Toolbar control overview

In this topic

About using the ToolbarControl

The ToolbarControl works in conjunction with a buddy control. The buddy control can be a MapControl, PageLayoutControl, GlobeControl, or SceneControl. The buddy control can be set at design-time through the ToolbarControl Java Property Editor (in development environments that support this capability) or programmatically using the setBuddyControl() method when the container hosting the ToolbarControl displays. The ToolbarControl hosts a panel of commands, tools, tool controls, menus, and palettes that work with the display of the buddy control. See the following screen shot that shows a sample application:
See the following code example:
Each ToolbarControl buddy control implements the IToolbarBuddy interface. This interface is used to set the setCurrentToolByRef() method 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 the Page Zoom In tool on the ToolbarControl, it becomes the current tool of the PageLayoutControl. The implementation of the Page Zoom In tool queries the ToolbarControl to access its buddy control (the PageLayoutControl) and retrieves the PageLayout. It then provides the implementation to display the rectangle dragged by the end user, 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 geographic information system (GIS) application. The ToolbarControl not only provides a part of the user interface (UI), it also provides a part of the application's framework. ArcGIS for Desktop applications, such as ArcMap, ArcGlobe, and ArcScene have a powerful and flexible framework that includes UI 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 UI components.
Many development environments provide some pieces of a framework in the form of simple dialog boxes, forms, and multiple document interface (MDI) applications. They also provide generic UI components, such as 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 for Desktop application framework. The developer can use some or all of these framework pieces when building an application with the ToolbarControl. 


