How to create an add-in menu

Summary This document will guide 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. These buttons can be your own buttons or the ESRI provided system buttons and menus can only be your own custom menus. In addition, menus can be exposed by adding them to an existing toolbar (see How to create an add-in toolbar for more information on creating your own toolbar) or by setting a particular property to make it available in a particular category in the customize dialog.
The following will guide you through the process of creating a menu 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 menu for any one of the ArcGIS Desktop applications, this workflow shows you how to create a menu that can be consumed in ArcMap. This document will show how the menu can be used to contain your buttons or ESRI provided buttons as well as your custom menus. It will also demonstrate how to expose your menu so it can be consumed in ArcMap.
The workflow for creating a menu in Eclipse consists of the following steps:
  1. Creating a new menu
  2. Setting properties
  3. Adding functionality
  4. Adding a menu to a toolbar
Step 1 will examine the process of creating a new menu in Eclipse. Step 2 will examine all of the properties that can be set for the menu with detailed descriptions. Step 3 will examine how existing functionality is added to the menu, either your own add-ins or ESRI provided functionality. The final step examines the process of adding a menu to a toolbar so it can be exposed in an ArcGIS Desktop application after the project is deployed.

Creating a new menu

The following will show you how to create a new menu 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 types of add-ins are presented to you at this point.
  1. Choose menu and click OK.
A new section of the editor now appears with various properties for you to set for your new menu. 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 menu details section that is added to the editor with default values.

Setting properties

A menu 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 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 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.arcmapmenu could be used to represent the menu being created for this document (Required).
  • caption* - The caption property is used to give a name to the menu and is used in two locations after a project is deployed (Required).

    The first location that the caption is used is as meta-data in the Add-In Manager to help an end user identify the types of customizations available. The following example uses 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 (see the check box for this option). This option is explained in detail next. If this option is checked on, however, then the menu caption will appear in the commands tab of the customize dialog as shown next:

    Notice the special category used to identify root menus found on ArcMap’s standard toolbar. Your custom menu now appears as part of this category and the caption is used to identify your menu.
  • Is this a root menu - As described, if this option is checked, then your menu gets added to the special menus category and is identified using the caption property. By default, this property is off and thus your menu can only be exposed through a toolbar.

Adding functionality

At this stage, you have finished entering 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 own buttons or the ones provided to you by ESRI. In addition, you can nest existing menus. The following image illustrates 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 menu container. All menus that you define are considered menus and are designated with the keyword. This dialog also gives you the ESRI provided buttons designated using system as the keyword. The dialog box on the right is used to show what the menu contains. To add your functionality to the menu, 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 menu if the functionality is undesired.
For example, this example moves the ArcMap button, ArcMap menu 2 along with the ESRI provided fixed zoom in and fixed zoom out buttons. The result of these actions would give the following:
Similar to adding your add-ins to a menu, you can also add any of the ESRI system provided buttons 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.

Adding a menu to a toolbar

If your menu is not enabled as a root menu, then you must add your menu to a toolbar (you can add a root menu to a toolbar if you wish to do so) before deploying your project. To achieve this, do the following:
  1. See How to create an add-in toolbar for details on creating a toolbar.
  2. Select your toolbar under the all add-ins section of the editor.
  3. Using the technique explored previously, add your menu to your new toolbar.
See How to deploy your add-in for information about consuming menus that are connected with your toolbars.

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