ArcGIS Engine Developer Guide

C++ APPLICATION PROGRAMMING INTERFACE
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.
Since commands are a GUI tool to interact with ArcGIS controls, C++ custom
commands will only work on Solaris and Linux. If you want to write a command
or tool to plug into ArcMap or ArcCatalog, you will need to use a different
language such as Visual C++.
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’, which can be
found in the developer help system under Development Environments > C++ >
Walkthroughs.
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.
250 • ArcGIS Engine Developer Guide