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 or layers. While it's possible to work directly with the graphics in the layer, the Editor provides editing commands that can help you get the editing workflow in place with less code. The following sections provide information on using the Editor to create an editing application:

• Basis of the editing application
• Setting up the Editor and its properties
• Save and validation settings for edits
• Using Editor commands
  • Adding features
  • Selecting features
  • Deleting features
  • Modifying features
  • Saving edits
  • Canceling edits

Basis of the editing application

While your editing application can be as simple or complex as necessary, 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 that 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 user interface (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 you're working in XAML with the Editor as a resource, this needs 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 the properties available to customize the Editor's behavior; only the Map property is required:

Editor property	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 AutoComplete fills in the rest of the polygon based on snapping to nearby features. Default: False
AutoSelect	AutoSelect allows 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—Requires the user to make a selection, then performs the union with that selection (GraphicsLayer only supported with the SelectionMode is Point or Rectangle). Default: False
ContinuousMode	If ContinuousMode is true, commands (such as Add, Select, and so on) stay active until this value is set to false, CancelActive is executed, or another command is enabled. Default: False
Freehand	Indicates whether the Editor is using freehand draw mode when using the Add, Reshape, Union, and Cut commands. Once drawing is started during freehand draw mode, 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 are 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. This is done by allowing your selected point to jump (or snap) to edges, vertices, and other geometric elements when they're within the 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 specifies if it automatically saves edits back to the server and whether 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 property	Description
AutoSave	Gets or sets whether edits to the layer's graphics collection are auto-submitted to the service. Default: True
ValidateEdits	Shows whether edits are validated. If true, exceptions are thrown on attribute value changes if the value does not match the field type or if it does not fall into the field domain. Default: True

For example, the following FeatureLayer automatically saves edits and validates the 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. Consequently, 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. The available commands (including functionality for adding features, selecting features, deleting features, modifying features, saving edits, and canceling edits) are as follows:

• Add—Draws and adds new graphics.
• CancelActive—Cancels the active command on the map.
• ClearSelection—Unselects 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. 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's 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) as well as to execute each command.

All of the commands are based on ICommand, and 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 whether a Union can be performed, and if it can, 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 features

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, which depends on the type of layer you're editing. When working with a GraphicsLayer, Add takes an ESRI.ArcGIS.Client.Symbols.Symbol. When adding features to a FeatureLayer, the required parameter is a specific template or type ID.

To determine the value when working with a FeatureLayer, see the service's web page; 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-Meteorological 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-Meteorological 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 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 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 to the Select command. With the rich touch experience expected in Windows Phone applications, this is not a recommended setting. 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. To remove features based on interaction with the map, use the Select command with the Remove parameter.

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

To clear the entire selection, call ClearSelection, which has no required parameter.

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

If you're working with a FeatureLayer, the layer 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 (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 following example sets the selection color to match the phone's accent color:

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

Deleting features

To delete features, select the features to delete and call DeleteSelected. It has no required parameter.

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

Modifying 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. Vertices can be added along lines by tapping the lines, then tapping again to add the vertices. Vertices can be added to polygons by tapping the perimeter, 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, and updated by interacting with the feature while the vertices are displayed. A location outside of the feature is 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 execute. Once a selection is made, those commands will act on that selection.

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

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

When the code executes, the application waits for the user to draw a line on the map, which is used to cut the features into multiple features.

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

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

When the code executes, the application waits for the user to draw a line on the map, which is used in the reshaping. It acts on a single type of feature at a time. If the selection includes multiple feature types, it only acts 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, the features in the current selection are merged into a single feature. If features of multiple types are selected, the created union feature matches 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 the Save and validation settings for edits section), 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 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. If you're in the middle of an edit, the changes made up to that point 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 another 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.