Pop-up Menus

Identifier: org.eclipse.ui.popupMenus

Description: This extension point is used to add new actions to pop-up menus owned by other plug-ins. Action contribution may be made against a specific object type (objectContribution) or against a specific popup menu. When registered for an object type, a contribution will appear in all viewers where objects of the specified type are selected. In contrast, registration against a popup menu will only appear in the specified menu, regardless of the selection.

When selection is heterogeneous, contribution will be applied if registered against a common type of the selection, if possible. If a direct match is not possible, matching against superclasses and superinterfaces will be attempted.

Selection can be further constrained through the use of a name filter. If used, all the objects in the selection must match the filter in order to apply the contribution.

Individual actions in an object contribution can use attribute enablesFor to specify if it should only apply for a single, multiple, or any other selection type.

If these filtering mechanisms are inadequate an action contribution may use the filter mechanism. In this case the attributes of the target object are described in a series of key value pairs. The attributes which apply to the selection are type specific and beyond the domain of the workbench itself, so the workbench will delegate filtering at this level to the actual selection.

Configuration Markup:

   <!ELEMENT objectContribution (filter | menu | action)* (visibility)?>
   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
      objectClass CDATA #REQUIRED
      nameFilter CDATA #IMPLIED
      adaptable   (true|false) #IMPLIED
   >

id - a unique identifier that can be used to reference this contribution.
objectClass - a fully qualified name of the class or interface that all the objects in the selection must subclass or implement.
nameFilter - an optional filter that will be applied against each object in the selection. No contribution will take place if there is no match.
adaptable - a flag that indicates if types that adapt to IResource should use this object contribution. This flag is used only if objectClass adapts to IResource. Default value is false.

In version 2.0 of Eclipse, a visibility element may be used in an objectContribution to define the visibility for the action. This is not a replacement for the objectClass attribute, which defines the primary target for the action. The visibility element is used to refine the primary target. For more information on the use of visibility element, refer to actionExpressions.html.

   <!ELEMENT viewerContribution (menu | action)*>
   <!ATTLIST viewerContribution
      id        CDATA #REQUIRED
      targetID CDATA #REQUIRED
   >

id - a unique identifier that can be used to reference this contribution.
targetID - the unique identifier of a popup menu inside a view, editor or viewer.

   <!ELEMENT filter EMPTY>
   <!ATTLIST filter
      name       CDATA #REQUIRED
      value      CDATA #REQUIRED
   >

name - the name of an object attribute.
value - the value of an object attribute. In combination with the name attribute, the name value pair is used to define the target object for an object action contribution.

   <!ELEMENT menu (separator)+>
   <!ATTLIST menu
      id         CDATA #REQUIRED
      label      CDATA #REQUIRED
      path       CDATA #IMPLIED
   >

id - a unique identifier that can be used to reference this submenu.
label - the text label of the new menu. The label should include mnemonic information.
path - the location of the submenu starting from the pop-up menu as a root. If omitted, the menu will be added at the end of the pop-up menu.

   <!ELEMENT separator EMPTY>
   <!ATTLIST separator
      name       CDATA #REQUIRED
   >

name - the name of the separator that can later be referenced as the last token in the action path. Therefore, separators serve as named groups into which actions can be added.

   <!ELEMENT action (selection)* (enablement)?>
   <!ATTLIST action
      id                NMTOKEN #REQUIRED
      label             CDATA #REQUIRED
      menubarPath       CDATA #IMPLIED
      icon              CDATA #IMPLIED
      helpContextId     CDATA #IMPLIED
      state             (true | false) #IMPLIED
      class             CDATA #REQUIRED
      enablesFor        CDATA #IMPLIED
   >

id - a unique identifier that can be used as a reference for this action.
label - a translatable name that will be used for a pop-up menu item label. The label can contain JFace-encoded mnemonic (see example).
menubarPath - a slash-delimited path ('/') that is used to specify the location of the action in the pop-up menu. Each token in the path except the last one represents an existing submenu in the hierarchy. The last token represents the named separator group into which the action will be added. If the path is omitted, the action will be added to the standard additions group defined by IWorkbenchActionConstants.MB_ADDITIONS.
icon - a relative path for an icon that will be used to visually represent the action in the pop-up menu. The path is relative to the location of the plugin.xml file of the contributing plug-in.
state - an optional attribute indicating that the action should be of a toggle type. When added to a pop-up menu, it will manifest itself as a check box item.. If defined, attribute value will be used as the initial state (either true or false)
helpContextId - a unique identifier indicating the help context id for this action. When the action appears as a menu item, pressing F1 while the menu item is highlighted will display help for the given context id.
class - a name of the fully qualified class that implements org.eclipse.ui.IObjectActionDelegate(for object actions), org.eclipse.ui.IViewActionDelegate (for view-related viewer actions), or org.eclipse.ui.IEditorActionDelegate (for editor-related viewer actions). For backwards compatability, org.eclipse.ui.IActionDelegate may be implemented for object contributions.
enablesFor - a value indicating the selection count which must be met to enable the action. If this attribute is specified and the condition is met the action is enabled. If the condition is not met the action is disabled. If no attribute is specified the action is enabled for any number of items selected. The following attribute formats are supported:

multiple, 2+

   <!ELEMENT selection EMPTY>
   <!ATTLIST selection
      class             CDATA #REQUIRED
      name              CDATA #IMPLIED
   >

