How to create an add-in toolbar

Summary This document will guide you through the workflow for creating a toolbar using the Eclipse integrated development environment (IDE). A toolbar is a container for other types of add-ins (that is, Tools, Buttons, Menus, Tool Palettes, and Combo Boxes) that you have created or other ESRI provided tools and buttons.

In this topic

About the toolbar

A toolbar is a container for buttons, tools, combo boxes, tool palettes, and menus. In addition to your own customizations, you can add ESRI system buttons and tools to your toolbar. Toolbars can be floating or docked in desktop applications, just like any system toolbar provided by ESRI. Toolbars can also be activated so they show up when a desktop application is started - this is referred to as a premier toolbar.
The following will guide you through the process of creating a toolbar using the Eclipse IDE. Before beginning this workflow, you must make sure that you have created a new ArcMap add-in project using Eclipse (see How to create an add-in project in Eclipse for details). Since there is no difference between creating a toolbar for any one of the ArcGIS Desktop applications, this workflow shows you how to create a toolbar for ArcMap. This document will show you how the toolbar contains the various add-ins or ESRI provided functionality. It will also demonstrate the notion of a premier toolbar.
The workflow for creating a toolbar in Eclipse consists of the following steps:
  1. Creating a new toolbar
  2. Setting properties
  3. Adding functionality
  4. Setting the premier status, if applicable (Optional)
Step 1 will examine the process of creating a new toolbar in Eclipse. Step 2 will examine all of the properties that can be set with detailed descriptions.  Step 3 will examine how functionality is added to the toolbar, either your own add-ins or ESRI provided functionality. The final step examines an optional choice you have for setting the premier status of a toolbar.

Creating a new toolbar

The following will show you how to create a new toolbar for an existing Eclipse add-in project. Please ensure that you have the add-in view enabled for the add-in editor on the config.xml file and that you have filled out the required overview properties.
  1. Under All add-ins, click the Add button.

    You are presented with a dialog box asking you which type of add-in you wish to create.  Notice that all 8 different customizations are presented to you at this point.
  1. Choose toolbar and click OK.
A new section of the editor now appears with various properties for you to set for your new toolbar. By default, the id* and caption* properties are filled in for you with default values to help expedite the development process. The following figure shows you the new toolbar details section that is added to the editor with default values.

Setting properties

A toolbar has only 3 properties for you to set. The following is a list of all of the properties with an explanation for each:
  • id* - The id represents the unique name that is used to identify your toolbar. It is possible for you to create more than one toolbar for a given project and this id property is used to distinguish between the different toolbars.  Notice that the previous image shows a default value for this property. Ideally, you should replace this id with a more meaningful name. It is also highly recommended that the Java package naming convention is used when constructing your id property value. For example, com.esri.arcgis.arcmap.addin.arcmaptoolbar could be used to represent the toolbar being created for this document (Required).
  • caption* - The caption property is used to give a name to the toolbar and is used in two different locations after the project is deployed (Required).

    The first location is the Add-In Manager where the caption is used as meta-data to help a user identify the types of customizations available. The following example uses a value of "ArcMap Toolbar" for the caption property and is exposed in the Add-In Manager as follows (notice the container is identified as Toolbars):

    The second place that the caption is used is when a user is adding the toolbar to the user interface (UI) of a desktop application. The workflow for doing so is discussed in How to deploy your add-in. For reference, the customize dialog’s toolbars tab is used and will use the caption defined under the toolbars textbox as follows:

Adding functionality

At this stage, you have finished entering values for all of the properties needed to define your toolbar. This step looks at how you can add functionality to your toolbar container. A toolbar can contain your own tools, tool palettes, combo boxes, menus and buttons or the ones provided to you by ESRI. The following image gives you all of these different possibilities:
The dialog box on the left shows all of the possible types of add-ins that can be put into a toolbar container. All the types of add-ins that you define are considered custom and are designated with that keyword. This dialog also gives you the ESRI provided buttons and tools designated using system as the keyword. The dialog box on the right is used to show what the toolbar is containing. To add your functionality to the toolbar, do the following:
  1. Select the functionality you want to move.
  1. Click the arrow to move the piece of functionality to the right dialog box.
The other arrow is available to allow you to remove functionality from a toolbar if the functionality is undesired.
For example, this example moves the ArcMap button, tool and menu to the right dialog. The result of these actions would be the following:
In the editor, under the all add-ins section, you notice when you add different pieces of functionality to the toolbar container that your toolbar does not update automatically. In this special case, you need to click on your toolbar in this section to refresh its contents. The same is true when updating properties, but is less intuitive in this situation. When you click on the toolbar in this section, you’ll notice that the three items added now appear in this list as follows:
Another item worth noting is the organization of the toolbar itself. In the following scenario, you want to distinguish between the ArcMap button, tool and menu defined in your project. To create this logical separation you can add a separator between the tool and the menu. To do this, you can follow these steps:
  1. Select the piece of functionality you want to create the separator on (in this instance ArcMap Menu) under the toolbars header.

    Notice that the dialog to the right is updated in the following fashion when you execute step 1. The check box indicates your intention to have a separator.
  1. Check the box to define the separator.

    The result of doing step 2 is the following:

    Notice the gray bar between the ArcMap tool and menu. This is the separator defined in Eclipse and it can be placed accordingly depending on the groupings you wish to have for your toolbar.
Similar to adding your add-ins to a toolbar, you can also add any of the ESRI system provided buttons and tools by following the same methodology presented. This approach avoids having to re-invent the wheel if the functionality already exists in the desktop product you are customizing.

Setting the premier status, if applicable (Optional)

The final piece that is available to you when working with toolbars is the notion of a premier toolbar. If so desired, your toolbars can be enabled so that the first time a desktop application is opened, it will display your toolbar. By default, this behavior is not available and requires you to set a property in the project to enable it. This property is a check box that can be found under the toolbar details.
The check box that asks: "Do you want to show this when Application starts?" is used to indicate if the toolbar you are creating is a premier toolbar or not. This status is optional and by default it is checked off.

Understanding the config.xml

When setting all of the properties, the config.xml file was being generated behind the scenes for you. To understand more about how this config.xml file is created, see Understanding the config.xml document.

Creating different types of customizations

The following documentation showed you how to create a toolbar.  However, there are 7 additional types of add-ins that can be created and defined.  The following links will take you to those how-to documents.





Development licensing Deployment licensing
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo