ArcGIS Engine Developer Guide

BUILDING APPLICATIONS WITH THE ARCGIS CONTROLS
• A command item or tool control implementing both the ICommand and
IToolControl interfaces. This is typically a user interface component, such as a
Listbox or ComboBox, hosted on the ToolbarControl. The ToolbarControl hosts a
small window supplied by a window handle from the IToolControl::hWnd
property. Only a single instance of a particular tool control can be added to
the ToolbarControl.
Commands can be added to ToolbarControl in two ways: by specifying a UID
object that uniquely identifies a command (using a Globally Unique Identifier, or
GUID) or by supplying an instance of an existing Command object to the AddItem
method. Where possible, commands should be added to the ToolbarControl by
specifying a UID. If a UID is supplied, the ToolbarControl can identify whether
this command has previously been added and, if so, can reuse the previous instance
of the command. When an existing instance of a Command object is added
to the ToolbarControl, there is no unique identifier for the command, and multiple
instances of the same command can exist on the ToolbarControl.
ToolbarItem
A ToolbarItem is a single command or menu hosted on a ToolbarControl or
ToolbarMenu. The IToolbarItem interface has properties to determine the appearance
of the item to the end user, for example, whether the item has a vertical line
to its left signifying that it begins a Group and whether the Style of the item
displays with a bitmap, a caption, or both. The Command and Menu properties
return the actual command or menu that the ToolbarItem represents.
Updating commands
By default, the ToolbarControl updates itself automatically every one-half second
to ensure that the appearance of each ToolbarItem hosted on the ToolbarControl is
synchronized with the Enabled, Bitmap, and Caption properties of its underlying
command. Changing the UpdateInterval property can alter the frequency of the
update. An UpdateInterval of 0 will stop any updates from happening automatically,
and you must call the Update method programmatically to refresh the state
of each ToolbarItem.
The first time the Update method is called in an application, the
ToolbarControl will check whether the ICommand::OnCreate method of
each ToolbarItem’s underlying command has been called. If the method
has not been called, the ToolbarControl is automatically passed as the hook
to the ICommand::OnCreate method.
Hosting the ToolbarMenu directly on the
ToolbarControl
ToolbarMenu
The ToolbarControl can host an item that is a dropdown menu. A
ToolbarMenu item presents a vertical list of single-click command items.
The user must select one of the command items on the ToolbarMenu or
click outside the ToolbarMenu to make it disappear. A ToolbarMenu can
only host command items; no tools or tool controls are permitted. The
ToolbarMenu itself can be hosted on the ToolbarControl, be hosted on
52 • ArcGIS Engine Developer Guide