Creating custom commands and tools

With ArcGIS Engine, you can write custom commands and tools to add to your applications. They allow you to easily add custom functionality to your ArcGIS control applications without having to listen for all the events on the controls. To create a new command or tool, you will use the esriSystemUI ICommand interface. Through the ICommand interface, you will be able to set the properties and behavior for your command or tool. Some of the properties that you can set through the ICommand interface are the command's name, bitmap, caption, category, statusbar message, tooltip, enabled state, and checked state. It also defines the action taken when your command is clicked. For a custom tool, you will also use the esriSystemUI ITool interface. Through the ITool interface, you will be able to specify what cursor to use; what to do when the mouse button is pressed, released, or double-clicked; what to do when the mouse is moved; what to do when a key is pressed down or released; and what to do when a screen display in the application is refreshed.

Your custom command will be a button or menu that performs a simple action when clicked or selected. If you only want to have an action performed when the custom toolbar button is clicked (as, for example, a zoom to full extent command), you only need to write a custom command. To create custom commands with the C++ API, there is a helper class for ICommand that your command class will inherit from: CAoCommandBase. This is defined in arcgis/include/Ao/AoCommandBase.h and includes AoToolbarAddCommand, which you will use to place your custom command on a ToolbarControl.

Your custom tool will be a button or menu that interacts with the controls when it is selected. If you are looking to interact with the ArcGIS controls' display--for example, as the zoom in tool does--you will need to write a custom tool. To create custom tools with the C++ API, there is a helper class for ICommand and ITool that your tool class will inherit from: CAoToolBase. This is defined in arcgis/include/Ao/AoToolBase.h and includes AoToolbarAddTool, which you will use to place your custom tool on a ToolbarControl.

When you write your custom command or tool class, you will first stub out and implement all members of ICommand (for commands and tools) and ITool (for tools). This document does not go into detail on how to write your command or tool class. For help on writing the class, see Creating a Custom Command using AoBaseCommand or Creating a Custom Tool using AoBaseTool, respectively.

Once your command or tool class has been implemented you can add it into your application that has a toolbar. For the purposes of this document, ipToolbarControl will refer to your application's toolbar, which is already set up and placed earlier in the code. Your command class will be referred to as MyCommandClass, and your tool class will be referred to as MyToolClass.

          // Create an instance of your command
MyCommandClass *myCommand = new MyCommandClass();

// Create an instance of your tool
MyToolClass *myTool = new MyToolClass();

3. Now place your command or tool onto your application's toolbar.

          // Place the command onto the toolbar
AoToolbarAddCommand(ipToolbarControl, myCommand, esriCommandStyleIconOnly);

// Place the tool onto the toolbar
AoToolbarAddTool(ipToolbarControl, myTool, esriCommandStyleIconOnly);

4. Your options for the third parameter to AoToolbarAddCommand and AoToolbarAddTool are the same as they are for adding built-in commands and tools to the toolbar: esriCommandStyleIconOnly, esriCommandStyleTextOnly, and esriCommandStyleIconAndText. Compile your application. Your command or tool will be on the toolbar, ready for you to use it.