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.  We'll look at paths by looking at the workbench Help menu.

Named groups

The locations for inserting new menus, menu items, or tool bar 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 and toolbar contributions at certain points in a menu or toolbar.

The workbench defines all of its group slot names in the class IWorkbenchActionConstants. 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"
   About action - ABOUT - "About"

The standard workbench help menu consists of a named group called "start," followed by a named group called "end," followed by the "About" action. Defining two groups gives plug-ins 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.

But wait!  We know that there are other menu items on the Help menu.  These are added by plug-ins.  For example, the help plug-in adds an action set containing the "Help Contents" menu to the workbench.  Here's the markup from the org.eclipse.help.ui plug-in's plugin.xml.

<extension point="org.eclipse.ui.actionSets">
	<actionSet
		id="org.eclipse.help.internal.ui.HelpActionSet"
		label="%help"
		visible="true">
			
	<action id="org.eclipse.help.internal.ui.HelpAction"
		menubarPath="help/helpEnd"
		label="%helpcontents"
		class="org.eclipse.help.ui.internal.HelpContentsAction"
		icon="icons/view.gif"
		helpContextId="org.eclipse.help.ui.helpContentsMenu"
		tooltip="%openhelpcontents"/>
	...

The new help action will be placed in the help menu, inside the helpEnd group. If no other plug-in has contributed to the help menu, this means the "Help Contents" menu item will appear as the first item in the menu above the "About" item. If another plug-in wanted to contribute an item that always appeared above the "Help Contents" item, then it could specify the helpStart group on its path.  

Toolbar paths work similarly. Whenever a path is specified, it must end with the name of a group in the toolbar.

Fully qualified menu and tool paths

A complete menu or toolbar path is simply "menu name/group name."  Menu names for the workbench are defined in IWorkbenchActionConstants. This class is used to 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 (e.g. %help, %helpcontents) and creating entries in the plugin.properties file of the form:

   help = "Help"
   helpContents = "Help Contents"

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 and toolbars.

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 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.  It's possible that a future version of the plug-in could change the names of the paths.  The recommended practice is to 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.

Copyright IBM Corp. and others 2000,2002.