Action Sets

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 and appear within the workbench window by user preference.

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 all perspectives.  This option will only be honoured when the user opens a new perspective which has not been customized.  The user may also override this option from the "Customize Perspective Dialog".
• description - an optional subelement whose body should contain text providing short description of the action set.

• 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 before the Window menu 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.

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.

name - a name of the group marker that can later be referenced as the last token in the action path.

• 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).
• accelerator - an integer that is used to specify the keycode of the accelerator for the action. This is the integer value resulting from a bitwise OR of zero or more SWT key modifier masks (i.e. SWT.CTRL or SWT.ALT) and a character code. For example, for Ctrl+Z use SWT.CTRL | 'Z' = (1<<18)|'Z' = 262234.
• definitionId - the id specified in the action definition. Only needed when an action set specifies accelerators through the key binding service. See the extension points Action Definitions and Accelerator Sets
• 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. The icon will appear in toolbars but not in menus. Enabled actions will be represented in menus by the hoverIcon.
• disabledIcon - a relative path of an icon that will be used to visually represent the action in its context when the action is disabled. If it is omitted the normal icon will simply appear grayed out. The path is relative to the location of the plugin.xml file of the contributing plug-in. The disabled icon will appear in toolbars but not in menus. Icons for disabled actions in menus will be supplied by the OS.
• hoverIcon - a relative path of an icon that will be used to visually represent the action in its context when the mouse is over the action. If it is omitted the normal icon will be used. 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.eclipse.ui.IWorkbenchWindowActionDelegate or org.eclipse.ui.IWorkbenchWindowPulldownDelegate.  The latter should be implemented in cases where pulldown is true. If the retarget attribute is true this attribute should not be supplied.
• retarget - if this attribute is true then a retarget (global) action will be created. Parts may supply a handler for this global action using the standard mechanism for setting a global action handler on their site using this action's id. If this attribute is true, the class attribute should not be supplied.
• allowLabelUpdates - only applies if retarget is true. If this attribute is true then the retarget action will update its label and tooltip from its handler.
• 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

• 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 following is an example of an action set (note the subelements and the way attributes are used):

    <extension point = "org.eclipse.ui.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>
            <action id="com.xyz.runABC"
                label="&amp;Run ABC Tool"
                menubarPath="com.xyz.xyzMenu/group1"
                toolbarPath="Normal/XYZ"
                icon="icons/runABC.gif"
                tooltip="Run ABC Tool"
                helpContextId="com.xyz.run_abc_action_context"
                retarget="true"
                allowLabelUpdate="true">
            </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.eclipse.ui.IWorkbenchWindowActionDelegate or org.eclipse.ui.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.

The enablement criteria for an action extension is 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.

It is important to note that the workbench does not generate menus on plug-ins' behalf: menu paths must reference menus that already exist.

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 end 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).

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.

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 workbench view results in a new menu item appearing in the Window menu. Import, Export, and New Wizards extensions are also added automatically to the window.