ArcGIS Engine editing

---

ArcGIS for Desktop editing functionality is delivered through the Editor library, whereas in ArcGIS Engine, it is contained within the Controls library. Both support a user interface (UI) and an application programming interface (API). 

Although the ArcGIS for Desktop editing environment is more feature rich, ArcGIS Engine provides many commands that offer similar functionality, such as the Editor menu, Sketch tool, Edit tool, Target Layer control, Edit Task control, Snapping dialog box, and Attribute dialog box. 

The primary editing object in the ArcGIS for Desktop environment is Editor, whereas in ArcGIS Engine, it is the EngineEditor singleton. In their respective applications, these objects are responsible for managing the edit sketch, current task, current target layer, edit workspace, edit selection, edit session properties, and snap environment. The following table shows the main editing interfaces for each type of application.

	ArcGIS Engine	ArcGIS for Desktop
Editing environment	IEngineEditor	IEditor
Edit tasks	IEngineEditTasks	IEditTasks
Edit sketch	IEngineEditSketch	IEditSketch
Edit layers	IEngineEditLayers	IEditLayers
Edit properties	IEngineEditProperties	IEditProperties
Edit events	IEngineEditEvents	IEditEvents

The fact that the interfaces are not shared between ArcGIS Engine and ArcGIS for Desktop makes it difficult to create individual components that work in both types of applications. You should maintain separate classes but share program logic in helper classes where appropriate.

All data editing should take place within an edit session except when an application bulk loads or bulk updates simple features using insert or update cursors. An edit session is used to implement a long transaction that can encapsulate both edit and sketch operations. Data changes made during an edit session can only be seen by the application that is performing the edit session. Data changes made by other concurrently executing applications (if allowed) are not seen until those edit sessions are saved. For more information on the correct rules of object editing on geodatabases see IWorkspaceEdit.

An edit session can be created using IEngineEditor (Controls) or IWorkspaceEdit (Geodatabase). The type of application determines the most appropriate approach. See the following:

The edit session can be started and stopped using the IEngineEditor.StartEditing and IEngineEditor.StopEditing methods, respectively. 

All edits made in an edit session should be performed within an operation. Edit operations can create, modify, or delete features, whereas sketch operations modify the edit sketch. Edit and sketch operations can be thought of as short transactions nested within the long transaction corresponding to the edit session. 

Operations provide the capability to undo or redo edits made in the edit session by adding each operation to the operation stack. Once the edit session is finished, all operations are removed from the operation stack. See the following screen shot:

For more information, see the following topics:

The target layer represents the IFeatureLayer currently being edited. Use IEngineEditLayers.SetTargetLayer to programmatically set the target layer for the Edit tool, Sketch tool, and any custom commands. Alternatively, provide the ControlsEditingTargetToolControl to allow the user to set the target layer as required. Use IEngineEditLayers.TargetLayer to return a reference to the layer being edited.

ArcGIS Engine edit tasks are components that acquire the geometry stored in an edit sketch, then perform a specific edit operation with it. The following two out-of-the-box edit tasks are provided:

It is also possible to create custom edit tasks by implementing the IEngineEditTask interface. For example, the Custom reshape polyline edit task sample shows an edit task that allows the user to perform a reshape on the selected feature. See the following screen shot:

Typically, edit tasks are registered in the ESRI Engine Edit Tasks component category, although they can be added programmatically using the IEngineEditor.AddTask method. 

Set or return the current edit task using the IEngineEditor.CurrentTask property. Alternatively, provide ControlsEditingTaskToolControl to allow the user to select the current edit task.

The edit sketch, which is managed using the IEngineEditSketch interface, contains a geometry that is used as input for completion of the current edit task. The type of sketch geometry can be a multipoint, polyline, or polygon and is set by the current edit task. For example, the Create New Feature task sets the edit sketch geometry type (esriGeometryType) to be the same as the geometry type of the target layer. Edit tasks often set the edit sketch geometry to esriGeometryNull, causing the sketch tool to become inactive. For example, the previously mentioned Custom reshape polyline edit task sample sets the edit sketch geometry to esriGeometryNull if a single polyline feature is not selected. This prevents users from creating an edit sketch that would otherwise do nothing.

When the edit sketch is finished, the current edit task takes the geometry stored in the edit sketch and performs a specific operation with it. For example, completing the sketch of a building outline when the current task is set to Create New Feature and the target layer is set to the Buildings feature class, creates a Building feature.

Access the edit sketch geometry using the IEngineEditSketch.Geometry property. Use either the sketch tool (ControlsEditingSketchTool) or the IEngineEditSketch.AddPoint method to add points to the edit sketch. Create an IEngineSketchOperation to programmatically modify the edit sketch. 

Two context menus are provided to aid manipulating the edit sketch geometry. The sketch context menu (ControlsEditingSketchContextMenu) is typically used with the Sketch tool in conjunction with the Create New Feature task. The edit vertex context menu (ControlsEditingVertexContextMenu) is typically used with the Edit tool in conjunction with the Modify Feature task. See the following screen shots:

Use the IEngineEditEvents interface to trap specific events that occur in an edit session. For example, custom validation code could be executed when a user completes the edit sketch by listening to the IEngineEditEvents.OnSketchFinished event. For more information, see How to listen to edit events.

The ControlsEditingAttributeCommand dialog box contains two panels as shown in the following screen shot. The left panel lists the features from the map that have been selected and are editable. The features are listed under the feature class to which they belong. Any related features are also listed in this panel under the selected feature to which they are related. The right panel contains a feature inspector that enables attribute editing. 

It is also possible to replace the default feature inspector with a custom feature inspector by implementing the IEngineObjectInspector interface and registering the class as a feature class extension.

Snap agents help position features and edit sketch vertices. They can be accessed using the ControlsEditingSnappingCommand or programmatically through the IEngineSnapEnvironment interface. Custom snap agents can be created by implementing the IEngineSnapAgent interface. See the following screen shot: