In this topic
- Creating a toolbar
- Setting properties
- Adding functionality
- Setting the premier status, if applicable (optional)
- Understanding the config.xml
- Creating different types of customizations
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 to appear when a desktop application is started (referred to as a premier toolbar).
This topic guides you through the process of creating a toolbar using the Eclipse IDE. Before beginning this workflow, make sure that you have created an ArcMap add-in project using Eclipse. For more information, see How to create an add-in project in Eclipse.
Since there is no difference between creating a toolbar for any ArcGIS for Desktop application, this workflow shows how to create a toolbar for ArcMap. This topic shows how the toolbar contains the various add-ins or ESRI provided functionality. It also shows how to set a premier toolbar.
The workflow for creating a toolbar in Eclipse consists of the following steps (done in the order as show):
- Creating a toolbar—Examines the process of creating a toolbar in Eclipse.
- Setting properties—Examines the properties that can be set with descriptions.
- Adding functionality—Examines how functionality is added to the toolbar, either your add-ins or ESRI provided functionality.
- Setting the premier status, if applicable (optional)—Examines an optional choice you have to set the premier status of a toolbar.
Creating a toolbar
The following shows how to create a toolbar for an existing Eclipse add-in project. Ensure the Add-In view is enabled on the Add-In Editor for the config.xml file and that you have completed the required Add-In Overview properties. See the following screen shot:
- Under All Add-Ins on the Add-In Editor, click the Add button. The Create New Add-In dialog box appears. See the following screen shot:
- Select the Toolbar option on the preceding screen shot (there are eight different options), then click OK.
A new section of the Add-In Editor appears with various properties for you to set for your new toolbar. By default, the id* and caption* properties are completed with default values to help expedite the development process. The following screen shot shows the Toolbar Details section that is added to the Add-In Editor with default values:
Setting properties
A toolbar has several properties for you to set. The following is a list of all of the properties with an explanation for each:
- id*—Represents the unique name that is used to identify your toolbar. You can create more than one toolbar for a given project and this id property is used to distinguish between the different toolbars. The preceding screen shot shows a default value for this property. Ideally, you should replace this id with a more meaningful name. Use the Java package naming convention when constructing your id property value. For example, com.esri.arcgis.arcmap.addin.arcmaptoolbar could be used to represent the toolbar being created in this topic (required).
-
caption*—Used to name 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 metadata to help a user identify the types of customizations available. The following screen shot shows 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. For this workflow, see How to deploy your add-in. For reference, the Toolbar tab on the Customize dialog box is used (uses the caption defined under the Toolbars area). See the following screen shot:
- Do you want to show this when Application starts—For information on this check box, see the Setting the premier status, if applicable (optional) section in this topic.
Adding functionality
At this stage, you have finished adding values for all of the necessary properties to define your toolbar. This step looks at how you can add functionality to your toolbar container. A toolbar can contain your tools, tool palettes, combo boxes, menus, and buttons or ESRI provided functionality. See the following screen shot that shows these different possibilities:
On the preceding screen shot, the left side shows all possible add-in types that can be put onto a toolbar container. All the types of add-ins that you define are considered custom and are designated with that keyword. The screen shot also shows ESRI provided buttons and tools designated with System as the keyword. The right side is used to show what the toolbar contains. Do the following steps to add functionality to the tool palette:
-
On the left, select the functionality you want to move.
-
Click the arrow (>) to move the selected functionality to the right.
The other arrow (<) is available to remove selected functionality from the right if the functionality is not wanted.
For example, the following screen shot shows moving the ArcMap Button, ArcMap Tool, and ArcMap Menu to the right:
On the Add-In Editor, under the All Add-Ins section, you will notice when you add different pieces of functionality to the toolbar container that your toolbar does not automatically update. In this case, click 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 the toolbar in this section, you will notice that the three added items now appear in the list as shown on the following screen shot:
Also, notice the organization of the toolbar. In the following scenario, you want to distinguish between the ArcMap Button, ArcMap Tool, and ArcMap Menu defined in your project. To create this logical separation, you can add a separator between the tool and the menu by doing the following steps:
-
Select the piece of functionality on which to create the separator (that is, ArcMap Menu) under the toolbars header. See the following screen shot:
-
Select the Is this a separator check box to define the separator. The following screen shot shows the result of this step:
Notice the gray bar between ArcMap Tool and ArcMap Menu. This is the separator defined in Eclipse and it can be placed accordingly depending on the groupings you want to have for your toolbar.
Similar to adding your add-ins to a toolbar, you can also add any ESRI system provided buttons and tools by following the same methodology. This approach avoids having to redo the functionality that already exists in the desktop product you are customizing.
Setting the premier status, if applicable (optional)
The final step when working with toolbars, is a premier toolbar. If applicable, your toolbars can be enabled so that the first time a desktop application opens, it shows your toolbar. By default, this behavior is not available and requires you to select the "Do you want to show this when Application starts" check box on the Toolbar Details to enable it. See the following screen shot:
The "Do you want to show this when Application starts" check box is used to indicate if the toolbar is a premier toolbar. This check box is optional and by default, not selected.
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
This topic showed how to create a toolbar. However, there are additional types of add-ins that can be created and defined. See the following topics that discuss each type of add-in.
| Development licensing | Deployment licensing |
|---|---|
| ArcGIS for Desktop Basic | ArcGIS for Desktop Basic |
| ArcGIS for Desktop Standard | ArcGIS for Desktop Standard |
| ArcGIS for Desktop Advanced | ArcGIS for Desktop Advanced |