How to create a command or tool to work with the controls

Summary
The ArcGIS Visual Studio integrated development environment (IDE) Integration Framework provides ArcGIS base command and base tool item templates. These can be used to create custom commands and tools to work with the ArcGIS Engine controls. This topic provides an overview of how base command and base tool items can be created and, once they are created, how they can be used with the ArcGIS Engine controls in a custom application.

ArcGIS base command and base tool

The ArcGIS Visual Studio IDE Integration Framework includes item templates for the ArcGIS base command and base tool. Using these item templates, you can create commands and tools more efficiently than directly implementing the ICommand and ITool interfaces. The following are the advantages of using the item templates:
  • The ArcGIS base command and base tool inherit from the BaseCommand and BaseTool abstract classes. Instead of implementing the Bitmap, Caption, Category, Name, Message, and ToolTip properties individually, you can set the values to be returned from these read-only properties in the class constructor and rely on the BaseCommand or BaseTool class to provide the implementation for these methods. The other members are left to return the default values as implemented by the BaseCommand or BaseTool class.
Abstract classes cannot be instantiated and frequently contain only partial implementation code or no implementation at all. They are closely related to interfaces. However, they differ significantly from interfaces in that a class may implement any number of interfaces, but it can inherit from only one abstract class. 
  • The ArcGIS base command and base tool override the OnCreate method that is passed a handle or hook to the ArcGIS Engine control or ArcGIS for Desktop application with which the command works (for example, MapControl, PageLayoutControl, ToolbarControl, or ArcMap). Rather than adding code to an OnCreate method to determine the type of hook that is passed to the command, the HookHelper object handles this. The HookHelper object is used to hold on to the hook, and the IHookHelper interface it implements can return the ActiveView, PageLayout, and Map regardless of the type of hook that is passed.
A GlobeHookHelper or SceneHookHelper object can also be used. The GlobeHookHelper object is used to hold on to the hook, and the IGlobeHookHelper interface it implements can return the Camera, Globe, GlobeDisplay, and ActiveViewer regardless of the type of hook that is passed. The SceneHookHelper object is used to hold on to the hook, and the ISceneHookHelper interface it implements can return the SceneViewer, Scene, SceneGraph, and Camera regardless of the type of hook that is passed.
  • ArcGIS Engine expects a custom command or tool to be a Component Object Model (COM) class. The ArcGIS base command and base tool provide the attributes and globally unique identifiers (GUIDs) required by COM in the class.
  • Visual Studio provides the ability to specify functions that execute when an assembly exposed for COM is registered and unregistered on a system. This allows the class to be registered in a component category that a Customize dialog box looks for. The ArcGIS base command and base tool provide these COM component category registration functions.

Creating a base command or base tool

To create a base command or base tool, perform the following steps:
  1. To add the ArcGIS base command or base tool to your Microsoft Visual Studio project, do one of the following:
    1. Select the project name in Solution Explorer and choose Add New Item from the Project menu.
    2. Right-click the project name in Solution Explorer, select Add, and click New Item (or press Ctrl+Shift+A).
The Add New Item dialog box opens. See the following screen shot:

  1. Expand the ArcGIS node under Categories and click Extending ArcObjects.
  2. Under Templates, select Base Command or Base Tool and click Add. The ArcGIS New Item Wizard Options dialog box opens.
  3. 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 for Desktop application you want the command or tool to work with. See the following screen shots:

A Universal Command or Universal Tool works with the ArcGIS Engine MapControl, PageLayoutControl, GlobeControl, and SceneControl, as well as the ArcGIS for Desktop (ArcMap, ArcGlobe, and ArcScene) applications. A Blank Command or Blank Tool does not contain any component category registration code or any implementation within the OnCreate method; you need to provide this.
  1. Add custom functionality to the command or tool. For example, provide Bitmap, Caption, Category, Name, Message, and ToolTip values for the command or tool in the class constructor. In the case of a command, provide implementation in the OnClick method. In the case of a tool, provide implementation in the OnMouseDown, OnMouseMove, or OnMouseUp methods.
See Building a map viewing application using the ArcGIS Engine controls for more information on using the ArcGIS base tool to create a custom Add Date tool for the ArcGIS Engine MapControl and PageLayoutControl.

Using a base command or base tool in an application

This section explains the different ways a custom ArcGIS base command or base tool can be used in an application once it has been fully implemented and built.

Using the ArcGIS Engine ToolbarControl

In custom ArcGIS Engine applications where you use the ToolbarControl in conjunction with a buddy control (MapControl, PageLayoutControl, GlobeControl, or SceneControl), the command or tool can be added to the ToolbarControl in one of the following ways:
  • Using the ToolbarControl property pages at design time.
  • By the end user through the CustomizeDialog if the ToolbarControl is in Customize mode.
  • Programmatically using the AddItem method.
Once a command or tool has been added to the ToolbarControl, the ToolbarControl passes the hook to the OnCreate method.
In this case, the hook that is passed is the actual ToolbarControl. If the command or tool uses a HookHelper, GlobeHookHelper, or SceneHookHelper object, they internally return properties from the ToolbarControl buddy (MapControl, PageLayoutControl, GlobeControl, or SceneControl).

Using the ArcGIS Engine controls without the ToolbarControl

In custom ArcGIS Engine applications where the ToolbarControl is not required, the command or tool must work directly with the MapControl, PageLayoutControl, GlobeControl, or SceneControl. You must programmatically perform the following tasks:
  1. Create an instance of the command or tool.
  2. Pass the individual ArcGIS Engine control to the OnCreate method. When passing the control, use the Object property (for example, AxGlobeControl.Object when using the host wrapper) to ensure the real control is passed to the command or tool. This is done because .NET contains the real control inside a wrapper object or host.
The ArcGIS Engine controls are contained in a Controls library. For the .NET application programming interface (API), there are two primary interop assemblies (PIAs) provided by Esri for the ArcGIS Engine controls. The first, ESRI.ArcGIS.AxControl, inherits from the .NET AxHost class and enables the controls to be embedded in a .NET container, such as a form. The second, ESRI.ArcGIS.Control, is a wrapper around the actual type library.
  1. In the case of a command, call the OnClick method at the appropriate time to perform the specific action. See the following code example:
[C#] 
//Create a command instance.
ICommand command = new myCommandClass();
//Pass the MapControl to the OnCreate method.
command.OnCreate(axMapControl1.Object);
//Call OnClick.
command.OnClick();
[VB.NET] 
'Create a command instance.
Dim Command As ICommand = New myCommandClass()
'Pass the MapControl to the OnCreate method.
Command.OnCreate(AxMapControl1.Object)
'Call OnClick.
Command.OnClick()
  1. In the case of a tool, set the CurrentTool of the ArcGIS Engine control. The ArcGIS Engine control sends any keyboard and mouse event to the tool. See the following code example:
[C#] 
//Create a tool instance.
ICommand command = new myToolClass();
//Pass the MapControl to the OnCreate method.
command.OnCreate(axMapControl1.Object);
//Set the MapControl's current tool.
axMapControl1.CurrentTool = command as ITool;
[VB.NET] 
'Create a tool instance.
Dim Command As ICommand = New myToolClass()
'Pass the MapControl to the OnCreate method.
Command.OnCreate(AxMapControl1.Object)
'Set the MapControl's current tool.
AxMapControl1.CurrentTool = Command
  1. The Enabled, Caption, and Bitmap properties of the command or tool can be read and incorporated into properties of a command button supplied by the development environment—for example, to build up the user interface of the application.

Using an ArcGIS for Desktop application

A custom command or tool built with ArcGIS Engine can be added to an ArcGIS for Desktop (ArcMap, ArcGlobe, or ArcScene) application using, for example, the Customize dialog box supplied by these applications. This is because the libraries and objects available in ArcGIS Engine are also available in ArcGIS for Desktop.


See Also:

Walkthrough: Building a map viewing application using the ArcGIS Engine controls
Controls library overview



Development licensing Deployment licensing
Engine Developer Kit Engine
ArcGIS for Desktop Basic
ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced