Action Sets

Identifier:

org.eclipse.ui.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 and appear within the Workbench window by the user customizing a perspective.

You can now use org.eclipse.ui.menus to place commands in menus and toolbars as well.

There is an implementation limitation which currently affects action sets. It is important to define the entire menu structure that is to be referenced within the action set. So, for example, if another action set defines a menu called "example", it is not possible to rely on "example" existing. It is necessary to redefine the "example" menu in every action set that wishes to use it.

An action's enablement and/or visibility can be defined using the elements enablement and visibility respectively, if the extension point supports it. These two elements contain a boolean expression that is evaluated to determine the enablement and/or visibility.

The syntax is the same for the enablement and visibility elements. Both contain only one boolean expression sub-element. In the simplest case, this will be an objectClass, objectState, pluginState, or systemProperty element. In the more complex case, the and, or, and not elements can be combined to form a boolean expression. Both the and, and or elements must contain 2 sub-elements. The not element must contain only 1 sub-element.

Configuration Markup:

<!ELEMENT extension (actionSet+)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

point - a fully qualified identifier of the target extension point
id - an optional identifier of the extension instance
name - an optional name of the extension instance

<!ELEMENT actionSet (menu* , action*)>

<!ATTLIST actionSet

id CDATA #REQUIRED

label CDATA #REQUIRED

visible (true | false)

description CDATA #IMPLIED>

This element is used to define a group of actions and/or menus.

id - a unique identifier for this action set.
label - a translatable name used by the Workbench to represent this action set to the user.
visible - an optional attribute indicating whether the action set is initially visible when a perspective is open. This option is only honoured when the user opens a perspective which has not been customized. The user can override this option from the "Customize Perspective Dialog". This attribute should be used with great care so as not to overwhelm the user with too many actions.
description - a translatable description used by the Workbench to represent this action set to the user.

<!ELEMENT action ((selection* | enablement?) , class?)>

<!ATTLIST action

id CDATA #REQUIRED

label CDATA #REQUIRED

definitionId IDREF #IMPLIED

menubarPath CDATA #IMPLIED

toolbarPath CDATA #IMPLIED

icon CDATA #IMPLIED

tooltip CDATA #IMPLIED

style (push|radio|toggle|pulldown) "push"

state (true | false)

pulldown (true | false)

class CDATA #IMPLIED

retarget (true | false)

allowLabelUpdate (true | false)

enablesFor CDATA #IMPLIED

mode (FORCE_TEXT) >

This element defines an action that the user can invoke in the UI.

id - a unique identifier used as a reference for this action.
label - a translatable name used either as the menu item text or toolbar button label. The name can include mnenomic information.
definitionId - Specifies the command that this action will handle. By specifying and action, the key binding service can assign a key sequence to this action. See the extension point org.eclipse.ui.commands for more information.
menubarPath - a slash-delimited path ('/') used to specify the location of this action in the menu bar. Each token in the path, except the last one, must represent a valid identifier of an existing menu in the hierarchy. The last token represents the named group into which this action will be added. If the path is omitted, this action will not appear in the menu bar.
toolbarPath - a slash-delimited path ('/') that is used to specify the location of this action in the toolbar. The first token represents the toolbar identifier (with "Normal" being the default toolbar), while the second token is the named group within the toolbar that this action will be added to. If the group does not exist in the toolbar, it will be created. If toolbarPath is omitted, the action will not appear in the toolbar.
icon - a relative path of an icon used to visually represent the action in its context. If omitted and the action appears in the toolbar, the Workbench will use a placeholder icon. The path is relative to the location of the plugin.xml file of the contributing plug-in, or the ISharedImages constant. The icon will appear in toolbars but not in menus. Enabled actions will be represented in menus by the hoverIcon.
tooltip - a translatable text representing the action's tool tip. Only used if the action appears in the toolbar.

style - an attribute to define the user interface style type for the action. If omitted, then it is push by default. The attribute value will be one of the following:

	push	- as a regular menu item or tool item.
	radio	- as a radio style menu item or tool item. Actions with the radio style within the same menu or toolbar group behave as a radio set. The initial value is specified by the `state` attribute.
	toggle	- as a checked style menu item or as a toggle tool item. The initial value is specified by the `state` attribute.
	pulldown	- as a cascading style menu item or as a drop down menu beside the tool item.

state - an optional attribute indicating the initial state (either true or false). Used only when the style attribute has the value radio or toggle.
Deprecated pulldown - Use the style attribute with the value pulldown.
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 the style attribute has the value pulldown. This class is the handler responsible for performing the action. If the retarget attribute is true, this attribute is ignored and should not be supplied.
retarget - an optional attribute to retarget this action. When true, view and editor parts may supply a handler for this action using the standard mechanism for setting a global action handler on their site using this action's identifier. If this attribute is true, the class attribute should not be supplied.
Note:The combination of pulldown and retarget is not supported. Commands can be used to provide this type of functionality, see org.eclipse.ui.menus and the command element with a style of pulldown.
allowLabelUpdate - optional attribute indicating whether the retarget action allows the handler to override it's label and tooltip. Only applies if retarget attribute is true.

enablesFor - a value indicating the selection count which must be met to enable the action. If specified and the condition is not met, the action is disabled. If omitted, the action enablement state is not affected. 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.a precise number of items selected. For example: enablesFor=" 4" enables the action only when 4 items are selected
	*	- any number of items selected

mode - For actions appearing in a toolbar, FORCE_TEXT will show text even if there is an icon. See ActionContribuitonItem.

<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name CDATA #REQUIRED

value CDATA #REQUIRED>

A parameter element to be used within an IExecutableExtension element. This will be passed as initialization data to the instantiated class.

name - the parameter name
value - the parameter value

<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #IMPLIED>

The element version of the class attribute. This is used when the class implements org.eclipse.core.runtime.IExecutableExtension and there is parameterized data that you wish used in its initialization.

class - A class that implements org.eclipse.ui.IWorkbenchWindowActionDelegate. It may also implement org.eclipse.core.runtime.IExecutableExtension.

<!ELEMENT menu (separator* , groupMarker*)>

<!ATTLIST menu

id CDATA #REQUIRED

label CDATA #REQUIRED

path CDATA #IMPLIED

icon CDATA #IMPLIED>

This element is used to defined a new menu.

id - a unique identifier that can be used to reference this menu.
label - a translatable name used by the Workbench for this new menu. The name should include mnemonic information.
path - the location of the new menu starting from the root of the menu. Each token in the path must refer to an existing menu, except the last token which should represent a named group in the last menu in the path. If omitted, the new menu will be added to the additions named group of the menu.
icon - a relative path of an icon used to visually represent the menu in its context. The path is relative to the location of the plugin.xml file of the contributing plug-in.

<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

This element is used to create a menu separator in the new menu.

name - the name of the menu separator. This name can later be referenced as the last token in a menu path. Therefore, a separator also serves as named group into which actions and menus can be added.

<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

This element is used to create a named group in the new menu. It has no visual representation in the new menu, unlike the separator element.

name - the name of the group marker. This name can later be referenced as the last token in the menu path. It serves as named group into which actions and menus can be added.

<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name CDATA #IMPLIED>

This element is used to help determine the action enablement based on the current selection. Ignored if the enablement element is specified.

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

This element is used to define the enablement for the extension.

This element is used to define the visibility for the extension.

This element represent a boolean AND operation on the result of evaluating its two sub-element expressions.

This element represent a boolean OR operation on the result of evaluating its two sub-element expressions.

This element represent a boolean NOT operation on the result of evaluating its sub-element expressions.

<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

This element is used to evaluate the class or interface of each object in the current selection. If each object in the selection implements the specified class or interface, the expression is evaluated as true.

name - a fully qualified name of a class or interface. The expression is evaluated as true only if all objects within the selection implement this class or interface.

<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name CDATA #REQUIRED

value CDATA #REQUIRED>

This element is used to evaluate the attribute state of each object in the current selection. If each object in the selection has the specified attribute state, the expression is evaluated as true. To evaluate this type of expression, each object in the selection must implement, or adapt to, org.eclipse.ui.IActionFilter interface.

name - the name of an object's attribute. Acceptable names reflect the object type, and should be publicly declared by the plug-in where the object type is declared. @see IResourceActionFilter for a list of the supported constants
value - the required value of the object's attribute. The acceptable values for the object's attribute should be publicly declared.

<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id CDATA #REQUIRED

value (installed|activated) "installed">

This element is used to evaluate the state of a plug-in. The state of the plug-in may be one of the following: installed (equivalent to the OSGi concept of "resolved") or activated (equivalent to the OSGi concept of "active").

id - the identifier of a plug-in which may or may not exist in the plug-in registry.
value - the required state of the plug-in. The state of the plug-in may be one of the following: installed (equivalent to the OSGi concept of "resolved") or activated (equivalent to the OSGi concept of "active").

<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name CDATA #REQUIRED

value CDATA #REQUIRED>

This element is used to evaluate the state of some system property. The property value is retrieved from the java.lang.System.

name - the name of the system property.
value - the required value of the system property.

Examples:

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


    <extension point = "org.eclipse.ui.actionSets"> 
        <actionSet
            id="com.xyz.actionSet" 
            label="My Actions"> 
            <menu
               id="com.xyz.xyzMenu" 
               label="XYZ Menu"
               path="additions"> 
               <separator name="group1"/>
               <separator name="option1"/>
            </menu>
            
            <action
               id="com.xyz.runXYZ" 
               label="&amp;Run XYZ Tool"
               style="toggle"
               state="false"
               menubarPath="com.xyz.xyzMenu/group1" 
               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"
               style="push"
               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">
               <enablement>
                  <and>
                     <objectClass name="org.eclipse.core.resources.IFile"/>
                     <not>
                        <objectState name="extension" value="java"/>
                     </not>
                  </and>
               </enablement>
            </action>             

            <action 
               id="com.xyz.runDEF"
               label="&amp;Run DEF Tool"
               style="radio"
               state="true"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runDEF.gif"
               tooltip="Run DEF Tool"
               class="com.xyz.actions.RunDEF" 
               helpContextId="com.xyz.run_def_action_context">
            </action>             
            <action 
               id="com.xyz.runGHI"
               label="&amp;Run GHI Tool"
               style="radio"
               state="false"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runGHI.gif"
               tooltip="Run GHI Tool"
               class="com.xyz.actions.RunGHI" 
               helpContextId="com.xyz.run_ghi_action_context">
            </action>             
            <action 
               id="com.xyz.runJKL"
               label="&amp;Run JKL Tool"
               style="radio"
               state="false"
               menubarPath="com.xyz.xyzMenu/option1"
               icon="icons/runJKL.gif"
               tooltip="Run JKL Tool"
               class="com.xyz.actions.RunJKL" 
               helpContextId="com.xyz.run_jkl_action_context">
            </action>             
        </actionSet> 
    </extension>

In the example above, the specified action set, named "My Actions", is not initially visible within each perspective because the visible attribute is not specified.

The XYZ action will appear as a check box menu item, initially not checked. It is enabled only if the selection count is 1 and if the selection contains a Java file resource.

The ABC action will appear both in the menu and on the toolbar. It is enabled only if the selection does not contain any Java file resources. Note also this is a label retarget action therefore it does not supply a class attribute.

The actions DEF, GHI, and JKL appear as radio button menu items. They are enabled all the time, independent of the current selection state.

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 the style attribute has the value pulldown. This class is the handler responsible for performing the action. If the retarget attribute is true, this attribute is ignored and should not be supplied. 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, and also either selection or 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 a plug-in's behalf. Menu paths must reference menus that already exist.

Action and menu labels may contain special characters that encode mnemonics using the following rules:

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.

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.

The selection and enablement elements are mutually exclusive. The enablement element can replace the selection element using the sub-elements objectClass and objectState. For example, the following:


 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>

can be expressed using:


 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Supplied Implementation:

Plug-ins may use this extension point to add new top level menus. 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 immediately 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 workbench view results in a new menu item appearing in the Perspective menu. Import, Export, and New Wizards extensions are also added automatically to the window.

Copyright (c) 2000, 2007 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html