Using the Editor

If you have a map with one or more GraphicsLayers or editable FeatureLayers in it, you can use the Editor to select, add, and modify features in the layer(s). While it is possible to directly work with the graphics in the layer, the Editor provides editing commands which help you get the editing workflow in place with less code. This topic provides information on using the Editor to create an editing application, including the following steps:

• Setting up the Editor and its properties
• Save and validation settings for edits
• Using Editor commands
  • Adding new features
  • Selecting features
  • Deleting existing features
  • Modifying existing features
  • Saving edits
  • Canceling edits

Basis of the editing application

While your editing application can be as simple or complex as you need, the code in this topic assumes that you have an existing application with a map, including an editable FeatureLayer, and that you are adding editing functionality. The application is assumed to have a map similar to the following:

<esri:Map x:Name="MyMap" Extent="-13054165,3850112,-13027133,3863559" >
    <esri:ArcGISTiledMapServiceLayer ID="BaseLayer" 
        Url="http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer" />
    <esri:FeatureLayer ID="ThreatAreas"  
        Url="http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/HomelandSecurity/operations/FeatureServer/2" />
</esri:Map>

In the above code, the ThreatAreas FeatureLayer is an editable polygon layer which the application is going to edit.

Setting up the Editor and its properties

Once the layer is ready for editing, an Editor that will act on the layer needs to be defined. It can be defined in XAML or in code-behind. When working in XAML, it needs to be defined as a resource since it is not a UI element. See the following example Editor definition, specifying that the ThreatAreas FeatureLayer should be edited, and also a Geometry service to use with the Cut, Union, and Reshape commands:

<Grid x:Name="LayoutRoot" Background="Transparent">
    <Grid.Resources>
        <esri:Editor x:Key="MyEditor" 
            LayerIDs="ThreatAreas"
            GeometryServiceUrl="http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer" />

The Map property on the Editor is required. However, if working in XAML with the Editor as a resource, this will need to be set in the code-behind as follows:

ESRI.ArcGIS.Client.Editor editor = LayoutRoot.Resources["MyEditor"] as Editor;
editor.Map = MyMap;

The following table lists all the properties available to customize the Editor's behavior; only the Map property is required:

Editor propery	Description
AutoComplete	Indicates if auto completion is enabled when adding polygons to a FeatureLayer. When AutoComplete is enabled, you draw a line instead of a polygon, and the autocomplete will fill in the rest of the polygon based on snapping to nearby features. Default: false
AutoSelect	AutoSelect will allow commands that require an active selection to be executed even though no features have been selected. Instead the selection is done using the interaction for the command. The following commands use AutoSelect, as described: Cut: Uses the cut line to select features and to perform the cut (FeatureLayer only). Reshape: Uses the reshape line to select features and to perform the reshape (FeatureLayer only). Union: asks the user to perform a selection and then does the union with that selection (GraphicsLayer only supported with the SelectionMode is Point or Rectangle). Default: false
ContinuousMode	If ContinuousMode is true, commands like Add, Select, and so on will stay active until this value is set to false, CancelActive is executed, or another command is enabled. Default: false
Freehand	Indicates whether this Editor is using freehand draw mode when using the Add, Reshape, Union and Cut commands. During freehand draw mode, once drawing is started, the movement across the map is tracked and turned into vertices. When freehand draw mode is disabled, vertices are added when the map is tapped. Default: false
GeometryServiceUrl	A URL to a geometry service for the Editor to use. Cut, Union, and Reshape commands require a Geometry service and will be disabled if one is not set. This property is optional and has no default.
IsTouchMagnifierEnabled	A boolean indicating whether a magnifier window opens to show a finer area of detail when editing with touch gestures. Default: true
LayerIDs	The IDs of the layers that the Editor will work on. Default: all GraphicsLayers in the Map
Map	The map the Editor works on. This property is required and has no default.
SelectionMode	The selection mode used with the selection tool. Only DrawMode.Point and DrawMode.Rectangle are supported on a GraphicsLayer. Default: Rectangle
SnapDistance	The snap radius, in pixels. Snapping allows you to create features that connect to each other so your edits are more accurate, with fewer errors, by allowing your selected point to jump, or snap to, edges, vertices, and other geometric elements when within this specified number of pixels. This is often set in XAML as a property on the associated Map. Default: 15
SnapKey	The key that, when pressed, activates snapping. This is often set in XAML as a property on the associated Map. Default: Ctrl

Save and validation settings for edits

The FeatureLayer itself specifies if it automatically saves edits back to the server and also if the edits are validated. This allows you, as a developer, to have different save and validation settings for each FeatureLayer that is editable. Both properties, as detailed in the following table, can be specified on the FeatureLayer in XAML:

FeatureLayer propery	Description
AutoSave	Gets or sets the whether edits to the layer's graphics collection are auto-submitted to the service. Default: true.
ValidateEdits	Whether edits are validated. If true, exceptions will be thrown on attribute value changes if value does not match field type or if it does not fall into the field domain. Default: true.

For example, the following FeatureLayer will automatically save edits and will validate edits as they are made:

<esri:FeatureLayer ID="ThreatAreas"  
    Url="http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/HomelandSecurity/operations/FeatureServer/2"                  
    AutoSave="True" 
    ValidateEdits="True" />

Note:

A GraphicsLayer is unable to send updates back to the server, as discussed in Editing GraphicsLayers vs. FeatureLayers. As such, it doesn't have these properties or settings.

Using Editor commands

Once a layer is ready for editing and an Editor is ready to edit that layer, the commands available on the editor can be used to edit the data. These commands that are available, including functionality for adding new features, selecting features, deleting existing features, modifying existing features, saving editsand canceling edits, are as follows:

• Add—draw and add new graphics.
• CancelActive—cancel the active command on the map.
• ClearSelection—unselect all graphics.
• Cut—uses a geometry service to cut graphics along a user-defined line.
• DeleteSelected—deletes selected graphics. If graphics are associated with an editable feature layer, features are deleted from the database.
• EditVertices—edits the vertices of any graphic clicked by the user.
• Reshape—uses a geometry service to reshape graphics with a user-defined line.
• Save—commits unsaved edits in all feature layers.
• Select—allows the user to select graphics.
• Union—uses a geometry service to union graphics selected by the user.

When working with the ArcGIS API for Windows Phone, the commands are used in the code-behind. First, a reference to the Editor must be obtained if it was defined as a resource in the XAML:

ESRI.ArcGIS.Client.Editor editor = LayoutRoot.Resources["MyEditor"] as Editor;

Note:

It is common to define an Editor variable in the scope of the PhoneApplicationPage's class. It can then be used when setting the Editor's Map property (shown above) and also to execute each command.

All of the commands are based on ICommand, and as such each has both a CanExecute method and an Execute method. CanExecute determines if the command can be used, while Execute runs the command. For example, the following code shows checking if a Union can be performed, and if so, executing a Union.

if (editor.Union.CanExecute(null))
    editor.Union.Execute(null);

In the example above, null is used as the parameter to the CanExecute and Execute methods. For Union, the selection in the map is used as the input, so no parameter is required. Other commands, such as Add, require a parameter to execute.

Adding new features

New features can be added by using the Editor's Add command. It takes a single property indicating the type of feature or graphic to add to the map, and which depends on the type of layer you are editing. When working with a GraphicsLayer, Add takes an ESRI.ArcGIS.Client.Symbols.Symbol. When adding features to a FeatureLayer, the parameter required is a specific template or type ID.

To determine the value when working with a FeatureLayer, see the service's web page, and the value is the ID from the Types section. See Finding information about a service for more information about the service's page. For example, to add a Hydro-Meteorlogical feature to the service at http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/HomelandSecurity/operations/FeatureServer/2, the parameter will be 11001.

The following code tests if a Hydro-Meteorlogical feature can be added, and if so, adds one:

if (editor.Add.CanExecute(11001))
    editor.Add.Execute(11001);

When the code executes, it traps draw events on the map in order to create the geometry of the feature being added. If the Editor's ContinuousMode is set to true, it will continue adding features based on draw events until a different command is selected.

Selecting features

The editing commands for deleting (DeleteSelected), along with a number of the modification commands (Cut, Reshape, and Union) work on a selection of features. For these commands to execute, there must be a selection of features on which they will operate. Selections are created and modified using the Select and ClearSelection commands. When the Select code executes, it traps tap events on the map in order to update the selection. If the Editor's ContinuousMode is set to true, it will continue updating the selection (as specified by the parameter) until a different command is selected.

Features are selected with the Select command, passing in either the "New" or "Add" parameter. If "New" is passed, the selection is cleared and the next feature clicked is used to start a new selection.

if (editor.Select.CanExecute("New"))
    editor.Select.Execute("New");

If "Add" is passed, the selected features are added to the existing selection, starting a selection if one does not yet exist.

if (editor.Select.CanExecute("Add"))
    editor.Select.Execute("Add");

Features can also be selected using keyboard-mouse combinations if "Keyboard" is passed into the Select command. With the rich touch experience expected in Windows Phone applications, this is not a recommended setting for Windows Phone applications. However, it is the default value for the Select command.

