Action Sets

org.eclipse.ui.actionSets

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.

An action's enablement and/or visibility can be defined using the elements enablement and visibility respectively. 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.

<!ELEMENT extension (actionSet+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!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.



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

accelerator      CDATA #IMPLIED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

toolbarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

disabledIcon     CDATA #IMPLIED

hoverIcon        CDATA #IMPLIED

tooltip          CDATA #IMPLIED

helpContextId    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>

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



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

This element is used to defined a new menu.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

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



<!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.



<!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.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

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



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

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



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

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



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

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



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean NOT operation on the result of evaluating it's 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.



<!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.



<!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 or activated.



<!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.



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.

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:

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

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:

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.