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
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>
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:
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 |
<esri:FeatureLayer ID="ThreatAreas"
Url="http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/HomelandSecurity/operations/FeatureServer/2"
AutoSave="True"
ValidateEdits="True" />
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 Runtime SDK 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;
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.
if (editor.Add.CanExecute(11001))
editor.Add.Execute(11001);
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 (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");
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);
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);
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);
Union creates a single feature out of the selected features.
if (editor.Union.CanExecute(null))
editor.Union.Execute(null);
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);
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);
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.