Features are removed from the selection using either the Select command and the "Remove" parameter or by using the ClearSelection command. If you want to remove features based on interaction with the map, use the Select command, called with the "Remove" parameter.

if (editor.Select.CanExecute("Remove"))
    editor.Select.Execute("Remove");

If you need to clear the entire selection, call ClearSelection, which has no required parameter:

if (editor.ClearSelection.CanExecute(null))
    editor.ClearSelection.Execute(null);

If you are working with a FeatureLayer, the layer itself provides information about selections done on it. It has properties for the number of features (SelectionCount) as well as to get access to the selected features themselves (SelectedFeatures).

FeatureLayer featureLayer = MyMap.Layers["ThreatAreas"] as FeatureLayer;

MessageBox.Show("# selected: " + featureLayer.SelectionCount);

foreach (Graphic graphic in featureLayer.SelectedGraphics)
{
    // work with your selected graphics
}

SelectionColor allows you to specify the color to use for the selection. The example below sets the selection color to match the phone's accent color:

featureLayer.SelectionColor = Application.Current.Resources["PhoneAccentBrush"] as Brush;

Deleting existing features

Deletion of features is done by selecting the features to delete and then calling DeleteSelected. It has no required parameter:

if (editor.DeleteSelected.CanExecute(null))
    editor.DeleteSelected.Execute(null);

Modifying existing features

Features that are already part of the layer being edited can be updated using the EditVertices, Cut, Reshape, and Union commands.

EditVertices doesn't require a selection, and works on the next feature tapped on the map, allowing the user to move the complete feature or update individual vertices.

if (editor.EditVertices.CanExecute(null))
    editor.EditVertices.Execute(null);

When the code executes, editing of a feature is activated by tapping that feature. Its vertices will appear, and they can be moved by dragging them. New vertices can be added along lines by tapping on the lines and then tapping again to add the vertices, and new vertices can be added to polygons by tapping on the perimeter and then tapping again to add the vertices. The entire feature can be moved by dragging it. In ContinuousMode, a feature is tapped to activate display of its individual vertices, updated by interacting with the feature, and then a different location tapped to complete the edit. Then the next feature can be tapped and updated. If the Editor's ContinuousMode is set to true, it will continue interacting with features tapped on the map until a different command is selected.

A selection is required to modify features using Cut, Reshape, or Union. If there is no selection, those commands will not be able to execute. Once a selection is made, these commands will act on that selection.

Cut allows the user to draw a line on the map which will be used to cut the selected features into new features.

if (editor.Cut.CanExecute(null))
                editor.Cut.Execute(null);

When the code executes, the user then draws a line on the map that is used to cut the features into multiple features.

Reshape allows the user to draw a line on the map which will then be used to reshape the selected features.

if (editor.Reshape.CanExecute(null))
    editor.Reshape.Execute(null);

When the code executes, the user then draws a line on the map that is used in the reshaping. It acts on a single type of feature at a time. If the selection includes multiple feature types, it will only act on the first type of feature added to the selection.

Union creates a single feature out of the selected features.

if (editor.Union.CanExecute(null))
    editor.Union.Execute(null);

When the code executes, all the features in the current selection are merged into a single feature. If features of multiple types are selected, the created union feature will match the type of the first feature added to the selection.

Saving edits

Once edits to a FeatureLayer are made, they need to be saved to the server. If your FeatureLayer layer has AutoSave set to true (as discussed in Save and validation settings for edits) then the edits are automatically saved to the server and no additional save is required. If instead you have AutoSave set to false on your layer, you will need to save your edits by calling the Save command. Executing the Save command doesn't require any parameters, as shown in the following code:

if (editor.Save.CanExecute(null))
    editor.Save.Execute(null);

Note:

GraphicsLayers do not support saving back to the server; GraphicsLayer edits are only available in the client.

Canceling edits

When editing, mistakes can be made, and edits then need to be cancelled. When in the middle of an edit, the changes taken so far can be cancelled with the CancelActive command. This command cancels the active command on the map, removing any edits made with that command. Executing the CancelActive command doesn't require any parameters, as shown in the following code:

if (editor.CancelActive.CanExecute(null))
    editor.CancelActive.Execute(null);

Note:

The CancelActive command is only active if any other command is currently waiting for user input.

If your FeatureLayer has AutoSave set to false, you can also cancel the commitment of edits to the service by not calling the Save command. If your FeatureLayer has AutoSave set to true, your edits have already been pushed to the server, and those edits cannot be cancelled.