ArcMap Editor Object Model Overview

ArcMap Editor Object Model

Introduction:

The ArcMap editing toolbar is an extension to the ArcMap application that provides a unified editing and mapping environment for features stored in all types of vector geographic datasets; geodatabases, coverages and shapefiles.

The ArcMap editing toolbar consists of tools for editing and maintaining GIS databases. These are some important functions of these tools:

CAD-like tools for feature construction and editing
Rule-based feature validation
Multi-layer feature snapping
Undo/redo capabilities
Multi-user editing and versioning

The ArcMap editing toolbar is built on an underlying framework or object model comprised of COM components that you can program to customize the users editing environment. Developers can use these objects to create new custom tools, constrain or remove existing tools, or enforce application-specific behavior using custom tasks or edit event notifications implemented using custom extensions.

The primary object in the editor framework is the Editor object. The Editor object exposes many interfaces including: IEditor, IEditLayers, IEditEvents, IEditProperties, IEditSketch, and ISnapEnvironment. Each interface manages a logical grouping of editing functionality. The remainder of this document reviews the model for extending the editing environment.

Implementing Edit Operations

Edit operations typically occur through one of four methods; commands, tools, tasks, and edit event notifications.

Commands perform edits without the user having to click on the map. For example, the Buffer command creates new features by buffering the selected features.
Tools require user interaction. For example, the Split tool requires the user to locate the point where the split will occur.
Edit tasks require an input geometry to perform their edits. For example, the Reshape task uses a sketch geometry to modify a selected feature’s shape.
Edit events are notifications that occur during an edit session and edit event listeners are any objects that respond to the events. For example, the target layer control on the Editor toolbar responds to the IEditEvents::OnCurrentLayerChanged event so that it can update itself when the target layer is set programmatically.

Editor commands:
The editor uses commands for all operations that do not require the user to click on the map. Examples of editor commands include the Buffer, Intersect, and Union commands. Commands may prompt the user for input using a dialog, but none of them require the user to interact with the display. Most editor commands reside on the Editor pulldown menu.

All commands implement the ICommand interface. For more details on creating custom commands, read chapter 3, ‘Customizing the user interface’.

An example of a custom editor command that a developer could create is a Difference command. Such a command could create new features based on the overlapping regions of two selected features. The code samples provided in your ArcGIS software installation contains examples of how to create custom editor commands like this.

Editor tools:
All operations that require the user to interact with the display are called tools. The Sketch tool, the Rotate tool, and the Split tool are all examples of editor tools. Tools require that the user click on the map to complete the desired operation. Tools generally reside directly on the editor toolbar.

All tools implement the ITool and ICommand interfaces. Again, for more details on creating custom tools, read chapter 3, ‘Customizing the user interface’. An example of a custom tool that could be created and added to the Editor toolbar is a Fillet tool. A Fillet tool would ask the user to select two segments and then create a fillet line between them based on a radius value. The code samples on your ArcGIS installation contains many examples of how to create a custom edit tool.

Edit tasks:
For edit operations that require an input geometry, the editor uses edit tasks. Edit tasks are components that acquire the geometry stored in an edit sketch and perform a specific operation with it. For example, the Reshape task uses the sketch geometry to alter the shape of a selected feature. Edit tasks are managed by the Editor object and one is always active. The current task is set using the IEditor::CurrentTask property.

All edit tasks implement the IEditTask interface and are registered in the 'ESRI Edit Tasks' component category. An example of a custom edit task might be a Measure task that simply reports the length of a line created in the edit sketch. The benefit of such a task would be that the user could digitize an accurate line using sketch tools and snapping instead of just clicking on the map. All edit tasks appear in the Current Task dropdown list on the Editor toolbar.

Edit events:
Edit events are specific notifications that occur during editing. Edit event listeners are objects that listen for and respond to edit events. For example, a specific edit event is fired each time a new feature is created and a custom object could perform automatic feature validation after receiving this notification.

Edit Session

All editing takes place during an edit session. Only layers belonging to one workspace can be edited at a time; all of the layers that have been added to a map and belong to the same workspace can be edited simultaneously.

To specify a workspace to edit, use IEditor::StartEditing. You can get a reference to the current edit workspace with IEditor::EditWorkspace.

The following sample determines the workspace the first feature layer in the map belongs to and starts an edit session on it. Note that this sample, and all following samples in this chapter, must have a reference to the editor extension passed in. The first subroutine below shows how to obtain a reference to the editor.

Public Sub GetEditorReference()
  Dim pEditor As IEditor
  Dim pID As IUID
  
  Set pID = New UID
  pID = "esriCore.Editor"
  Set pEditor = Application.FindExtensionByCLSID(pID)
  'Call the StartEditing routine
  StartEditing pEditor
End Sub

The following sample code determines the edit workspace the first feature layer belongs to and starts an edit session on it.

Public Sub StartEditing(pEditor As IEditor)
  Dim pMxDoc As IMxDocument
  Dim pMap As IMap
  Dim pFeatureLayer As IFeatureLayer
  Dim pDataset As IDataset
  Dim LayerCount As Integer
  
  Set pMxDoc = Application.Document
  Set pMap = pMxDoc.FocusMap
  
  'If an edit session has already been started exit
  If Not pEditor.EditState = esriStateNotEditing Then Exit Sub

  'Start editing the workspace of the first featurelayer you find
  For LayerCount = 0 To pMap.LayerCount - 1
    If TypeOf pMap.Layer(LayerCount) Is IFeatureLayer Then
      Set pFeatureLayer = pMap.Layer(LayerCount)
      Set pDataset = pFeatureLayer.FeatureClass
      pEditor.StartEditing pDataset.Workspace
      Exit For
    End If
  Next LayerCount
End Sub

The Start Editing command on the Editor menu performs similarly.

Edit sketch

The edit sketch contains a geometry that is used as input for completion of the current edit task. The type of sketch geometry may be a multi-point, a polyline, or a polygon. The current edit task sets the type of sketch geometry. The edit sketch is owned by the Editor object and accessed via the IEditSketch interface. Access to the edit sketch geometry is through the IEditSketch::Geometry property.

When the edit sketch is finished, the current editing 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 new Building feature.

Tools that add points to the sketch are called sketch tools. Any sketch tool or combination of sketch tools can be used to create a sketch geometry. For example, the Intersection tool and the Distance-Distance tool can be used interchangeably to add points to an edit sketch. A custom sketch tool is another example of a custom editor tool that can be created and added to the Editor toolbar.

The edit sketch has its own context menu that aids in manipulating the edit sketch geometry. Commands that appear on this menu include: Move, Move To, Insert, and Delete. Right-clicking on top of any part of the edit sketch invokes the edit sketch context menu no matter what the active tool is. Custom commands can be added to the edit sketch context menu through the Customize dialog.

To automatically add new commands to the edit sketch context menu, register commands in the ‘ESRI Sketch Menu Commands’ component category. Customize the sketch tool context menu in the same fashion except in this case register commands in the ‘ESRI SketchTool Menu Commands’ component category. Commands registered in these categories will appear at the top of their related menus. An interesting alternative when adding several commands to either category, is to instead add a single menu pull-right, see IMenuDef, that in turn lists the custom commands. A pull-right menu may be more attractive and will make ordering and managing the custom commands easier.

The following sample adds a new point to the end of an edit sketch and then completes the sketch. In this example, the new point is calculated at a delta x,y of 50 map units from the last point in the edit sketch. Once IEditSketch::FinishSketch is called, the geometry the edit sketch manages is sent to the current task.

Public Sub AddPoint(pEditor As IEditor)
  Dim pEditSketch As IEditSketch
  Dim pPoint As IPoint
  
  Set pEditSketch = pEditor 'QI
  Set pPoint = pEditSketch.LastPoint
  If pPoint Is Nothing Then Exit Sub
  pPoint.PutCoords pPoint.x + 50, pPoint.y + 50
  pEditSketch.AddPoint pPoint, True
  pEditSketch.FinishSketch
End Sub

EditSketch Extensions

Edit sketch extensions let programmers alter the edit sketch geometry and edit sketch display feedback mechanism. For example, a custom edit sketch extension may be written for a layer that contains two-point polylines. Such an extension can ensure that new features are restricted to two points when created and modified.

When constructing a new feature of this type, the edit sketch extension automatically finishes the sketch when a second point is added. When modifying the feature, inserting new vertices into the edit sketch is prevented unless the user has deleted a vertex and the point count is less than two.

The creation or modification of a dimension feature in a geodatabase uses edit sketch extensions; dimension features store complex geometry and the edit sketch extension is used to help the user create and modify complex dimension shapes in an intuitive manner.

Edit sketch extensions are created by implementing IExtension and IEditSketchExtension and registering the class in the 'ESRI Editor Extensions' component category.

Sketch operations

Sketch operations are a type of operation that can be put on the documents operation stack, IMxDocument::OperationStack. Any change to the edit sketch should happen within the context of a sketch operation.

For example, the Edit tool is able to move edit sketch vertices and does so using sketch operations so that each action is undoable. Code that modifies the edit sketch should be placed between calls to ISketchOperaton::Start and ISketchOperation::Finish.

IEditSketch::AddPoint adds a new vertex to the end of the edit sketch and it automatically creates a sketch operation. This case is an exception, there is no need to create an edit operation when using AddPoint.

The sample below deletes a vertex from the edit sketch. The sample relies on the IEditSketch::Vertex property to identify which vertex to delete. This property is set whenever a vertex is right-clicked on in the edit sketch. This is also the case for IEditSketch::Part and IEditSketch::Segment. If nothing has been right-clicked, a value of -1 is returned. Right-clicking on any part of the edit sketch reveals the edit sketch context menu.

The best place for commands and macros, such as the following, that work with the edit sketch is right on the edit sketch context menu so they can be easily executed after right-clicking on the edit sketch.

Public Sub DeleteEditSketchVertex(pEditor As IEditor)
  Dim pEditSketch As IEditSketch
  Dim pPointColl As IPointCollection
  Dim index As Long
  Dim pSketchOp As ISketchOperation
  
  Set pEditSketch = pEditor 'QI
  'Get the vertex that was last right-clicked
  index = pEditSketch.Vertex 
  If index = -1 Then Exit Sub ‘Exit if I don’t have a vertex

  'Create a sketch operation to get undo/redo capabilities
  Set pSketchOp = New SketchOperation
  pSketchOp.MenuString = "Delete Vertex" 'Give the operation a name
  pSketchOp.Start pEditor 'Start the operation

  'Delete the point from the edit sketch and refresh
  Set pPointColl = pEditSketch.Geometry
  pPointColl.RemovePoints index, 1
  pEditSketch.RefreshSketch

  'Finish the operation to add it to the operation stack
  pSketchOp.Finish pEditSketch.Geometry.Envelope
End Sub

Edit operations

Edit operations are very similar to sketch operations except that these are typically operations on features instead of the edit sketch. For example, if a feature is moved with the Edit tool, the operation can be undone and redone.

Edit operations are created using the IEditor interface by placing the code between calls to IEditor::StartOperation and IEditor::StopOperation.

The following sample deletes all of the selected features that are editable and does so within the confines of an edit operation so the delete can be undone. Note, for simplicity sake, this sample uses IFeature::Delete to delete each feature which is usually acceptable for Shapefile and Coverage features, but with geodatabase, you might want to use IFeatureEdit::DeleteSet as this will ensure all related feature are deleted as well. See the 'Delete Selected Features' editing tip for an example of this.

'Public Sub DeleteFeatures(pEditor As IEditor)
  On Error GoTo ErrorHandler:
  
  Dim pEnumFeature As IEnumFeature
  Dim pFeature As IFeature
  Dim pActiveView As IActiveView
  
  'Check the editor’s selection
  If pEditor.SelectionCount = 0 Then Exit Sub
  
  'Start an edit operation
  pEditor.StartOperation
  
  'Delete each selected feature
  Set pEnumFeature = pEditor.EditSelection
  pEnumFeature.Reset
  Set pFeature = pEnumFeature.Next
  Do While Not pFeature Is Nothing
    pFeature.Delete
    Set pFeature = pEnumFeature.Next
  Loop
  
  'Complete the edit operation
  pEditor.StopOperation "Delete Features"
  
  'Refresh the display
  pEditor.Map.ClearSelection
  Set pActiveView = pEditor.Map
  pActiveView.PartialRefresh esriViewGeography + _  
              esriViewGeoSelection, Nothing, Nothing
  
  Exit Sub 'Exit sub to avoid error handler

  ErrorHandler:
    'Abort the edit operation if any error occurs
    pEditor.AbortOperation
End Sub

Snap agents

The editor also maintains a snapping environment that contains several snapping agents useful for placing points. For example, FeatureSnapAgent can be configured to snap input points to the vertices of existing features.

All snap agents implement the ISnapAgent interface and are registered in the 'Editor Snap Agents' component category. A specific class of snap agent is the feature snap agent.

The sketch tools and other editing tools use feature snap agents to find features to snap to. The editor automatically instantiates a feature snap agent for each editable feature class the first time the snapping window is opened. The other snap agents such as Snap Perpendicular are also instantiated when the snapping window is first opened.

The snapping properties such as snap tolerance, snap tolerance units (map or pixel), and hit-type are managed by the ISnapEnvironment interface on the Editor object.

Snapping is performed by calling the ISnapEnvironment::SnapPoint method and passing it an IPoint. For example, the sketch tools get the current mouse location (IEditor::Location) and pass it to SnapPoint. SnapPoint in turn calls each snap agent’s ISnapAgent::Snap method until one of them returns True, which indicates that the snap agent has found a new point that meets its unique snapping criteria. The coordinates of the point are modified to reflect that of the new point location.

Feature snap agents use feature caches to create a small selected set of features in memory. The feature snap agents track the current mouse location and continually reinitializes a feature cache and fills it with the features that reside near this point. The snap agents then cycles through all of the features in the cache and checks to see if any of them are within the editor’s snap tolerance.

Editor extensions

The editor ships with four extensions: the Attributes Window extension, the Digitizer extension, the Topology Editor extension, and the Conflict Resolution extension. All editor extensions must implement the IExtension interface and be registered in the ESRI Edit Extensions component category. When an edit session begins, each editor extension is activated; when editing is complete, each editor extension is deactivated.

Custom editor extensions can be created and added to the editor. For example, a developer may choose to create a custom extension that controls feature validation throughout an edit session. Such an extension might listen for the edit events OnCreateFeature and OnChangeFeature and perform validation whenever these events are fired.

Feature Inspectors

The editor ships with a standard feature inspector which enables attribute editing. For any feature class in a geodatabase, you can replace the default feature inspector with a custom feature inspector. For example, you may want to create a custom feature inspector that displays a bitmap whenever a feature belonging to a specific feature class is selected.

Create custom inspectors by implementing the IObjectInspector interface and registering the class as a feature class’s feature class extension. Again, custom feature inspectors can only be assigned to feature classes in a geodatabase.

Only one feature inspector can be active for each feature class. When you create a custom feature inspector, you specify the specific feature classes that will use it. Selecting a feature in the left panel of the Attributes dialog activates the associated feature inspector in the right panel.

The editor’s attribute dialog contains two panels. The left panel lists the features from the map that have been selected and are editable. The features are listed under the feature class they belong to. Any related features are also listed in this panel underneath the selected feature they are related to. The right panel houses a feature inspector.