This document is archived and information here might be outdated.  Recommended version.


Using the ToolbarControl (ArcObjects .NET 10.8 SDK)
ArcObjects Help for .NET developers > ArcObjects Help for .NET developers > Developing with ArcGIS > Building stand-alone applications > Using the Winforms ArcGIS Engine controls > Using the ToolbarControl

Using the ToolbarControl


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 property pages (in development environments that support property page 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 of a ToolbarControl:
See the following code example:
[C#] 
axToolbarControl1.SetBuddyControl(axPageLayoutControl1);
[VB.NET] 
AxToolbarControl1.SetBuddyControl(AxPageLayoutControl1)
Each ToolbarControl buddy control implements the IToolbarBuddy interface. This interface is used to set the CurrentTool property of the buddy control. For example, a ToolbarControl is hosting a Page Zoom In tool and has a PageLayoutControl as its buddy. When the Page Zoom In tool on the ToolbarControl is clicked, it becomes the CurrentTool of the PageLayoutControl. The implementation of the Page Zoom In tool queries the ToolbarControl to access its buddy control (PageLayoutControl) and retrieves the PageLayout, then provides the implementation to display the rectangle dragged by the user and changes the extent of the PageLayout.
The ToolbarControl is used with a selection of the control commands and a buddy control to provide a functional geographic information system (GIS) application. For more information, see Using the control commands.
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 (for example, 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 user to customize the application by allowing them to reposition, add, and remove most of these UI components.
Many development environments provide pieces of framework in the form of 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 user. The ToolbarControl and the objects in its library can supply pieces of framework similar to the ArcGIS for Desktop application framework. You 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 Engine controls to perform specific actions. You can extend this suite of control commands by creating customized commands that perform specific pieces 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 after the command object 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 tests to see if the hook object is supported (that is, the command tests to see that the hook is an object 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 checks 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's buddy is a MapControl, the command should disable.
The ICommand.OnClick method is called when the user clicks a command item hosted on the ToolbarControl. Depending on the type of command, it does some work using the hook to access the required objects from the buddy control. The following are the types of commands:
  • Command item 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 the same as a toggle.
  • Command item or tool implementing the ICommand and ITool interfaces that requires user interaction with the display of the buddy control - The ToolbarControl maintains one CurrentTool. When the user clicks the tool on the ToolbarControl, it becomes the CurrentTool and the previous tool is deactivated. The ToolbarControl sets the CurrentTool of the buddy control. While the tool is the CurrentTool, it receives mouse and key events from the buddy control.
  • A command item or tool control implementing the ICommand and IToolControl interfaces - This is a UI component similar to a Listbox or ComboBox control 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 the ToolbarControl programmatically or at design time by clicking Add on the Items property page to display commands, toolsets, menus, and palettes registered in the various ArcGIS Engine controls related component categories.
Commands can be added programmatically by specifying a unique identifier (UID) object that uniquely identifies a command (using a globally unique identifier [GUID]) to the AddItem method, or by supplying an instance of an existing command object to the AddItem method. Where possible, add commands to the ToolbarControl by specifying a UID. If a UID is supplied, the ToolbarControl can identify if 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 UID for the command, and multiple instances of the same command can exist on the ToolbarControl. See the following code example:
[C#] 
axToolbarControl1.SetBuddyControl(axMapControl1);
axToolbarControl1.AddItem("esriControls.ControlsOpenDocCommand",  - 1,  - 1, false,
    0, esriCommandStyles.esriCommandStyleIconAndText);
axToolbarControl1.AddItem("esriControls.ControlsMapZoomInTool",  - 1,  - 1, true, 0,
    esriCommandStyles.esriCommandStyleIconOnly);
axToolbarControl1.AddItem("esriControls.ControlsMapZoomOutTool",  - 1,  - 1, false,
    0, esriCommandStyles.esriCommandStyleIconOnly);
axToolbarControl1.AddItem("esriControls.ControlsMapFullExtentCommand",  - 1,  - 1,
    false, 0, esriCommandStyles.esriCommandStyleIconOnly);
[VB.NET] 
AxToolbarControl1.SetBuddyControl(AxMapControl1)
AxToolbarControl1.AddItem("esriControls.ControlsOpenDocCommand", , , False, , esriCommandStyles.esriCommandStyleIconAndText)
AxToolbarControl1.AddItem("esriControls.ControlsMapZoomInTool", , , True, , esriCommandStyles.esriCommandStyleIconOnly)
AxToolbarControl1.AddItem("esriControls.ControlsMapZoomOutTool", , , False, , esriCommandStyles.esriCommandStyleIconOnly)
AxToolbarControl1.AddItem("esriControls.ControlsMapFullExtentCommand", , , False, , esriCommandStyles.esriCommandStyleIconOnly)

ToolbarItem

A ToolbarItem represents a single command, menu, or palette hosted on a ToolbarControl, ToolbarMenu, or ToolbarPalette. The IToolbarItem interface has properties to determine the appearance of the item to the user, for example, whether the item has a vertical line to its left to signify 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.
A MultiItem object can only exist on a ToolbarMenu.

Updating commands

By default, the ToolbarControl updates automatically every half second. This ensures that the appearance of each ToolbarItem hosted on the ToolbarControl is synchronized with the Enabled, Bitmap, Checked, and Caption properties of its underlying command. Changing the UpdateInterval property can alter the frequency of the update. An UpdateInterval of 0 stops updates from occurring automatically. In this case, 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 ToolbarControl is automatically passed as the hook to the ICommand.OnCreate method.

ToolbarMenu

The ToolbarControl can host a drop-down menu item. A ToolbarMenu item can show 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. The ToolbarMenu can be hosted on the ToolbarControl, on another ToolbarMenu as a submenu, or it can appear as a pop-up menu that is used as a context menu when right-clicked. See the following code example:
[C#] 
axToolbarControl1.AddMenuItem("esriControls.ControlsMapViewMenu",  - 1, false,  - 1);
[VB.NET] 
AxToolbarControl1.AddMenuItem("esriControls.ControlsMapViewMenu", -1, False)
The IToolbarMenu2 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 the most recently loaded map documents or a list of the spatial bookmarks within a map.

ToolbarPalette

The ToolbarControl can host an item that is a drop-down palette. A ToolbarPalette item can consist of tools that interact with the display of the buddy control when set as the CurrentTool. The user must select one of the command items on the ToolbarPalette or click outside the ToolbarPalette to make it disappear. The ToolbarPalette can be hosted on the ToolbarControl, on a ToolbarMenu as a submenu, or it can appear as a pop-up palette that is used as a right-click context palette. See the following code example:
[C#] 
IToolbarPalette toolbarPalette=new ToolbarPaletteClass();
toolbarPalette.AddItem("esriControlCommands.ControlsSelectTool",  - 1,  - 1);
toolbarPalette.AddItem("esriControlCommands.ControlsNewLineTool",  - 1,  - 1);
toolbarPalette.AddItem("esriControlCommands.ControlsNewPolygonTool",  - 1,  - 1);
axToolbarControl1.AddItem(toolbarPalette,  - 1, 0, false, 0,
    esriCommandStyles.esriCommandStyleIconAndText);
[VB.NET] 
Dim toolbarPalette As IToolbarPalette
toolbarPalette=New ToolbarPaletteClass
toolbarPalette.AddItem("esriControlCommands.ControlsSelectTool")
toolbarPalette.AddItem("esriControlCommands.ControlsNewLineTool")
toolbarPalette.AddItem("esriControlCommands.ControlsNewPolygonTool")
AxToolbarControl1.AddItem(toolbarPalette, , 0, False, , esriCommandStyles.esriCommandStyleIconAndText)

CommandPool

Each ToolbarControl, ToolbarMenu, and ToolbarPalette has a CommandPool property that manages the collection of command objects it uses. Normally, as a developer, you will not interact with the CommandPool. When a command is added to the ToolbarControl - through the property pages of the ToolbarControl or programmatically - the command is automatically added to the CommandPool. Command objects are added to the CommandPool 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 UID 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 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 increments 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 also appears pressed because they are both using the same command object. When an application contains multiple ToolbarControls, ToolbarMenus, or ToolbarPalettes, ensure each ToolbarControl, ToolbarMenu, and ToolbarPalette uses the same CommandPool to prohibit more than one instance of a command being created in the application.

Customization

The ToolbarControl has a Customize property that can be set to true to put the ToolbarControl into customize mode. This changes the behavior of the ToolbarControl and allows the user to rearrange, remove, add items, and change appearances. See the following:
  • Click to select an item on the ToolbarControl and 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 Group properties of the ToolbarItem.
While the ToolbarControl is in customize mode, you can programmatically launch the modeless CustomizeDialog. The CustomizeDialog lists all the ArcGIS Engine commands, with any custom commands, toolsets, menus, and palettes. For more information, see ArcGIS Engine commands. It does this by reading entries from the ESRI controls commands, toolbars, menus, and palettes component categories. If required, change the CustomizeDialog to use alternative component categories with the CommandsCategory, ToolbarsCategory, MenusCategory, and PalettesCategory properties. The user can add these commands, toolsets, menus, and palettes to the ToolbarControl by dragging-and-dropping them on the ToolbarControl or by double-clicking them.
The 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. 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 keep the contents of a ToolbarControl after it has been customized by a user at run time. The IToolbarControl2.LoadItems method can be used to reload contents onto a ToolbarControl.

Operation stack

The ToolbarControl has an OperationStack property 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 needed. 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 on its implementation. Typically, as a developer, you create a single ControlsOperationStack for an application (by default, the OperationStack property is Nothing) and set it onto 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. Extent changes in an ActiveView are added to the IActiveView.ExtentStack and not an OperationStack.

ToolbarControl appearance

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 BackColor, FadeColor, and FillDirection properties control the background shading of the ToolbarControl. Alternatively, the Transparent property can set the background's transparency. The ShowHiddenItems property determines whether hidden items on the ToolbarControl are visible on a hidden items menu (indicated by  on the toolbar). See the following screen shot:


See Also:

Controls library overview
Using the control commands
ArcGIS Engine commands
How to create a command or tool to work with the controls
How to use an application as the ToolbarControl buddy
How to save ToolbarControl items to a settings file
Enabling menu tracking on the ToolbarControl
How to display MapControl and ToolbarControl information on a status bar
How to create a toolbar palette that works with the ToolbarControl
Samples:



Development licensing Deployment licensing
Engine Developer Kit Engine
ArcGIS for Desktop Basic
ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced