Toolbar Control Overview

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 such 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, menus and palettes that work with the display of the buddy control.

[Java]


        toolbar.setBuddyControl(pageLayoutControl);

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 on the Page Zoom In tool on the ToolbarControl it will become the current tool 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 document 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 Engine Controls to perform some specific action. You can extend this suite of control commands by creating your 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 item is hosted on the ToolbarControl. The method is passed a handle or "hook" to the application that the command will work 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 will disable 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 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 should disable itself.

The ICommand::onClick method is called when the end user clicks on 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 command item implementing the ICommand interface that responds to a single click. A click results in call to the ICommand::onClick() method, and some action is performed. By changing the ICommand::isChecked() method boolean value simple command items can behave like a toggle.
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 current tool and the previous tool is deactivated. The ToolbarControl will set the setCurrentToolByRef() method of the buddy control. While the tool is the current tool 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 like a Listbox or ComboBox hosted on the ToolbarControl. The ToolbarControl hosts a small window supplied by a window handle from the IToolControl::gethWnd() method. Only a single instance of a particular tool control can be added to the ToolbarControl.

Commands can be added to the ToolbarControl either programmatically or at design-time by using Java Property Editor for ToolbarControl. Commands can be added programmatically, by specifying the clsid that uniquely identifies the command (also known as GUID, globally unique identifier) 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.

[Java]


        //using Clsid of the command object
toolbarControl.setBuddyControl(mapControl);
toolbarControl.addItem(ControlsOpenDocCommand.getClsid(),  - 1,  - 1, false, 0,
    esriCommandStyles.esriCommandStyleIconAndText);
toolbarControl.addItem(ControlsMapZoomInTool.getClsid(),  - 1,  - 1, true, 0,
    esriCommandStyles.esriCommandStyleIconOnly);
toolbarControl.addItem(ControlsMapZoomOutTool.getClsid(),  - 1,  - 1, false, 0,
    esriCommandStyles.esriCommandStyleIconOnly);

//using instance of a command object

toolbarControl.addItem(new ControlsOpenDocCommand(), 0, 0, false, 0,
    esriCommandStyles.esriCommandStyleIconAndText);
toolbarControl.addItem(new ControlsMapZoomInTool(), 0, 0, true, 0,
    esriCommandStyles.esriCommandStyleIconAndText);
toolbarControl.addItem(new ControlsMapZoomOutTool(), 0, 0, false, 0,
    esriCommandStyles.esriCommandStyleIconAndText);

Custom commands written in Java do not have a clsid (GUID) and hence can only be added as an instance of the command object.

ToolbarItem

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, a 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 itself 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. An value of 0 will stop any updates from happening automatically and you will then 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 will check 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.

ToolbarMenu

The ToolbarControl can host an item that is a drop down menu. A ToolbarMenu item presents 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 itself can be either hosted on the ToolbarControl, hosted on another ToolbarMenu as a ‘sub menu’, or it can appear as a ‘popup menu’ and used for a right click context menu.

[Java]


        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 . It should be noted that MultiItems can only be added to the ToolbarMenu.

ToolbarPalette

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 itself can be either hosted on the ToolbarControl, hosted on a ToolbarMenu as a ‘sub menu’, or it can appear as a ‘popup palette’ and used for a right click context menu.

[Java]


        IToolbarPalette toolbarPalette = new ToolbarPalette();

//using 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 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,
    esriCommandStyles.esriCommandStyleIconAndText);

CommandPool

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 won't 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 either 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 will reuse 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 will also appear 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.

Customization

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.

Use the left mouse button to select an item on the ToolbarControl, either drag the selected item to a new position or drag-and-drop the item off the ToolbarControl to remove it.
Use the right mouse button 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 of the 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 either 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 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 IToolbarControlDefault::saveItems() method to save out 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 back into a ToolbarControl.

Operation Stack

The ToolbarControl has an setOperationStack() and getOperationStack() methods 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 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 the 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 .

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 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.

Development licensing	Deployment licensing
Engine Developer Kit	Engine Runtime
	ArcView
	ArcEditor
	ArcInfo

Toolbar Control Overview

Using the ToolbarControl

Commands

ToolbarItem

Updating commands

ToolbarMenu

ToolbarPalette

CommandPool

Customization

Operation Stack

Appearance

See Also: