The ToolbarControl works in conjunction with a buddy control. The buddy control can be a MapControl, PageLayoutControl, ReaderControl, SceneControl, or GlobeControl. The buddy control can be set at design time through the ToolbarControl property pages (in development environments that support property page capability) or programmatically using the SetBuddyControl method when the container hosting the ToolbarControl is displayed. The ToolbarControl hosts a panel of commands, tools, tool controls, and menus that work with the display of the buddy control.
An application that uses the ToolbarControl and the GlobeControl
Each ToolbarControl buddy control implements the IToolbarBuddy interface. This interface is used to set the CurrentTool property of the buddy control. For example, imagine a ToolbarControl that is hosting a Page Zoom In tool and has a PageLayoutControl as its buddy. When the end user clicks on the Page Zoom In tool on the ToolbarControl, it will become the CurrentTool of the PageLayoutControl. The implementation of the Page Zoom In tool will query the ToolbarControl to access its buddy control—the PageLayoutControl—and retrieve the PageLayout. It will then provide the implementation for displaying the rectangle dragged by the end user and changing the extent of the PageLayout.
The ToolbarControl is typically used with a selection of the Control Commands and a buddy control to quickly provide a functional GIS application. The ToolbarControl is not only providing a part of the user interface, it is also providing a part of the application's framework. ArcGIS desktop applications like ArcMap, ArcGlobe, and ArcScene have a powerful and flexible framework that includes user interface components such as toolbars, commands, menus, dockable windows, and status bars. This framework enables the end user to customize the application by allowing them to reposition, add, and remove most of these user interface components.
Many development environments provide some pieces of a framework in the form of simple dialog boxes, forms, and multiple docking interface (MDI) applications. They also provide generic user interface components like buttons, status bars, and list boxes. However, a substantial amount of coding can still be required to provide toolbars, menus and palettes that host commands, especially if they need to be customized by the end user. The ToolbarControl and the objects within its library can supply pieces of a framework similar to the ArcGIS Desktop application framework. The developer can use some or all of these framework pieces when building an application with the ToolbarControl.
Commands
ArcGIS Engine provides several suites of control commands that work with the ArcGIS controls to perform some specific action. You can extend this suite of control commands by creating their own customized commands that perform some specific piece of work. All of these command objects implement the ICommand interface that is used by the ToolbarControl to call methods and access properties at appropriate times.
The ICommand::OnCreate method is called shortly after the Command object is hosted on the ToolbarControl. The method is passed a handle or "hook" to the application with which the command will work. The implementation of a command normally tests to see if the hook object is supported (that is, the command tests to see that the hook is an object that the command can work with). If the hook is not supported, the command disables itself. If the hook is supported, the command stores the hook for later use. For example, if an Open Map Document command is to work with the MapControl or PageLayoutControl, and they are passed to the OnCreate method as the hook, the command will store the hook for later use. If the ToolbarControl is passed to the OnCreate event as the hook, the command would normally check the type of buddy control being used in conjunction with the ToolbarControl using the Buddy property. For example, if a command hosted on the ToolbarControl only works with the GlobeControl and the ToolbarControl buddy is a MapControl, the command should disable itself.
The ICommand::OnClick method is called when the end user clicks a command item hosted on the ToolbarControl. Depending on the type of command, it will typically do some work using the hook to access the required objects from the buddy control. There are three types of commands:
-
A single-click command implementing the ICommand interface that responds to a single click. A click results in a call to the ICommand::OnClick method, and an action is performed. By changing the ICommand::Checked value, simple command items can behave like a toggle. Single-click commands are the only types of commands that can be hosted on a menu.
-
A command item or tool implementing both the ICommand and ITool interfaces that requires end user interaction with the display of the buddy control. The ToolbarControl maintains one CurrentTool. When the end user clicks the tool on the ToolbarControl, it becomes the CurrentTool, and the previous tool is deactivated. The ToolbarControl will set the CurrentTool of the buddy control. While the tool is the CurrentTool, it will receive mouse and key events from the buddy control.
-
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.
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 another ToolbarMenu as a submenu, or appear as a popup menu and be used for a right-click context menu. Refer to the 'Building applications' scenarios in Chapter 6, 'Developer scenarios', to see how to build a popup menu hosting some control commands that work with the PageLayoutControl.
Hosting the ToolbarMenu directly on the ToolbarControl
Hosting theToolbarMenu as a submenu
Hosting the ToolbarMenu as a popup
CommandPool
Each ToolbarControl and ToolbarMenu has a CommandPool that is used to manage the collection of Command objects that it is using. Normally, you will not interact with the CommandPool. When a command is added to the ToolbarControl either through the property pages of the ToolbarControl or programmatically, the command is automatically added to the CommandPool. Command objects are added to the CommandPool either as a UID object that uniquely identifies the command—using a GUID—or as an existing instance of a Command object.
If an existing instance of a Command object is added, there is no unique identifier for the command, and multiple instances of the same command can exist in the CommandPool. If a UID object is supplied, the CommandPool can identify whether the command already exists in the CommandPool and, if so, can reuse the previous instance of the command. The CommandPool manages this by tracking whether the OnCreate method of a command has been called. If the OnCreate method has been called, it will reuse the command and increment its UsageCount.
For example, if a Zoom In tool is added to a ToolbarControl twice, with the UID supplied, when one of the Zoom In items on the ToolbarControl is selected and appears "pressed", the other Zoom In item will also appear pressed because they are both using the same Command object. When an application contains multiple ToolbarControls or ToolbarMenus, you should ensure each ToolbarControl and ToolbarMenu uses the same CommandPool so only one instance of a command is created in the application.
Customization
The ToolbarControl has a Customize property that can be set to put the ToolbarControl into customize mode. This changes the behavior of the ToolbarControl and allows the end user to rearrange, remove, and add items as well as change their appearance.
-
Use the left mouse button to select an item on the ToolbarControl, then either drag the selected item to a new position or drag and drop the item off the ToolbarControl to remove it.
-
Right-click to select an item and display a customize menu. The customize menu can be used to remove the item or change the Style (bitmap, caption, or both) and Grouping of the ToolbarItem.
While the ToolbarControl is in customize mode, you can programmatically launch the modeless CustomizeDialog. The CustomizeDialog lists all of the control commands, together with any custom commands, toolsets, and menus. It does this by reading entries from the ESRI Controls Commands, ESRI Controls Toolbars, and ESRI Controls Menus component categories. If required you can change the CustomizeDialog to use alternative component categories. The end user can add these commands, toolsets, and menus to the ToolbarControl either by dragging and dropping them onto the ToolbarControl or double-clicking them.
TThe CustomizeDialog is modeless to allow the user to interact with the ToolbarControl. When the CustomizeDialog is launched with the StartDialog method, the method call returns immediately while the CustomizeDialog remains open on the screen. In order to keep a reference to the CustomizeDialog while it is open, it is sensible practice to store a class level variable to the CustomizeDialog and to listen to its ICustomizeDialogEvents.
Use the IToolbarControl2::SaveItems method to save out the contents of a ToolbarControl after it has been customized by an end user at runtime. The IToolbarControl2::LoadItems method can be used to reload the contents back into a ToolbarControl.
OperationStack
The ToolbarControl has an OperationStack that is used to manage undo and redo functionality. Operations are added to the operation stack by each ToolbarItem’s underlying command, so that the operation can be rolled forward and then rolled back as desired. For example, when a graphic element is moved, the operation can be undone by moving the graphic back to its original location. Whether or not a command makes use of an OperationStack depends upon its implementation. Typically, as a developer, you create a single ControlsOperationStack for an application (by default the OperationStack property is Nothing) and set it into each ToolbarControl. Undo and Redo commands can be added to the ToolbarControl that step through the OperationStack. The Undo and Redo commands that work with the ArcGIS Engine Controls exist in the out of the box ArcGIS Engine Commands. Any extent changes in an ActiveView are added to the IActiveView::ExtentStack and not an OperationStack.
Appearance
The appearance of the ToolbarControl can be controlled by members of the IToolbarControl2 interface. The orientation of a ToolbarControl can be set to either horizontal or vertical using the Orientation property. The BackColor, FadeColor and FillDirection properties control the background shading of the ToolbarControl. Alternatively, the Transparent property can set the background to be transparent. The ShowHiddenItems property determines whether any hidden items on the ToolbarControl are visible on a 'hidden items menu' indicated to the end user by two chevrons.
| Development licensing | Deployment licensing |
|---|---|
| Engine Developer Kit | Engine Runtime |
| ArcView | |
| ArcEditor | |
| ArcInfo |