Creating toolbars and menus

Summary Command bars are containers of command items, for example, buttons, tools, and submenus in an ArcGIS application. Toolbars, menus, and context menus are examples of command bars you can create by defining the collection of participating command items. This topic describes four different methods to implement these—add-ins (preferred method), interface implementation, base class inheritance, and the ArcGIS item templates.

In this topic

Building an add-in is the easiest way to create toolbars and menus. For more information, see Building add-ins for ArcGIS Desktop.

Implementing interfaces

To create a custom toolbar, implement IToolbarDef. The IToolbarDef interface is used to define the properties of a custom toolbar. You can set the caption and name of the toolbar and specify what command items are on the toolbar.
You can use IToolbarControl.AddToolbarDef to insert your toolbar definition to a ToolbarControl in an ArcGIS Engine application.
To create a custom menu, implement IMenuDef. The IMenuDef interface is identical to the IToolbarDef interface except that it is used to indicate to the application that this is a menu.
In ArcGIS Desktop, if you are creating a context menu, implement IMenuDef and IShortcutMenu. IShortcutMenu is an indicator interface that is used only to indicate to the application that this menu should be treated as a context menu. If you are creating a root menu (a menu that appears in the Menus command category on the Customize dialog box), implement IMenuDef and IRootLevelMenu. IRootLevelMenu is an indicator interface that is used only to indicate to the application that this menu should be treated as a root menu.
You can use IToolbarMenu to define menus and contexts menu in an ArcGIS Engine application.

Inheriting ArcGIS base classes

The BaseToolbar and BaseMenu classes standardize the creation of custom toolbars and menus for ArcGIS. Instead of directly implementing the IToolbarDef or IMenuDef interface, you can use these base classes to define command items on a command bar in a script-like manner. See the following:
  • The AddItem() overloaded methods are more flexible than implementing the GetItemInfo method. You can add command items by its identifier—a ProgID, unique identifier (UID), or class identifier (CLSID) with subtype code, the System.Guid or System.Type of the class implementing the command item.
    • If the command item identifier is not resolvable at run time, a missing item placeholder is put on the command bar instead of skipping the item.
  • The BeginGroup() method is used to insert a separator between items.
  • The caption and name of the bar can be set via a protected member or overriding the read-only properties.
The following table shows the members that have a significant base class implementation and a description of that implementation:
Member (IToolbarDef or IMenuDef)
Description
Caption
Default to null. Can be overridden.
Name
Default to null. Can be overridden.
ItemCount
Determined by the number of items inserted by the AddItem() overloaded methods. Cannot be overridden.
GetItemInfo
 
Returns the items and separators inserted by the AddItem() and BeginGroup() methods. Cannot be overridden.

Using ArcGIS item templates

The ArcGIS Visual Studio integrated development environment (IDE) Integration Framework includes item templates for ArcGIS toolbars, menus, and context menus. Using these item templates allows you to create command bars more efficiently than directly implementing the interfaces.
The following are the advantages of using the item templates:
  • The implementation is essentially the same for the different command bar types.
  • The bar name defaults to the class name.
  • The definition of command items are all set up in the constructor with the help of the script-like methods to add items and insert separators.
  • All custom command bars are ready to be exposed to the Component Object Model (COM) and have the appropriate component category registration functions. 

Creating toolbars or menus

Do the following steps to add a toolbar or menu implementation to an existing project:
  1. Select the Base Toolbar or Base Menu template on the Add New Item dialog box to add the item to your Visual Studio project. For more information, see Using item templates to extend ArcObjects.
  2. After you click Add on the Add New Item dialog box, the ArcGIS New Item Wizard Options dialog box appears where you can choose the target ArcGIS Desktop or ArcGIS Engine application the toolbar or menu will use.
  3. Modify the code after the TODO comment lines in the constructor to define the command items to be included in the toolbar or menu. 

    See the following code example:
[VB.NET] 
Public Sub New()
    '
    'TODO: Define your menu here by adding items.
    '
    AddItem("esriArcMapUI.ZoomInFixedCommand")
    BeginGroup() 'Separator
    AddItem("{FBF8C3FB-0480-11D2-8D21-080009EE4E51}", 1) 'Undo command.
    AddItem(New Guid("FBF8C3FB-0480-11D2-8D21-080009EE4E51"), 2) 'Redo command.
End Sub
[C#] 
public ArcGISMenu()
{
    //
    // TODO: Define your menu here by adding items.
    //
    AddItem("esriArcMapUI.ZoomInFixedCommand");
    BeginGroup(); //Separator
    AddItem("{FBF8C3FB-0480-11D2-8D21-080009EE4E51}", 1); //Undo command.
    AddItem(new Guid("FBF8C3FB-0480-11D2-8D21-080009EE4E51"), 2); //Redo command.
}
  1. Modify the caption and name in the overridden properties.
  2. For ArcGIS Desktop only—If you want to create a root level menu, add a reference to the ESRI.ArcGIS.Framework assembly, and insert an implement statement of the indicator interface IRootLevelMenu in the base menu class.

    See the following code example:
[VB.NET] 
Public NotInheritable Class ArcGISMenu
Inherits BaseMenu
Implements ESRI.ArcGIS.Framework.IRootLevelMenu
[C#] 
public sealed class ArcGISMenu: BaseMenu, ESRI.ArcGIS.Framework.IRootLevelMenu

Creating ArcGIS Desktop context menus

Do the following steps to add a context menu implementation to an existing project:
  1. Select the Context Menu template from the ArcGIS Desktop node on the Add New Item dialog box to add the item to your Visual Studio project.
  2. After you click Add on the Add New Item dialog box, the ArcGIS New Item Wizard Options dialog box appears. Choose the type of ArcGIS Desktop application you want to create.
  3. The class generated is very similar to a Base Menu template except it implements the extra IShortcutMenu interface.
  4. Modify the code after the TODO comment lines in the constructor to define the command items to include in the context menu.
  5. Modify the caption and name in the overridden properties.
For more information, see How to add a context menu using the Visual Studio Integration tools.


See Also:

Working with ArcGIS base classes
ESRI.ArcGIS.ADF.BaseClasses namespace
How to add a context menu using the Visual Studio Integration tools
Using item templates to extend ArcObjects
Sample: Simple logging dockable window with a custom context menu