Editor

Supported with:
Library dependencies: System, SystemUI, Geometry, Display, Server, Output, Geodatabase, GISClient, ArcWeb, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, DataSourcesNetCDF, GeoDatabaseDistributed, GeoDatabaseExtensions, Carto, NetworkAnalysis, Location, GeoAnalyst, Animation, Maplex, Geoprocessing, NetworkAnalyst, Schematic, SpatialAnalyst, 3DAnalyst, GlobeCore, Publisher, TrackingAnalyst, Framework, GeoDatabaseUI, DisplayUI, OutputUI, Catalog, CatalogUI, CartoUI, DataSourcesRasterUI, ArcCatalogUI, ArcCatalog, ArcMapUI, ArcMap, AnimationUI

Additional library information: Contents, Object Model Diagram

The Editor library implements ArcMap's object editor. The editor supports the editing of simple features, network features, annotations, and topological features, along with attributes for all these features. The library supports both a user interface and a programming API. The API provided by the Editor is a higher level API to that of the GeoDatabase library. Developers are encouraged to use the Editor API when editing and manipulating features in the geodatabase.
 
Developers can extend the library with their own editing commands, edit tasks, and snap agents. For more advanced customization developers can create extensions to the editor. The object inspector interface is implemented by the Editor library; however, to extend this user interface a Class Extension is implemented by extending the GeoDatabase library for the appropriate data source.

The objects that implement this functionality are grouped into a number of library subsystems. These library subsystems are:

Editor
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.
 

Edit Session

All editing takes place during an edit session. Only layers belonging to a single workspace can be edited at one time; all layers added to a map that 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 additional samples in this topic, must have a reference to the editor extension passed in. The first subroutine below shows how to obtain a reference to the editor.

[VB.NET] 
 Public Sub GetEditorReference()
        'get editor extension
        Dim editorUID As UID
        editorUID = New UID
        editorUID.Value = "esriEditor.Editor"
        Dim editor As IEditor
        editor = (m_application.FindExtensionByCLSID(editorUID))

        'Call the StartEditing method (see below)
        Me.StartEditing(editor)
End Sub

[C#] 
public void GetEditorReference()
{
    //get editor extension
    UID editorUID = new UID();
    editorUID.Value = "esriEditor.Editor";
    IEditor editor = m_application.FindExtensionByCLSID(editorUID) as IEditor;
    //Call the StartEditing method (see below)
    this.StartEditing(editor);
}
The following sample code determines the edit workspace the first feature layer belongs to and starts an edit session on it.
[VB.NET] 
Public Sub StartEditing(ByVal editor As IEditor)
        Dim mxDocument As IMxDocument
        mxDocument = m_application.Document
        Dim map As IMap
        map = mxDocument.FocusMap
        'If an edit session has already been started exit
        If editor.EditState <> esriEditState.esriStateNotEditing Then
            Return
        End If
        'Start editing the workspace of the first feature layer you find
        Dim layerCounter As Integer
        For layerCounter = 0 To map.LayerCount - 1 Step layerCounter + 1
            Dim currentLayer As ILayer
            currentLayer = map.Layer(layerCounter)
            If TypeOf currentLayer Is IFeatureLayer Then
                Dim featureLayer As IFeatureLayer
                featureLayer = currentLayer
                Dim dataset As IDataset
                dataset = featureLayer.FeatureClass
                editor.StartEditing(dataset.Workspace)
                Return
            End If
        Next
End Sub

[C#] 
public void StartEditing(IEditor editor)
{
    IMxDocument mxDocument = m_application.Document as IMxDocument;
    IMap map = mxDocument.FocusMap;
    //If an edit session has already been started exit
    if (editor.EditState != esriEditState.esriStateNotEditing)
    {
        return;
    }
    //Start editing the workspace of the first feature layer you find
    for (int layerCounter = 0; layerCounter < map.LayerCount; layerCounter++)
    {
        ILayer currentLayer = map.get_Layer(layerCounter);
        if (currentLayer is IFeatureLayer)
        {
            IFeatureLayer featureLayer = currentLayer as IFeatureLayer;
            IDataset dataset = featureLayer.FeatureClass as IDataset;
            editor.StartEditing(dataset.Workspace);
            return;
        }
    }
}
The Start Editing command on the Editor menu performs similarly.

Edit commands, tools, tasks, and extensions

Edit Commands

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. The editor uses commands for all operations that do not require the user to click on the map. 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. 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.
 

Edit 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 editing 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. An example of a custom tool that can be created and added to the Editor toolbar is a Fillet tool. A Fillet tool asks the user to select two segments and then create a fillet line between them based on a radius value.
 

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 Extensions

The editor ships with several extensions, including the Attribute Window extension, the Digitizer extension, the Annotation Edit 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.
The difference between editor extensions and other customizations is that extensions are automatically loaded and unloaded by the application; there is only ever one instance of an extension running at a time. 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. More info about edit events can be found in the 'How to listen to edit events' document.

Edit Sketch and Edit Sketch extensions
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.

[VB.NET] 
Public Sub AddPoint(ByVal editor As IEditor)
        Dim editSketch As IEditSketch
        editSketch = editor
        Dim lastPoint As IPoint
        lastPoint = editSketch.LastPoint
        If lastPoint Is Nothing Then
            Return
        End If
        lastPoint.PutCoords(lastPoint.X + 50, lastPoint.Y + 50)
        editSketch.AddPoint(lastPoint, True)
        editSketch.FinishSketch()
End Sub

[C#] 
public void AddPoint(IEditor editor)
{
    IEditSketch editSketch = editor as IEditSketch;
    IPoint lastPoint = editSketch.LastPoint;
    if (lastPoint == null)
    {
        return;
    }
    lastPoint.PutCoords(lastPoint.X + 50, lastPoint.Y + 50);
    editSketch.AddPoint(lastPoint, true);
    editSketch.FinishSketch();
}

Edit Sketch 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 and Edit operations

Sketch Operations

Sketch operations are a type of operation that can be put on the document’s 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 using sketch operations so that each action is undoable. Code that modifies the edit sketch should be placed between calls to ISketchOperation::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 you right-click a vertex 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 any part of the edit sketch opens the edit sketch context menu.
The best place for commands and macros that work with the edit sketch is on the edit sketch context menu, so they can be easily executed after right-clicking the edit sketch.

[VB.NET] 
Public Sub DeleteEditSketchVertex(ByVal editor As IEditor)
      Dim editSketch As IEditSketch
      If editor Is Nothing Then Exit Sub
      editSketch = CType(editor, IEditSketch)
      Dim lastVertexIndex As Integer
      lastVertexIndex = editSketch.Vertex
      If lastVertexIndex = -1 Then
          Return
      End If
      Dim sketchOperation As ISketchOperation
      sketchOperation = New SketchOperation
      sketchOperation.MenuString_2 = "Delete Vertex"
      sketchOperation.Start(editor)
      Dim pointCollection As IPointCollection
      pointCollection = editSketch.Geometry
      pointCollection.RemovePoints(lastVertexIndex, 1)
      editSketch.RefreshSketch()
      sketchOperation.Finish(editSketch.Geometry.Envelope)
End Sub

[C#] 
public void DeleteEditSketchVertex(IEditor editor)
{
    IEditSketch editSketch = editor as IEditSketch;
    //Get the vertex that was last right-clicked 
    int lastVertexIndex = editSketch.Vertex;
    if (lastVertexIndex == -1)
    {
        //no vertex
        return;
    }
    //Create a sketch operation to get undo/redo capabilities 
    ISketchOperation sketchOperation = new SketchOperation();
    //Give the operation a name 
    sketchOperation.MenuString_2 = "Delete Vertex";
    //Start the operation
    sketchOperation.Start(editor);
    //Delete the point from the edit sketch and refresh 
    IPointCollection pointCollection = editSketch.Geometry as IPointCollection;
    pointCollection.RemovePoints(lastVertexIndex, 1);
    editSketch.RefreshSketch();
    //Finish the operation to add it to the operation stack   
    sketchOperation.Finish(editSketch.Geometry.Envelope);
}

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 simplicities 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 features are deleted as well.

[VB.NET] 
Public Sub DeleteFeatures(ByVal editor As IEditor)
        Try
            If editor.SelectionCount = 0 Then
                Return
            End If
            editor.StartOperation()
            Dim selectedFeatureList As IEnumFeature
            selectedFeatureList = editor.EditSelection
            selectedFeatureList.Reset()
            Dim currentFeature As IFeature
            currentFeature = selectedFeatureList.Next
            While Not (currentFeature Is Nothing)
                currentFeature.Delete()
                currentFeature = selectedFeatureList.Next
            End While
            editor.StopOperation("Delete Features")
            Dim activeView As IActiveView
            activeView = editor.Map
            editor.Map.ClearSelection()
            activeView.PartialRefresh(esriViewDrawPhase.esriViewGeography + esriViewDrawPhase.esriViewGeoSelection, Nothing, Nothing)
            
        Catch
            editor.AbortOperation()
        End Try
 End Sub

[C#] 
public void DeleteFeatures(IEditor editor)
{
    try
    {
        //Check the editor’s selection
        if (editor.SelectionCount == 0)
        {
            //nothing selected, thus nothing to delete
            return;
        }
        //Start an edit operation
        editor.StartOperation();
        //Delete each selected feature
        IEnumFeature selectedFeatureList = editor.EditSelection as IEnumFeature;
        selectedFeatureList.Reset();
        IFeature currentFeature = selectedFeatureList.Next();
        while (currentFeature != null)
        {
            //Use DeleteSet() for features out of a geodatabase.
            //This will ensure all related features are deleted as well.
            currentFeature.Delete();
            currentFeature = selectedFeatureList.Next();
        }
        //Complete the edit operation
        editor.StopOperation("Delete Features");
        //Refresh the display
        IActiveView activeView = editor.Map as IActiveView;
        //TODO refresh
        //activeView.Refresh();
        editor.Map.ClearSelection();
        activeView.PartialRefresh(esriViewDrawPhase.esriViewGeography | esriViewDrawPhase.esriViewGeoSelection, null, null);
        editor.Map.ClearSelection();
        activeView.PartialRefresh(esriViewDrawPhase.esriViewGeography, null, null);
    }
    catch
    {
        //Abort the edit operation if any error occurs
        editor.AbortOperation();
    }
}

Feature Inspectors
The ArcMap Attribute dialog box 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.
 
ArcMap 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 box activates the associated feature inspector in the right panel.

Annotation and Dimension Constructors

Annotation Constructors

Annotation constructors make use of an edit sketch extension to create new geodatabase annotation features.  An annotation constructor controls the display feedback that a user sees when creating a new annotation feature and constrains the construction in a certain way.  For example, when constructing a new annotation feature, you can control the number of points that must be entered before the construction may be finished, or if existing vertices may be deleted.  Annotation constructors use pre-sketch feedback to display text before the initial point is added to the sketch.  Annotation constructors must implement the IAnnotationConstructor interface and be registered in the 'ESRI Annotation Constructors' component category.
 

Dimension Constructors

Dimension constructors use edit sketch extensions to create new dimension features.  A dimension constructor controls the display feedback that a user sees when creating a new dimension feature and constrains the construction in some way. Dimension constructors must implement the IDimensionConstructor interface and be registered in the 'ESRI Dimension Constructors' component category.

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. Implementing the optional ISnapAgentFeedback interface will display a text string when a snap agent's ISnapAgent::Snap method returns True, alerting the user which snap agent used to modify the coordinates of the point. 
 
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 cycle through all of the features in the cache and check to see if any fall within the editor’s snap tolerance.