ArcGIS Engine editing

Summary This topic introduces the main editing components used to manage and extend the editing environment in an ArcGIS Engine application.

In this topic

Engine editing vs. ArcMap editing

ArcGIS 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 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 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 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
Although the interface names and their purpose are similar, they do not expose the exact same properties and methods. For example, the IEngineEditEvents interface effectively combines the events exposed on the IEditEvents and the IEditEvents2 interfaces.
The fact that the interfaces are not shared between ArcGIS Engine and ArcGIS 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.

Edit session

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:
  • Use IWorkspaceEdit to programmatically perform edits in console applications or graphical user interface (GUI)-based applications that do not require any user interaction.
  • Use IEngineEditor for GUI-based editing applications that involve any of the following:
    • Using out-of-the-box editing commands
    • Working with the edit sketch
    • Controlling the snapping environment
    • Listening to events that are raised while editing
The edit session can be started and stopped using the IEngineEditor.StartEditing and IEngineEditor.StopEditing methods, respectively. 

Edit and sketch operations

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:
 
Within the life span of the edit session, any sketch operations added to the operation stack are temporary. When the sketch is finished, sketch operations are removed and replaced with a single edit operation. When the edit session is finished, the operation stack is cleared.
For more information, see the following topics:

Editing target layer

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.
Using the ControlsEditingTargetToolControl automatically sets the target layer to be the first layer in the map when editing starts. When this control is not present, IEngineEditLayers.TargetLayer will be null until explicitly set.
Use the IEngineEditEvents.OnTargetLayerChanged event to detect when the target layer has been changed.

Edit tasks

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:
  • Create New Feature
  • Modify Feature
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:
Using the ArcGIS Add Class Wizard to extend ArcObjects helps you quickly create a class that implements IEngineEditTask. Choose Engine and Editor as the customization group, then choose Engine Edit Task as the base component.
The IEngineEditTask interface allows edit tasks to be logically grouped in the ControlsEditingTaskToolControl using the IEngineEditTask.GroupName property. This is not available for ArcGIS Desktop edit tasks.
Use the IEngineEditEvents.OnCurrentTaskChanged event to detect when the edit task has been changed.
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.

Edit sketch

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:
When using the ControlsEditingVertexContextMenu, set the mouse-clicked location first using the IEngineEditSketch.SetEditLocation method. An example of using these context menus is provided in the Feature editing with the control commands sample.

Edit events

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.

Feature inspectors

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.
Custom feature inspectors can only be assigned to feature classes in a geodatabase.

Snap agents

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:
 





Development licensing Deployment licensing
Engine Developer Kit Engine Runtime
ArcView
ArcEditor
ArcInfo