Migrating desktop editing customizations to ArcGIS 10

Summary
The ArcGIS editing user interface (UI) has been redesigned to provide a simpler and more productive experience for the end user. Additionally, the framework introduces a new way to create and deploy desktop customizations—such as commands and tools—called add-ins. This topic describes the impact on existing customizations and describes how to migrate them to the ArcGIS 10 editing environment.
This topic also provides an overview of editing changes and the migration path to move those customizations to take advantage of the new capabilities in ArcGIS.

Understanding the ArcGIS 10 desktop editing environment

At ArcGIS 9.3.1 and earlier, edits were performed via commands, tasks, and tools against an edit target. To create a feature, for example, you specified the editor's target layer, set the edit task to Create New Feature, then typically used the sketch tool to create a geometry that ultimately created a new feature.
At the current version of ArcGIS, a feature is created by selecting a feature template, selecting a construction tool, then using the shape constructors to create geometry. Behind the scenes, the target, task, and edit sketch are still in use. When you select a feature template, the editor's target layer is set to the feature class of the selected template and the task is set to Create New Feature. The construction tools forward calls to the edit sketch via the shape constructors to create the geometry. When the sketch finishes, the task takes over and creates the feature.
Edit tasks are now exposed as edit tools. For example, the Reshape Features tool is located on the Editor toolbar. Behind the scenes, this tool works on a single selected feature, setting the task to Reshape Features and again forwarding the tool calls to the edit sketch via the shape constructors.
The shape constructors are new classes exposed as commands (not tools) on the toolbar. They work with the currently active tool to define the geometry of the next point on the edit sketch. For example, if you have the Line tool active and the straight constructor active, clicking the mouse creates straight lines.
End users can return to the old UI by unchecking Create features using templates on the General tab under Editor Options. Unless you know the specific environment in which your end user is working, use the redesigned editor UI to develop new customizations, and migrate existing customizations to the new UI as well.

Converting customizations to ArcGIS 10

This section describe the considerations and methods to convert existing customizations to the ArcGIS 10 editing framework.

Edit commands

The logic within your edit commands should not change. If the command relies on the end user setting an edit target or edit task, you will need to provide a different mechanism for the user to set those.
All commands need to be recompiled and reregistered. See Migrating ArcGIS 9.3 Desktop and Engine custom components to ArcGIS 10 for information on converting commands.
If your command only implements ICommand or BaseCommand from the framework, you can also convert it to an add-in. See How to migrate from COM components to add-ins and Customizing the editor framework using add-ins for information on converting commands to add-ins.

Edit tools

If your edit tool creates its own geometry for a specific task or provides feedback, the logic of the tool should not change. As with edit commands mentioned previously, however, if the end user is responsible for setting a target and task, you need to provide an alternative mechanism for them to do that.
All tools need to be recompiled and reregistered. See Migrating ArcGIS 9.3 Desktop and Engine custom components to ArcGIS 10 for information on converting tools.
If you have a custom sketch tool, convert it to a shape constructor. See Editor framework customizations for information on creating a custom shape constructor. In this topic, the Angle-Angle sketch tool sample has been converted to a shape constructor as an example.

Edit tasks

Since edit tasks are no longer exposed in the default ArcGIS editing UI, you have to provide a way for users to access the customization. The options include wholly converting the edit task to a tool or partial conversion, which involves creating a tool to drive an edit task.
Converting edit tasks to tools
Before converting your task to a tool, see Customizing the editor framework using components to understand the general pattern for creating a tool that uses the sketch. These tools are similar to existing edit tasks in that they listen to the OnSketchFinished event to perform an action. The conversion steps for creating a tool from a task are as follows:
  1. Create a new edit tool from the Visual Studio ArcGIS templates.
  2. Change the BaseTool properties—such as name, caption, and so on.
  3. Transfer the edit task code from IEditTask.Activate to the tool's OnCreate or OnClick method as appropriate. Transfer any Deactivate code as well.
  4. Transfer the edit task code from IEditTask.OnFinishSketch to the tool's OnSketchFinished event.
Creating a tool to drive a task
The premise is to create a tool that sets your task as the current edit task while still forwarding all the tool methods to the sketch. Once the sketch is finished, your edit task takes over as it normally would. The conversion steps for creating a tool to drive a task are as follows:
  1. Create a new edit tool from the Visual Studio ArcGIS templates.
  2. Change the BaseTool properties—such as name, caption, and so on.
  3. Set your task to be the current editor task in the tool OnClick event. You can use the IEditTaskSearch interface to find your task or the IEditor.TaskCount and IEditor.Task loops.
  4. Set the current task to null on Tool.Deactivate.
You have to maintain, compile, and register both the edit task and the tool.

Edit extensions

As with commands and tools, the general logic of edit extensions should not have to change.
If your extension only implements IExtension from the framework, you can also convert it to an edit extension add-in. See Building editor extensions using add-ins for information on converting edit extensions to add-ins.

Annotation Constructors

The annotation constructor class will need to be recompiled but otherwise does not change. You will need to create an editor construction tool to drive the annotation constructor. The edit tool simply exposes the sketch tool with a point shape constructor to pass the input points to the annotation constructor which handles the feedback and text construction.
Create the edit tool as a Desktop ArcMap Edit Tool via the Visual Studio ArcGIS Templates. The tool needs to be registered in the Editor Annotation Feature Construction Tools category.
The following code should be in the OnClick event.
[C#] 
m_edSketch = m_editor as IEditSketch3;
m_csc = new PointConstructorClass();
m_csc.Initialize(m_editor);
m_edSketch.ShapeConstructor = m_csc;
m_csc.Activate();

//Set this as the current anno constructor
UIDClass pID = new UIDClass();
pID.Value = "esriEditor.AnnotationEditExtension";
IAnnotationEditExtension annoEditExt = m_editor.FindExtension(pID)as
    IAnnotationEditExtension;
IEnumAnnotationConstructor annoConstructs = annoEditExt.AnnotationConstructors;
IAnnotationConstructor annoConstructor = annoConstructs.Next();
//Find annotation constructor by name
while (!(annoConstructor == null))
{
    if (annoConstructor.Name == "Midpoint")
        annoEditExt.CurrentConstructor = annoConstructor;
    annoConstructor = annoConstructs.Next();
}

//Show annotation construction window
pID.Value = "esriEditor.AnnotationConstructionWindow";
IAnnotationConstructionWindow annoConWindow = m_editor.FindExtension(pID)as
    IAnnotationConstructionWindow;
annoConWindow.Visible = true;

//set the current task to null
//m_editor.CurrentTask = Nothing
[VB.NET] 
m_edSketch = TryCast(m_editor, IEditSketch3)
m_csc = New PointConstructorClass()
m_csc.Initialize(m_editor)
m_edSketch.ShapeConstructor = m_csc
m_csc.Activate()

'Set this as the current anno constructor
Dim pID As New UIDClass()
pID.Value = "esriEditor.AnnotationEditExtension"
Dim annoEditExt As IAnnotationEditExtension = m_editor.FindExtension(pID)
Dim annoConstructs As IEnumAnnotationConstructor = annoEditExt.AnnotationConstructors
Dim annoConstructor As IAnnotationConstructor = annoConstructs.Next
'Find annotation constructor by name
Do Until annoConstructor Is Nothing
    If annoConstructor.Name = "Midpoint" Then annoEditExt.CurrentConstructor = annoConstructor
    annoConstructor = annoConstructs.Next
Loop

'Show annotation construction window
pID.Value = "esriEditor.AnnotationConstructionWindow"
Dim annoConWindow As IAnnotationConstructionWindow = m_editor.FindExtension(pID)
annoConWindow.Visible = True

'set the current task to null
'm_editor.CurrentTask = Nothing
It is important to keep the Editor's current task to Create Feature, which is the default if the user selects an edit template. In this example the Annotation Construction Window is also shown. This needs to be hidden in the tools Deactivate method.

Snapping

ArcGIS 10 introduces a new snapping environment that you can use in customizations in Desktop and Engine. This new environment is not restricted to the editor.
If you're using snapping in your existing tools, explore the new snapping environment, which offers a simpler application programming interface (API). The previous editor snapping environment is still supported and will continue to work in your existing tools.
See Working with the ArcGIS snapping environment for information on implementing this new API in your customizations.

Snap agents, object inspectors, and sketch extensions

Snap agent, object inspector, and sketch extension customizations need to be recompiled but otherwise should work as is. Snap agents only apply to the classic editor snapping environment. Custom object inspectors cannot use the attributes window toolbar.