class - a fully qualified name of the class or interface that each object in the selection must subclass or implement in order to enable the action.
name - a wild card filter for the name that can optionally be applied to objects in the selection. If this filter is specified and the match fails, the action will be disabled.

In version 2.0 of Eclipse, an enablement element may be used to define the enablement for the action. For more information on the use of enablement element, refer to actionExpressions.html.

The enablement criteria for an action extension are initially defined by enablesFor, selection and enablement. However, once the action delegate has been instantiated, it may control the action enable state directly within its selectionChanged method.

Action and menu labels may contain special characters that encode mnemonics which are specified using the ampersand ('&') character in front of a selected character in the translated text. Since ampersand is not allowed in XML strings, use & character entity.

If two or more actions are contributed to a menu or toolbar by a single extension the actions will appear in the reverse order of how they are listed in the plugin.xml file. This behavior is admittedly unintuitive. However, it was discovered after the Eclipse Platform API was frozen. Changing the behavior now would break every plug-in which relies upon the existing behavior.

Examples:

The following is an example of a pop-up menu extension point:

   <extension point="org.eclipse.ui.popupMenus">
      <objectContribution
         id="com.xyz.C1"
         objectClass="org.eclipse.core.resources.IFile"
         nameFilter="*.java">
         <menu id="com.xyz.xyzMenu"
               path="additions"
               label="&XYZ Java Tools">
            <separator name="group1"/>
         </menu>
         <action id="com.xyz.runXYZ"
              label="&Run XYZ Tool"
              menubarPath="com.xyz.xyzMenu/group1"
              icon="icons/runXYZ.gif"
              helpContextId="com.xyz.run_action_context"
              class="com.xyz.actions.XYZToolActionDelegate"
              enablesFor="1">
          </action>
        </objectContribution>
        <viewerContribution
           id="com.xyz.C2"
           targetID="org.eclipse.ui.views.TaskList">
           <action id="com.xyz.showXYZ"
                   label="&Show XYZ"
                   menubarPath="additions"
                   icon="icons/showXYZ.gif"
                   helpContextId="com.xyz.show_action_context"
                   class="com.xyz.actions.XYZShowActionDelegate">
           </action>
        </viewerContribution>
     </extension>

In the example above, the specified action will only enable for a single selection (enablesFor attribute). In addition, each object in the selection must implement the specified interface (IFile) and must be a Java file. This action will be added into a submenu previously created. This contribution will be effective in any view that has the required selection.

In contrast, the viewer contribution above will only appear in the Tasks view, and will not be affected by the selection in the view.

The following is an example of the filter mechanism. In this case the action will only appear for IMarkers which are completed and have high priority.

   <extension point="org.eclipse.ui.popupMenus">
      <objectContribution
         id="com.xyz.C1"
         objectClass="org.eclipse.core.resources.IMarker">
         <filter name="done" value="true"/>
         <filter name="priority" value="2"/>
         <action id="com.xyz.runXYZ"
              label="High Priority Completed Action Tool"
              icon="icons/runXYZ.gif"
              class="com.xyz.actions.MarkerActionDelegate">
          </action>
        </objectContribution>
     </extension>

API Information: The value of the action attribute class must be a fully qualified class name of a Java class that implements org.eclipse.ui.IObjectActionDelegatein the case of object contributions, org.eclipse.ui.IViewActionDelegate for contributions to viewers that belong to views, or org.eclipse.ui.IEditorActionDelegate for contributions to viewers that belong to editors. In all cases, the implementing class is loaded as late as possible to avoid loading the entire plug-in before it is really needed.

Note: For backwards compatability, org.eclipse.ui.IActionDelegate may be implemented for object contributions.

Popup menu extension within a part is only possible when the target part publishes a menu for extension. This is heartily encouraged, as it improves the extensability of the product. To accomplish this each part should publish any popup menus which are defined by calling IWorkbenchPartSite#registerContextMenu. Once this has been done the workbench will automatically insert any action extensions which exist.

A menu id must be provided for each registered menu. For consistency across parts the following strategy should be adopted by all part implementors.

If the target part has only one context menu it should be registered with id == part id. This can be done easily by calling registerContextMenu(MenuManager, ISelectionProvider). Extenders may use the part id itself as the targetID for the action extension.
If the target part has more than one context menu a unique id should be defined for each. Prefix each id with the part id and publish these id's within the javadoc for the target part. Register each menu at runtime by calling registerContextMenu(String, MenuManager, ISelectionProvider). Extenders will use the unique menu id as the targetID for the action extension.

Any pop-up menu which is registered with the workbench should also contain a standard insertion point with id IWorkbenchActionConstants.MB_ADDITIONS. Other plug-ins will use this value as a reference point for insertion. The insertion point may be defined by adding a GroupMarker to the menu at an appropriate location for insertion.

An object in the workbench which is the selection in a context menu may define an org.eclipse.ui.IActionFilter. This is a filtering strategy which can perform type specific filtering. The workbench will retrieve the filter for the selection by testing to see if it implements IActionFilter. If that fails, the workbench will ask for a filter through the IAdaptable mechanism.

Supplied Implementation: The workbench views have built-in pop-up menus that already come loaded with a number of actions. Plug-ins can contribute to these menus. If a view has reserved slots for these contributions and they are made public, slot names can be used as paths. Otherwise, actions and submenus will be added at the end of the pop-up menu.