## Menu and toolbar paths

We've seen many action contributions that specify the path for the location of their action. Let's take a close look at what these paths mean.

### Menu paths

We'll look at menu paths first by looking at the workbench Help menu.

#### Named groups in the workbench

The locations for inserting new menus and menu items are defined using named groups. You can think of a named group as a slot or placeholder that allows you to insert your menu items at certain points in a menu bar or pulldown menu.

The workbench defines all of its group slot names in the classes IWorkbenchActionConstants and IIDEActionConstants. (Two different classes are used since resource-related menu items are factored out of the generic workbench). For each workbench menu, named groups are placed in the menu at locations where it is expected that plug-ins will insert new actions.

The following description of the help menu is adapted from the IWorkbenchActionConstants class definition.

       Standard Help menu actions
       Start group - HELP_START - "start"
       End group - HELP_END - "end"

The standard workbench help menu defines a named group called "start," followed by a named group called "end,". Defining two groups gives plug-ins a little more control over where their contributed items will be positioned within the help menu. When you define a menu, you can define as many slots as you like. Adding more slots gives other plug-ins more control over where their contributions appear relative to existing contributions.

Plug-ins that add a menu item to the help menu can use these group names to decide where their menu item will go. For example, the cheatsheet plug-in adds an action set containing the "Cheat Sheets..." menu to the workbench. Here's the markup from the org.eclipse.ui.cheatsheets plug-in's plugin.xml.

    <extension
    	point="org.eclipse.ui.actionSets">
    	<actionSet
    		label="%CHEAT_SHEETS"
    		visible="true"
    		id="org.eclipse.ui.cheatsheets.actionSet">
    		<action
    			label="%CHEAT_SHEETS_MENU"
    			class="org.eclipse.ui.internal.cheatsheets.actions.CheatSheetHelpMenuAction"
    			menubarPath="help/helpStart"
    			id="org.eclipse.ui.cheatsheets.actions.CheatSheetHelpMenuAction">
    		</action>
    	</actionSet>
    </extension>

The new help action will be placed in the help menu, inside the helpStart group.

#### Fully qualified menu paths

A complete menu path is simply "menu name/group name." Most menu names for the workbench are defined in IWorkbenchActionConstants. (Resource-related menu names are defined in IIDEActionConstants.) If we look for the name of the help menu in this class, we'll find that the fully qualified path name for our help action is "help/helpEnd."

Some menus have nested submenus. This is where longer paths come into play. If the help menu had defined a submenu called "submenu" with a named group called "submenuStart," then the fully qualified menu path for an action in the new submenu would be "help/submenu/submenuStart."

#### Externalizing UI labels

The example above demonstrates a technique for externalizing strings that appear in the UI. Externalized strings are used to make translating the plug-in's UI to other languages simpler. We can externalize the strings in our plugin.xml files by replacing the string with a key (%CHEAT_SHEETS_MENU) and creating entries in the plugin.properties file of the form:

    	CHEAT_SHEETS_MENU = Cheat Sheets...

The plugin.properties file can be translated for different languages and the plugin.xml will not need to be modified.

#### Adding new menus and groups

In many of the examples we've seen so far, the actions contributed by the sample plug-ins have been added to existing named groups within menus.

The actionSets, viewActions, editorActions, and popupMenus extension points also allow you to define new menus and groups within your contribution. This means that you can define new submenus or new pull-down menus and contribute your actions to these new menus. In this case, the path for your new action will contain the name of your newly defined menu.

We saw this technique when the readme tool defined a new menu for its action set. Let's look at the markup one more time now that we've looked at menu paths in more detail.

       <extension point = "org.eclipse.ui.actionSets">
       <actionSet id="org_eclipse_ui_examples_readmetool_actionSet"
    	   label="%ActionSet.name"
    	   visible="true">
    	   <menu id="org_eclipse_ui_examples_readmetool"
    		   label="%ActionSet.menu"
    		   path="window/additions">
    		   <separator name="slot1"/>
    		   <separator name="slot2"/>
    		   <separator name="slot3"/>
    	   </menu>
    	   <action id="org_eclipse_ui_examples_readmetool_readmeAction"
    		   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
    		   toolbarPath="readme"
    		   label="%ReadmeAction.label"
    		   tooltip="%ReadmeAction.tooltip"
    		   helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
    		   icon="icons/ctool16/openbrwsr.gif"
    		   class="org.eclipse.ui.examples.readmetool.WindowActionDelegate"
    		   enablesFor="1">
    		   <selection class="org.eclipse.core.resources.IFile"
    				name="*.readme">
    		   </selection>
    	   </action>
    	   ...

We added a new menu called "org_eclipse_ui_examples_readmetool" whose label is defined in by the key "%ActionSet.name" in the properties file. Within this menu, we define three named groups: "slot1," "slot2," and "slot3." We add this new menu to the path "window/additions."

If we go back to IWorkbenchActionConstants, we see this definition of the window menu in the javadoc:

        * <h3>Standard Window menu actions</h3>
        * <ul>
        * <li>Extra Window-like action group (<code>WINDOW_EXT</code>)</li>

If we look further at the class definition, we will see these related definitions:

       public static final String MENU_PREFIX = "";
       ...
       public static final String M_WINDOW = MENU_PREFIX+"window";
       ...
       public static final String MB_ADDITIONS = "additions";  // Group.
       ...
       public static final String WINDOW_EXT = MB_ADDITIONS;   // Group.

From this information, we can piece together the path for adding something to the workbench "Window" menu. The menu itself is called "window" and it defines one slot called "additions." We use the path "window/additions" to add our new menu.

In the action set declaration, we add an action to our newly defined menu, using the path "window/org_eclipse_ui_examples_readmetool/slot1."

Other plug-ins could add to our menu by using this same path (or perhaps one of the other slots) to add one of their own menus.

In the readme tool example, we use the separator attribute to identify the group names. This will cause a separator line to appear between these groups when they contain items. We could instead use the groupMarker attribute if we want to define a named group without showing any separators in the menu to distinguish between the groups.

### Tool bar paths

Tool bar paths work similarly to menu paths.

#### Named tool bars in the workbench

The workbench tool bar is composed of tool bars contributed by different plug-ins, including the workbench itself. Within any particular tool bar, there are named groups or slots that can be used for inserting new tool bar items.

The following description of the workbench tool bars is adapted from the IWorkbenchActionConstants class definition.

    // Workbench toolbar ids
    public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file"
    public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate";

    // Workbench toolbar group ids.  To add an item at the beginning of the group,
    // use the GROUP id.  To add an item at the end of the group, use the EXT id.
    public static final String PIN_GROUP = "pin.group";
    public static final String HISTORY_GROUP = "history.group";
    public static final String NEW_GROUP = "new.group";
    public static final String SAVE_GROUP = "save.group";
    public static final String BUILD_GROUP = "build.group";

In the simplest case, a plug-in can contribute a tool bar item in its own tool bar. For example, the readme tool actions contributed to the menu are also given a tool bar path:

    ...
    <action id="org_eclipse_ui_examples_readmetool_readmeAction"
       menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
       toolbarPath="readme"
    ...

Since there is no reference to the workbench tool bar paths or groups, the readme actions appear in their own group on the tool bar. Specifying the following path would instead place the item in the file tool bar in the save group:

    ...
    <action id="org_eclipse_ui_examples_readmetool_readmeAction"
       menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
       toolbarPath="org.eclipse.ui.workbench.file/save.group"
    ...

The paths defined in IWorkbenchActionConstants may be referenced in the tool bar paths of other plug-ins.

#### Adding to action sets of another plug-in

Suppose a plug-in wants its tool bar items better integrated with actions from a different plug-in? Let's look at how the external tools plug-in (org.eclipse.ui.externaltools) integrates its action with the debugger tool bar. The debugger (org.eclipse.debug.ui) defines its tool bar actions like this:

    <extension
          point="org.eclipse.ui.actionSets">
       <actionSet
             label="%LaunchActionSet.label"
             visible="false"
             id="org.eclipse.debug.ui.launchActionSet">
       ...
       <action
             toolbarPath="debug"
             id="org.eclipse.debug.internal.ui.actions.RunDropDownAction"
             hoverIcon="icons/full/ctool16/run_exc.gif"
             class="org.eclipse.debug.internal.ui.actions.RunToolbarAction"
             disabledIcon="icons/full/dtool16/run_exc.gif"
             icon="icons/full/etool16/run_exc.gif"
             helpContextId="run_action_context"
             label="%RunDropDownAction.label"
             pulldown="true">
       </action>
       ...

Just like the readme tool, the debugger plug-in defines its own tool bar path, which means its tool bar items will be inside their own tool bar on the workbench. What does the external tools plug-in do?

    <extension point="org.eclipse.ui.actionSets">
    	<actionSet
    		id="org.eclipse.ui.externaltools.ExternalToolsSet"
    		label="%ActionSet.externalTools"
    		visible="true">
    		...
    		<action
    			id="org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
    			definitionId= "org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
    			label="%Action.externalTools"
    			toolbarPath="org.eclipse.debug.ui.launchActionSet/debug"
    			disabledIcon="icons/full/dtool16/external_tools.gif"
    			icon="icons/full/etool16/external_tools.gif"
    			hoverIcon="icons/full/ctool16/external_tools.gif"
    			tooltip="%Action.externalToolsTip"
    			pulldown="true"
    			class="org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate">
    		</action>
    	</actionSet>
    </extension>

Note the use of the action set ID of the debugger in the tool bar path. Using an action set ID in the path denotes that the tool bar item should be placed in the tool bar used by the referenced action set. Within a toolbar group, items are ordered by action set id, so for our example, the external tools action will appear after the debugger actions.

When adding to an action set's tool bar, new groups can also be defined. If the external tools plug-in defined its toolbarpath as "org.eclipse.debug.ui.launchActionSet/external" a new group would be created for the action on the tool bar. As with menus, tool bar groups are delineated by separators.

### Using paths from another plug-in

In general, it's not good practice to contribute to another plug-in's menu or tool bar by deriving the path name from the plugin.xml unless it has been marked specifically as being available for clients. It's possible that a future version of the plug-in could change the names of the paths. Two common ways to mark your plug-in's action set ids and paths as fair game are:

- annotate the XML with comments that explicitly mark the menu path or action set as usable by clients
- define a public interface (much like IWorkbenchActionConstants) which specifies exactly which menus, tool bar groups, and slots are considered fair game for use by other plug-ins