ArcGIS Engine provides several suites of control commands that work with ArcGIS Engine controls to perform some specific action. You can extend this suite of control commands by creating 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 item is hosted on the ToolbarControl. The method is passed a handle or "hook" to the application that the command works with. 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. 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 stores the hook for later use. If the ToolbarControl is passed to the OnCreate event as the hook, the command normally checks the type of buddy control being used in conjunction with the ToolbarControl using the getBuddy() method. For example, if a command hosted on the ToolbarControl only works with the GlobeControl and the ToolbarControl's buddy is a MapControl, the command disables.
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 typically does some work using the hook to access the required objects from the buddy control. The following are the types of commands:
Commands can be added to the ToolbarControl programmatically or at design-time by using the Java Property Editor for the ToolbarControl. Commands can be added programmatically, by specifying the class identifier (CLSID) that uniquely identifies the command (also known as the globally unique identifier [GUID]) to the addItem() method, or by supplying an instance of an existing command object to the addItem() method. Wherever possible, commands should be added to the ToolbarControl by specifying a CLSID. If a CLSID is supplied, the ToolbarControl can identify whether this command has previously been added, and if so, can reuse its previous instance. 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. See the following code example:
//Using the CLSID of the command object.
toolbarControl.addItem(ControlsOpenDocCommand.getClsid(),  - 1,  - 1, false, 0,
toolbarControl.addItem(ControlsMapZoomInTool.getClsid(),  - 1,  - 1, true, 0,
toolbarControl.addItem(ControlsMapZoomOutTool.getClsid(),  - 1,  - 1, false, 0,

//Using an instance of a command object.

toolbarControl.addItem(new ControlsOpenDocCommand(), 0, 0, false, 0,
toolbarControl.addItem(new ControlsMapZoomInTool(), 0, 0, true, 0,
toolbarControl.addItem(new ControlsMapZoomOutTool(), 0, 0, false, 0,
Custom commands written in Java do not have a CLSID (GUID) and can only be added as an instance of the command object.


A ToolbarItem represents a single command, menu, or palette hosted on a ToolbarControl, ToolbarMenu, or ToolbarPalette. The IToolbarItem interface has methods 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, caption, or both. The Command, Menu, Palette, and MultiItem properties return the actual command, menu, palette, or multi-item that the ToolbarItem represents. 

Updating commands

By default, the ToolbarControl updates automatically every half a second. This ensures that the appearance of each ToolbarItem hosted on the ToolbarControl is synchronized with the isEnabled(), getBitmap(), isChecked(), and getCaption() methods of its underlying command. Changing the setUpdateInterval() method can alter the frequency of the update. A value of 0 stops updates from happening automatically, then you need to 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 checks whether the ICommand.onCreate() method of each ToolbarItem's underlying command has been called. If the method has not been called, the onCreate() method of the command is called and the ToolbarControl is automatically passed as the hook to the onCreate() method.


The ToolbarControl can host an item that is a drop-down menu. A ToolbarMenu item shows a vertical list of typically single click command items. The user must select one of the command items on the ToolbarMenu or click outside of the ToolbarMenu to make it disappear. The ToolbarMenu can be hosted on the ToolbarControl, hosted on another ToolbarMenu as a "sub menu," or it can appear as a "pop-up menu" and used for a right-click context menu. See the following code example:
toolbarControl.addMenuItem("esriControls.ControlsMapViewMenu",  - 1, false,  - 1);
The IToolbarMenuDefault interface provides an addMultiItem method that enables IMultiItem objects to be appended to an existing ToolbarMenu. The IMultiItem object allows a single object to act like several adjacent menu items. For example, a list of most recently loaded map documents or a list of the spatial bookmarks within a Map. MultiItems can only be added to the ToolbarMenu.


The ToolbarControl can host an item that is a drop-down palette. A ToolbarPalette item typically consists of tools that interact with the display of the buddy control when set as the current tool. The user must select one of the command items on the ToolbarPalette or click outside of the ToolbarPalette to make it disappear. The ToolbarPalette can be hosted on the ToolbarControl, hosted on a ToolbarMenu as a sub menu, or it can appear as a pop-up palette and used for a right-click context menu. See the following code example:
IToolbarPalette toolbarPalette = new ToolbarPalette();

//Using an instance of the commands.
toolbarPalette.addItem(new ControlsSelectTool(), 0,  - 1);
toolbarPalette.addItem(new ControlsNewCircleTool(), 0,  - 1);
toolbarPalette.addItem(new ControlsNewCurveTool(), 0,  - 1);
toolbarPalette.addItem(new ControlsNewEllipseTool(), 0,  - 1);

//Using the CLSID of the commands.
toolbarPalette.addItem(ControlsSelectTool.getClsid(), 0,  - 1);
toolbarPalette.addItem(ControlsNewCircleTool.getClsid(), 0,  - 1);
toolbarPalette.addItem(ControlsNewCurveTool.getClsid(), 0,  - 1);

toolbarControl.addItem(toolbarPalette,  - 1, 0, false, 0,


Each ToolbarControl, ToolbarMenu, and ToolbarPalette has a CommandPool that is used to manage the collection of command objects that it is using. Normally, as a developer, you will not interact with the CommandPool. When a command is added to the ToolbarControl, either through the Java Property Editor of the ToolbarControl or programmatically, the command is automatically added to the CommandPool. Command objects are added to the CommandPool by the CLSID that uniquely identifies the command (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 the unique CLSID of the 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 reuses the command and increment its usage count .
For example, if a Zoom In tool is added to a ToolbarControl twice, with the CLSID of the object, when one of the Zoom In items on the ToolbarControl is selected and appears "pressed," the other Zoom In item also appears pressed because they are both using the same command object. When an application contains multiple ToolbarControls, ToolbarMenus, or ToolbarPalettes, you should ensure each ToolbarControl, ToolbarMenu, and ToolbarPalette uses the same CommandPool. This prohibits more than one instance of a command being created in the application.


The ToolbarControl has a setCustomize() method that can be set to true 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.
While the ToolbarControl is in customize mode, you can programmatically launch the modeless CustomizeDialog. The CustomizeDialog lists all ArcGIS Engine commands, together with any custom commands, toolsets, menus, and palettes. It does this by reading entries from the ESRI Controls Commands, ESRI Controls Toolbars, ESRI Controls Menus, and ESRI Controls Palettes component categories. If required, you can change the CustomizeDialog to use alternative component categories with the setCommandsCategory(), setToolbarsCategory(), setMenusCategory(), and setPalettesCategory() methods. The end user can add these commands, toolsets, menus, and palettes to the ToolbarControl by dragging and dropping them on to the ToolbarControl or by double-clicking them.
The CustomizeDialog is modeless to allow the user to interact with the ToolbarControl. When the CustomizeDialog is started with the startDialog method, the method call returns immediately while the CustomizeDialog remains open on the screen. To keep a reference to the CustomizeDialog while it is open, store a class level variable to the CustomizeDialog and listen to its ICustomizeDialogEvents.
Use the IToolbarControlDefault.saveItems() method to save the contents of a ToolbarControl after it has been customized by an end user at runtime. The IToolbarControlDefault.loadItems method can be used to reload the contents into a ToolbarControl.

Operation stack

The ToolbarControl has a setOperationStack() and getOperationStack() method 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, then rolled back as necessary. 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 uses an OperationStack depends upon its implementation. Typically, as a developer, you create a single OperationStack for an application 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 ArcGIS Engine controls exist in out-of-the-box ArcGIS Engine commands. Any extent changes in an ActiveView are added to the IActiveView-ExtentStack and not on OperationStack.


The appearance of the ToolbarControl can be controlled by members of the IToolbarControl2 interface. The orientation of a ToolbarControl can be set to horizontal or vertical using the Orientation property. The setBackColor(), setFadeColor(), and setFillDirection() methods control the background shading of the ToolbarControl. Alternatively, the setTransparent() method can set the background to be transparent. The setShowHiddenItems() method determines whether any hidden items on the ToolbarControl are visible on a "hidden items" menu indicated to the end user by two chevrons (>>). See the following screen shot:

See Also:

Controls library overview
Creating custom commands and tools
Sample: Toolbar appearance
How to set ToolbarControl properties

Development licensingDeployment licensing
Engine Developer KitEngine
ArcGIS for Desktop Basic
ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced