How to implement custom commands and tools


This document was published with and applies to ArcGIS 9.3.
A 10 version also exists. A 9.2 version also exists.
Summary Commands and tools are among the most frequently implemented components in ArcGIS. This document describes three different ways to implement custom commands and tools: interface implementation, base class inheritance, and the recommended ArcGIS item templates.

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

In this topic


Implementing interfaces

A custom command can be created by implementing ICommand. By implementing ICommand, you define a command's appearance, state, and behavior. A command is plugged into an application by registering itself in to the appropriate command component categories. When the command is used by the application framework, the OnCreate method is called to initialize and hook to the application or control.
 
A tool is a type of command that allows interaction with a display canvas in an ArcGIS application. To create a custom tool, implement both ICommand and ITool interfaces. By implementing ITool, you define the cursor, mouse, or keystroke interaction performed by a tool.
 
You must stub out and provide implementation code for each interface member in the source code. You are also responsible for registering the class to the appropriate component category.
 
You can use the ArcGIS Add Class Wizard to accomplish these development tasks.

Inheriting ArcGIS base classes

The BaseCommand and BaseTool classes simplify the creation of custom commands and tools for ArcGIS. They provide a default implementation for each of the members of ICommand and ITool. Instead of stubbing out each member and providing implementation code, you have to override the members that your custom command or tool requires. The exception is ICommand.OnCreate; this member must be overridden in your derived class.
 
The following table shows the members that have a significant base class implementation, along with a description of that implementation. Override these members when the base class behavior is not consistent with your customization. For example, enabled is set to true by default; if you want your custom command enabled only when a specific set of criteria has been met, you must override this property in your derived class.
 
Member
Description
The bitmap is made transparent based on the pixel value at position 1,1. The bitmap is null until set by the derived class.
If null, sets the category to Misc.
Set to false.
Set to true.
Set to false.
Set to true.
 

Using ArcGIS item templates

The Base Command and Base Tool item templates are available to help you create commands and tools more efficiently than directly implementing the interfaces. The advantages of using the item templates are listed as follows:
 

Creating a command or tool

Follow these general steps to add a command or tool implementation to an existing project:
  1. Select Base Command or Base Tool from the Add New Item dialog box to add the item to your Visual Studio project. For information on how to access the dialog box, see ArcGIS item templates.
  2. After you click Add, the ArcGIS New Item Wizard Options dialog box appears. Select the type of command or tool you want to create and click OK. The type of command or tool you choose depends on the ArcGIS Engine control or ArcGIS Desktop application you want the command or tool to work with. See the following screen shot:

 
A Universal Command or Universal Tool works with the ArcGIS Engine MapControl, PageLayoutControl, GlobeControl, and SceneControl, as well as the ArcGIS Desktop ArcMap, ArcGlobe, and ArcScene applications. A Blank Command or Blank Tool does not contain any component category registration code or implementation in the OnCreate method; you need to provide this.
  1. Modify the code below the TODO comment lines in the constructor of the generated class. Review the code in the overridden OnCreate method, which is responsible for initializing the command or tool with the hook control or application.  
  2. In the case of a command, provide implementation within the OnClick method. In the case of a tool, provide implementation within the OnMouseDown, OnMouseMove, or OnMouseUp methods.
  3. If necessary, override other methods or properties from the base class. Using the autocompletion feature in Visual Studio, type public override (C#) or Public overrides (VB.NET) and press the spacebar to get a list of the available members to override.
  4. If necessary, edit the command bitmap or tool cursor file. These files have the same name as the class file.


See Also:

Working with the ArcGIS base classes
ESRI.ArcGIS.ADF.BaseClasses namespace
How to create a command or tool to work with the controls
About the ArcGIS item templates