This document is archived and information here might be outdated.  Recommended version.


Editor framework customizations (ArcObjects .NET 10.6 SDK)
ArcObjects Help for .NET developers > Developing with ArcGIS > Learning ArcObjects > Extending ArcObjects > Editor framework customizations (ArcObjects .NET 10.6 SDK)

Editor framework customizations


Summary
This topic describes the types of editing customizations—and their respective deployment options—you can create using components.

This topic describes the editor customizations you can create with components. For information on how to create editor customizations with add-ins, see Customizing the editor framework using add-ins.
Creating and deploying your customizations as add-ins is the preferred method.

In this topic


Editor customizations and deployment options

The editing framework can be customized to add your own commands, tools, tasks, extensions, shape constructors, and object inspectors. For an overview of these customizations, see ArcGIS Desktop editing for developers.
Many of these customizations can be built and deployed as add-ins, while others require development of custom components. For more information on customizing using add-ins, see Building add-ins for ArcGIS Desktop. For general information on components, see Extending ArcObjects.
The following table shows the various editor customization types and their supported customization methods:
Customization type
Add-in
Component
Commands
Yes
Yes
  • Context menus
Yes
Yes
Tools
Yes
Yes
  • Construction tools
Yes
Yes
Extensions
Yes
Yes
Shape constructors
No
Yes
Tasks
No
Yes
Object inspectors
No
Yes
Snap agents
No
Yes
Edit sketch extensions
No
Yes

Commands

