How to create an add-in menu

Summary
This topic guides you through the workflow for creating a menu using the Eclipse integrated development environment (IDE). A menu is a container for buttons or menus that you have created, or ESRI provided buttons.

In this topic

About the menu

A menu is a container for buttons or menus. Buttons can be your buttons or ESRI provided system buttons, and menus can only be your custom menus. In addition, menus can be exposed by adding them to an existing toolbar or by setting a specific property to make it available in a particular category on the Customize dialog box. For more information on creating toolbars, see How to create an add-in toolbar.
The following guides you through the process of creating a menu 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 menu for any ArcGIS for Desktop application, this workflow shows you how to create a menu that can be consumed in ArcMap. This topic shows how the menu can be used to contain your buttons or ESRI provided buttons, as well as custom menus. It also shows how to expose your menu so it can be consumed in ArcMap.
The workflow for creating a menu in Eclipse consists of the following (done in the order as shown):
  • Creating a menu—Examines the process of creating a menu in Eclipse.
  • Setting properties—Examines all of the properties that can be set for the menu with detailed descriptions.
  • Adding functionality—Examines how existing functionality is added to the menu, either your add-ins or ESRI provided functionality.
  • Adding a menu to a toolbar—Examines the process of adding a menu to a toolbar so it can be exposed in an ArcGIS for Desktop application after the project is deployed.

Creating a  menu

The following shows how to create a menu 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:

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


  1. Select the Menu 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 menu. By default, the id* and caption* properties are completed with default values to help expedite the development process. The following screen shot shows the new Menu Details section that is added to the editor with default values:

Setting properties

A menu has three properties for you to set. The following is a list of the properties with an explanation for each:
  • id*—Represents the unique name that is used to identify the menu. It is possible for you to create more than one menu for a given project and this id* property is used to distinguish between the different menus. Notice that 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.arcmapmenu could be used to represent the menu being created in this topic (required).
  • caption*—Used to give a name to the menu and used in two locations after a project is deployed (required).

    The first location is the Add-In Manager, where the caption is used as metadata to help an end user identify the different types of customizations available. The following screen shot shows a value of ArcMap Menu for the caption property and is exposed in the Add-In Manager as follows:



    The second location that the caption is used requires that the menu you are defining is a root menu (that is, Is this a root menu check box, explained next). If this check box is selected, the menus caption appears under the Commands area on the Customize dialog box. Notice the special category used to identify root menus found on ArcMap's standard toolbar. The custom menu now appears as part of this category and the caption is used to identify the menu. See the following screen shot:


  • Is this a root menu—As previously described, if this check box is selected, the menu gets added to the special [Menus] category and is identified using the caption property. By default, this property is not selected and thus, your menu can only be exposed on a toolbar.

Adding functionality

At this stage, you have finished adding values for all of the properties needed to define your menu. This step looks at how you can add functionality to your menu container. A menu can contain your buttons or ESRI provided buttons. In addition, you can nest existing menus. See the following screen shot that shows these different possibilities:

The left side on the preceding screen shot shows the possible types of add-ins that can be put into a menu container. All menus that you define are considered menus and are designated with the Menus keyword. The preceding screen shot also shows the ESRI provided buttons by using System as the keyword. The right side on the screen shot shows what the menu contains. Do the following steps to add your functionality to the menu:
  1. Select the functionality on the left that you want to move.
  1. Click the arrow (>) to move the functionality to the right side.
The other arrow (<) allows you to remove functionality from a menu if the functionality is not applicable.
For example, the following screen shot shows ArcMap Button, ArcMap Menu 2, Fixed Zoom In, and Fixed Zoom Out  (provided by ESRI) being moved to the right side:
Similar to adding your add-ins to a menu, you can also add any ESRI system provided buttons by following the same methodology. This approach avoids having to redo the functionality that already exists in the desktop product you are customizing.

Adding a menu to a toolbar

If your menu is not enabled as a root menu, you must add your menu to a toolbar (you can add a root menu to a toolbar if you want) before deploying your project. Do the following steps to achieve this:
  1. See the previously referenced topic, How to create an add-in toolbar, for details on creating a toolbar.
  2. Select your toolbar under the All Add-ins section in the editor.
  3. Using the previously discussed technique, add the menu to your new toolbar.
For information about consuming menus that are connected with your toolbars, see How to deploy your add-in.

Understanding the config.xml file

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

Creating different types of customizations

This topic showed how to create a menu. 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