org.jlense.uiworks.actionSets Extension Point

Identifier: org.jlense.uiworks.actionSets

Description: This extension point is used to add menus, menu items and toolbar buttons to the common areas in the workbench window. These contributions are collectively known as an action set.

Configuration Markup:

   <!ELEMENT actionSet (menu)* (action)* (description?)>
   <!ATTLIST actionSet
      id        CDATA #REQUIRED
      label     CDATA #REQUIRED
      visible   (true | false) #IMPLIED
    >
    <!ELEMENT description (#PCDATA)>

  • id - a unique name that will be used to identify this action set.
  • label - a translatable name that will be used in the workbench window menu to represent this action set.
  • visible - an optional attribute indicating whether the action set should be initially visible in the workbench window.
  • description - an optional subelement whose body should contain text providing short description of the action set.

   <!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 menu
  • label - a text label of the new menu. The label should include mnemonic information.
  • path - a location of the menu starting from the root of the menu bar. If omitted, the menu will be added between the Perspective and Window menus on the menu bar. Each token in the path must refer to an existing menu in the workbench, except the last one, which should represent a named group in the last menu in the path.

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

  • name - a 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 and submenus can be added.

    •    <!ELEMENT action (selection)*>
   <!ATTLIST action
      id               NMTOKEN #REQUIRED
      label            CDATA #REQUIRED
      menubarPath      CDATA #IMPLIED
      toolbarPath      CDATA #IMPLIED
      icon             CDATA #IMPLIED
      tooltip          CDATA #IMPLIED
      helpContextId    CDATA #IMPLIED
      state            (true | false) #IMPLIED
      pulldown         (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 is used in various ways, depending on the context. In menus, it is used as the menu text. In toolbars, it is used as the button label. The label can contain JFace-encoded mnemonic and accelerator information (see example).
    • menubarPath - a slash-delimited path ('/') that is used to specify the location of the action in the menu bar. Each token in the path except the last one must represent a valid ID of an existing menu 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 not appear in the menu bar.
    • toolbarPath - a slash-delimited path ('/') that is used to specify the location of the action in the toolbar. The first token represents the toolbar ID (with "Normal" being the default toolbar), while the second token is the named group within the toolbar. If the group does not exist in the toolbar, it will be created. If toolbarPath is omitted, the action will not appear in the tool bar.
    • icon - a relative path of an icon that will be used to visually represent the action in its context. If it is omitted and the action should appear in the toolbar, the workbench will use a place holder icon. The path is relative to the location of the plugin.xml file of the contributing plug-in.
    • tooltip - a value of the tool tip text if the action is to appear in the toolbar. Otherwise, it is ignored.
    • helpContextId - a unique identifier indicating the help context id for this action. If the action appears as a menu item, then pressing F1 while the menu item is highlighted will display help for the given context id.
    • state - an optional attribute indicating that the action should be of a toggle type. When added to a menu, it will manifest itself as a check box item. When added to a toolbar, it will become a toggle button. If defined, the attribute value will be used as the initial state (either true or false). This attribute is mutually exclusive with pulldown.
    • pulldown - an optional attribute indicating that the action has an additional pulldown menu. If the action appears in a toolbar, and the attribute value is true, a pulldown menu will appear beside the action. If the action appears in a menu this attribute is ignored. This attribute is mutually exclusive with state.
    • class - a fully qualified name of a class which implements org.jlense.uiworks.workbench.IWorkbenchWindowActionDelegate or org.jlense.uiworks.workbench.IWorkbenchWindowPulldownDelegate. The latter should be implemented in cases where pulldown is true.
    • 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

       <!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.
    It is important to note that the workbench does not generate menus on plug-in's behalf: menu paths must reference menus that already exist.

    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 &amp; character entity.
    2. Optional accelerators are specified at the and of the name string, using @ followed by a series of modifiers and the final accelerator character (for example, &amp;Save@Ctrl+S). Modifier can be chained using the '+' sign as the delimiter (as in @Ctrl+Shift+S).

    Examples:

    The following is an example of an action set (note the subelements and the way attributes are used): 

        <extension point = "org.jlense.uiworks.actionSets">
        <actionSet id="com.xyz.actionSet"
        label="My Actions"
        visible="true">
            <menu id="com.xyz.xyzMenu" label="XYZ Menu" path="additions">
                <separator name="group1"/>
            </menu>

            <action id="com.xyz.runXYZ"
            label="&amp;Run XYZ Tool"
            menubarPath="com.xyz.xyzMenu/group1"
            toolbarPath="Normal/XYZ"
            icon="icons/runXYZ.gif"
            tooltip="Run XYZ Tool"
            helpContextId="com.xyz.run_action_context"
            class="com.xyz.actions.RunXYZ"
            enablesFor="1">
                <selection class="org.eclipse.core.resources.IFile" name="*.java"/>
            </action>
        </actionSet>
    </extension>

    In the example above, the specified action, named "My Actions", is initially visible within each perspective. It will only enable for a single selection (enablesFor attribute). In addition, objects within the selection must implement the specified interface (IFile) and must be a Java file.

    API Information: The value of the class attribute must be the fully qualified name of a class that implements org.jlense.uiworks.workbench.IWorkbenchWindowActionDelegate or org.jlense.uiworks.workbench.IWorkbenchWindowPulldownDelegate. The latter should be implemented in cases where pulldown is true. This class is loaded as late as possible to avoid loading the entire plug-in before it is really needed.

    Supplied Implementation: Plug-ins may use this extension point to add new top level menus (for example, Debug). Plug-ins can also define named groups which allow other plug-ins to contribute their actions into them.

    Top level menus are created by using the following values for the path attribute:

    • additions - represents a group to the left of the Window menu.
    Omitting the path attribute will result in adding the new menu into the additions menu bar group.

    The default groups in a workbench window are defined in the IWorkbenchActionConstants interface. These constants can be used in code for dynamic contribution. The values can also be copied into an XML file for fine grained integration with the existing workbench menus and toolbar.

    Various menu and toolbar items within the workbench window are defined algorithmically. In these cases a separate mechanism must be used to extend the window. For example, adding a new creation wizard (and denoting that it is available as a shortcut) results in a new menu item appearing under the File|New in the Perspective menu.