Creating an editor command follows the same workflow as outlined in Creating commands and tools.
A reference to the editor is usually obtained in the OnCreate method as a module level variable. You can enable the command based on the edit state in the command's Enabled property. The functionality of your command is placed in the OnClick method. See the following code example:
[C#]
private IEditor3 m_editor;
public override void OnCreate(object hook)
{
    m_application=hook as IApplication;
    //Get the editor.
    UID editorUid=new UID();
    editorUid.Value="esriEditor.Editor";
    m_editor=m_application.FindExtensionByCLSID(editorUid)as IEditor3;
}

public override void OnClick()
{
    //Developer code goes here.
}

public override bool Enabled
{
    get
    {
        return m_editor.EditState == esriEditState.esriStateEditing;
    }
}
[VB.NET]
Private m_application As IApplication
Public Overrides Sub OnCreate(ByVal hook As Object)
m_application=TryCast(hook, IApplication)
'Get the editor.
Dim editorUid As New UID()
editorUid.Value="esriEditor.Editor"
End Sub

Public Overrides Sub OnClick()
'Developer code goes here.
End Sub

Public Overrides ReadOnly Property Enabled() As Boolean
Get
Return m_editor.EditState=esriEditState.esriStateEditing
End Get
End Property

Context menus

All the items on the Editing menu, the Sketch Tool context menu, and the Edit Sketch context menu are implemented as commands. Most of these commands perform an edit operation, but a few, such as Snapping, open other controls.
Commands that you intend to use as menus must be implemented with the ICommand interface and follow the same pattern as if you were creating an editor command as previously described. For more information about menus, see Creating toolbars and menus.
Menu commands are registered in the following component categories:
  • ESRI EditTool Menu Commands for commands on the Edit Tools context menu
  • ESRI Sketch Menu Commands for commands on the Edit Sketch context menu
  • ESRI SketchTool Menu Commands for commands on the Sketch Tool context menu
A command registered in one of these categories automatically appears in its associated context menu. This prevents end users from having to set up their customized editing environment manually.

Tools

Editor tools are created to interact with the display. They can be divided into two main types, those that use the shape constructors (straight, arc, trace, right angle etc) to provide geometry and those that provide their own geometry (via tool events). Both these types can be further subdivided into two other subtypes, construction tools and non-construction tools. Construction tools are used to create new features and are found within the construction tools pane in the Create Features window. The polygon, polyline and rectangle tools are examples of construction tools whereas the split polygons tool is an example of regular or non-construction edit tool. It is important to understand what type of tool you wish to create as this will determine how you go about creating it.

Creating an edit tool that uses shape constructors

To build a tool that uses the shape constructors, you must create a tool component implementing ICommand, ITool, ISketchTool, and IShapeConstructorTool. Your custom tool forwards its mouse events (such as mouse move and mouse down) to the current shape constructor, which internally calls the editor's sketch tool. Your tool must also listen to the IEditEvents.OnSketchFinished event so you can obtain the edit sketch geometry (IEditSketch.Geometry) when you finish sketching and perform an edit operation.
A Visual Studio template is included with the software development kit (SDK) to help you create such a tool. You can also review the sample edit tool included in this topic. To create an edit tool component using the Visual Studio template, follow these steps:
  1. Start with an ArcMap Class Library Visual Studio project.
  2. Add a new item to the project and select Base tool from the ArcGIS Extending ArcObjects templates.
  3. Select Desktop ArcMap Edit Tool in the ArcGIS New Item Wizard.
  4. Change the BaseTool properties—such as name, caption, and so on.
  5. Add any initialization code to the tool's OnCreate or OnClick method.
  6. Add your code to the tool's OnSketchFinished event. This is the tool's functionality.
  7. Compile and register the component.

Creating an edit tool that does not use shape constructors—If your tool will provide its own geometry, that is, will not use the shape constructors, you can build a regular ArcGIS tool to use with the editor. The topic How to implement custom commands and tools describes how to create these tools. As with the command example previously described, you can obtain a reference to the editor in the tool's OnCreate event and set the enabled property as needed. You need to add code to the tool's mouse events to create your own geometry to complete the tool's operation.

Construction tools

Construction tools, such as the Line and Polygon construction tools, allow you to create features with a particular geometry type using the shape constructors. These tools follow the same pattern as tools that use shape constructors, as previously described, but are registered to specific component categories for each geometry type. For example, if you create a customized construction tool that creates point geometry, register the tool in the ESRI Editor Point Feature Construction Tools category (ESRI.ArcGIS.ADF.CATIDs.FeatureConstructionPointTools) as well as the MX Commands category. This tool would then be available when the user is working with a template item that has point geometry.
The following table lists the category, Component Category ID (CATID), and feature construction type of these tools:
Category
CATID
Feature type
ESRI Annotation Feature Construction Tools
FeatureConstructionAnnotationTools
Annotation
ESRI COGO Line Feature Construction Tools
FeatureConstructionCOGOLineTools
COGO Lines
ESRI Dimension Feature Construction Tools
FeatureConstructionDimensionTools
Dimensions
ESRI Geometric Network Line Feature Construction Tools
FeatureConstructionGNLineTools
Geometric Network Lines
ESRI Multipatch Feature Construction Tools
FeatureConstructionMultipatchTools
Multipatch
ESRI Multipoint Feature Construction Tools
FeatureConstructionMultipointTools
Multipoint
ESRI Network Dataset Turns Line Feature Construction Tools
FeatureConstructionTurnLineTools
Network Dataset Turns
ESRI Point Feature Construction Tools
FeatureConstructionPointTools
Point
ESRI Polygon Feature Construction Tools
FeatureConstructionPolygonTools
Polygon
ESRI Polyline Feature Construction Tools
FeatureConstructionPolylineTools
Polyline

Tasks

Edit tasks perform a specific edit operation using a geometry, typically from the edit sketch. For example, the Create New Feature edit task creates new features based on the geometry created by the various sketch tools. Similarly, the Select Features Using a Line edit task selects features in the map that are intersected by the edit sketch. In both cases, a geometry created by the sketch tools is used to complete an operation.

When to create a task

In the current version of ArcGIS, edit tasks are not exposed through the default editor user interface (UI) when working with templates. You should only create an edit task when end users will be working with the non-template UI; otherwise, create an edit tool as discussed previously.
If you have a case where users will be working in both UI environments, you can create an edit task to work in the non-template environment and a tool to drive the task when in the template UI. This slightly more complicated development process is discussed here.

Creating an edit task

To create an edit task, follow these steps:
  1. Create an empty library class (ArcMap) in Visual Studio using the templates under ArcGIS/Extending ArcObjects, and implement IEditTask from the editor library. The editor object is passed via the IEditTask.Activate method and can be used to access the sketch, IEditSketch. Most of your code should go in the IEditTask.OnFinishSketch method, which is called when the user completes the sketch.
  2. Use the sketch geometry, IEditSketch.Geometry, to complete your task.
  3. Compile and register the COM component. Edit tasks are registered under the ESRI Edit Tasks component category (EditTasks).

Creating a tool to drive an edit task

Tools that drive edit tasks are created the same way as a tool that uses shape constructors, as discussed previously, with the following changes:
  1. Set the editor's current task to the task you want to drive in the tool's OnClick event. You can find the registered task using the IEditTaskSearch interface or the IEditor.Task or IEditor.TaskCount loop.
  2. Remove the tool's default OnSketchFinished event handler and code; the task will perform this work.

Extensions

Creating an edit extension follows the same workflow as described in Creating an application extension. The key difference is that the editor object is passed to your extension via the InitializationData variant in the extension startup method, and you can set a module level variable for the editor in this routine. The extension is then registered to the ESRI Editor Extensions component category (editorextensions).

Shape constructors

Custom shape constructors are created as ArcGIS class libraries and consist of two components: the command component controls the behavior of the button on the editor toolbar while the implementation component defines the operation of the constructor.

Command component

The command class defines an ArcGIS button that can be placed on the Editor toolbar. It inherits from ESRI.ArcGIS.ADF.BaseClasses.BaseCommand to provide the basic button implementation. This class initializes the segment constructor and activates it on the edit sketch. The following methods are required:
  • The OnCreate method provides a hook into IApplication via the framework. A reference to the editor should be obtained within this method. See the following code example:
[C#]
public override void OnCreate(object hook)
{
    if (hook == null)
        return ;
    m_application=hook as IApplication;

    //Get the editor.
    UID editorUid=new UID();
    editorUid.Value="esriEditor.Editor";
    m_editor=m_application.FindExtensionByCLSID(editorUid)as IEditor;
}
[VB.NET]
Public Overrides Sub OnCreate(ByVal hook As Object)
If hook Is Nothing Then
    Return
End If
m_application=TryCast(hook, IApplication)
'Get the editor.
Dim editorUid As New UID()
editorUid.Value="esriEditor.Editor"
m_editor=TryCast(m_application.FindExtensionByCLSID(editorUid), IEditor3)
  • The OnClick method instantiates the implementation class and assigns the instance to the edit sketch shape constructor. See the following code example:
[C#]
public override void OnClick()
{
    // Create the constructor, pass the editor, and set as current constructor.
    m_edSketch=m_editor as IEditSketch3;
    AngleAngleCstr aac=new AngleAngleCstr();
    aac.Initialize(m_editor);
    m_edSketch.ShapeConstructor=aac;
}
[VB.NET]
Public Overrides Sub OnClick()
'Create the constructor, pass the editor, and set as current constructor.
m_edSketch=m_editor
Dim aac As AngleAngleCstr=New AngleAngleCstr()
aac.Initialize(m_editor)
m_edSketch.ShapeConstructor=aac
End Sub
In the previous code example, the segment constructor is first initialized with the editor (always required), then passed as the current shape constructor on the edit sketch. The constructor is then active until a new segment constructor is assigned, usually as a result of the user choosing a different segment constructor or construction tool.
The Enabled property determines if the command or constructor is available for the current tool. Ensure that there is an active session and that the current tool supports constructors. Tools that support constructors implement the IShapeConstructorTool interface. If your constructor is designed to only work with a certain geometry type, then query the edit sketch geometry in this property. See the following code example:
[C#]
public override bool Enabled
{
    // Enable the command if editing 
    // and current tool implements IShapeContructorTool.
    get
    {
        bool pEnabled=false;
        if (m_editor.EditState == esriEditState.esriStateEditing)
        {
            //Check for IShapeConstructorTool.
            IShapeConstructorTool psct=m_application.CurrentTool.Command as
                IShapeConstructorTool;
            pEnabled=(psct != null);
        }
        return (pEnabled);
    }
[VB.NET]
Public Overrides ReadOnly Property Enabled() As Boolean
Get
'Enable the command if editing
'and current tool implements IShapeContructorTool.
Dim pEnabled As Boolean=False
If (m_editor.EditState=esriEditState.esriStateEditing) Then
    'Check for IShapeConstructorTool.
    Dim csc As IShapeConstructorTool=m_application.CurrentTool.Command
    pEnabled=(csc IsNot Nothing)
    Return (pEnabled)
End If
End Get
End Property
The Checked property determines if the command button is depressed on the UI, indicating to the user the segment constructor is active. This property should be determined by what constructor is active on the current edit sketch. This is preferably obtained via persistence or the use of another property on the segment constructor implementation class. In the following code example, the check is made against the globally unique identifier (GUID) of the constructor implementation class:
[C#]
public override bool Checked
{
    get
    {
        // Check the command/button if this is the current constructor.
        IPersist ptemp=m_edSketch.ShapeConstructor as IPersist;
        Guid pg;
        ptemp.GetClassID(out pg);
        return (pg.ToString() == "guid string");
    }
}
[VB.NET]
Public Overrides ReadOnly Property Checked() As Boolean
Get
'Check the command/button if this is the current constructor.
Dim ptemp As IPersist=m_edSketch.ShapeConstructor
Dim pg As Guid
ptemp.GetClassID(pg)
Return (pg.ToString()="guid string")
End Get
End Property

Implementation component

The implementation class defines the behavior of the segment construction. It is normally inherited from IShapeConstructor to provide mouse and keyboard events similar to ITool. Ultimately, the goal of the implementation class is to define the location of the next sketch point and add it to the current edit sketch using the logic you provide.
The Initialize method provides a hook to the editor, passed from the command. You can set a reference to the editor and edit sketch at this point. Any other member variable initialization can also be done here. See the following code example:
[C#]
class AngleAngleCstr: IShapeConstructor, IPersist public override void Initialize
    (IEditor pEditor)
{
    m_editor=pEditor;
    m_EdSketch=m_editor as IEditSketch3;
}
[VB.NET]
Public Class AngleAngleCstr
    Implements IShapeConstructor, IPersist

    Public Sub Initialize(ByVal pEditor As IEditor) Implements IShapeConstructor.Initialize
        'Initialize the shape constructor.
        m_editor=pEditor
        m_edSketch=pEditor
    End Sub
Alternatively, you can aggregate an existing constructor to set limited constraints on the underlying base class.
If you rely on the Persistence method to control the checked properly of the associated command button, you need to implement the IPersist interface and set the GUID of the implementation class as shown in the following code example:
[C#]
public void GetClassID(out Guid pClassID)
{
    //Explicitly set a guid.
    //Used to set command.checked property.
    pClassID=new Guid("guid string");
}
[VB.NET]
Public Sub GetClassID(ByRef pClassID As System.Guid) Implements IPersist.GetClassID
    'Explicitly set a guid. Used to set command.checked property.
    pClassID=New Guid("guid string")
End Sub

Object inspectors

Custom object inspectors allow you to control what information is returned to the user in the Attributes window when selected features are inspected. You can only customize the panel that displays the attributes of the select features, not the panel containing the list of selected features. Custom object inspectors are usually items such as custom grid controls so developers can determine their own behavior when editing attributes.
Custom object inspectors are created as class libraries. You must implement IClassExtension from the geodatabase and IObjectInspector from the editor assemblies. The IObjectInspector.hWnd property determines what is displayed in the attributes pane. This is the handle of your custom control, usually a form hosting a control that will display information.
The IObjectInspector.Inspect method provides an enumeration of row objects that were inspected and a reference to the editor. Normally, the row enumeration contains one object, the individual feature the user clicked in the features pane, but it can return multiple objects if the user clicks the layer name. Use the row enumeration to retrieve properties of a feature and display any information as required in the attribute pane, declared in the hWnd property. You can then use the editor object reference to modify properties of a row within the context of an edit operation.
To enable your custom object inspector for feature classes, you must update the EXTCLSID column on the ObjectClasses table in the geodatabase with the CLSID (GUID) of your DLL for the feature classes you want to use with the inspector. The Sample: Tabbed feature inspector includes a command that shows this process.


See Also:

ArcGIS Desktop editing for developers




To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcGIS Desktop Advanced ArcGIS Desktop Advanced
ArcGIS Desktop Standard ArcGIS Desktop Standard
ArcGIS Desktop Basic ArcGIS Desktop Basic