org.jlense.uiworks.popupMenus Extension Point

Identifier: org.jlense.uiworks.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)*>
   <!ATTLIST objectContribution
      id          CDATA #REQUIRED
      objectClass CDATA #REQUIRED
      nameFilter  CDATA #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.

   <!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 EMPTY>
 <!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 and accelerator (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.jlense.uiworks.workbench.IObjectActionDelegate (for object actions), org.jlense.uiworks.workbench.IViewActionDelegate (for view-related viewer actions). For backwards compatability, org.jlense.uiworks.workbench.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:
  • ! - 0 items selected
  • ? - 0 or 1 items selected
  • + - 1 or more items selected
  • multiple, 2+ - 2 or more items selected
  • n - a precise number of items selected. Example: 4.
  • * - any number of items selected

The enablement criteria for an action extension are initially defined by enablesFor and selection. 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 and accelerators using the following rules:

1. Mnemonics 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.
2. Optional accelerators are specified at the and of the name string, using '@' followed by the series of modifiers and the final accelerator character (for example, &Save@Ctrl+S). Accelerators with more than one modifier are obtained by chaining modifiers, using the '+' sign as the delimiter (as in @Ctrl+Shift+S).

Examples:

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

   <extension point="org.jlense.uiworks.popupMenus">
      <objectContribution
      id="com.xyz.C1"
      objectClass="org.eclipse.core.resources.IFile"
      nameFilter="*.java">
         <menu id="com.xyz.xyzMenu"
         path="additions"
         label="&amp;XYZ Java Tools">

            <separator name="group1"/>
         </menu>
         <action id="com.xyz.runXYZ"
         label="&amp;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="&amp;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.jlense.uiworks.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.jlense.uiworks.workbench.IObjectActionDelegate in the case of object contributions, org.jlense.uiworks.workbench.IViewActionDelegate for contributions to viewers that belong to views. 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.jlense.uiworks.workbench.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 view 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.

An object in the workbench which is the selection in a context menu may define an org.jlense.uiworks.workbench.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 view have built-in pop-up menus that already come loaded with a number of actions. Plug-ins can contribute to these menus. If a viewer 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.