View Menus, Toolbars and Actions

Identifier: org.eclipse.ui.viewActions

Description: This extension point is used to add actions to the menu and toolbar for views registered by other plug-ins. Each view has a local pulldown menu normally activated by clicking on the top right area. Other plug-ins can contribute submenus and actions to this menu. Plug-ins may also contribute actions to a view toolbar. View owners are first given a chance to populate these areas. Optional additions by other plug-ins are appended.

Configuration Markup:

   <!ELEMENT viewContribution (menu | action)*>
   <!ATTLIST viewContribution
      id         CDATA #REQUIRED
      targetID   CDATA #REQUIRED
   >

id - a unique identifier that can be used to reference this contribution.

targetID - the unique identifier of the view (as specified in the registry) into which the contribution is made.

   <!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 - the text label of the new menu. The label should include mnemonic information.
path - the location of the menu starting from the pulldown, with the last token representing the named group. If omitted, the menu will be added at the end of the pulldown.

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

name - 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 (selection)* (enablement)?>
   <!ATTLIST action
      id                NMTOKEN #REQUIRED
      label             CDATA #REQUIRED
      menubarPath       CDATA #IMPLIED
      toolbarPath       CDATA #IMPLIED
      icon              CDATA #IMPLIED
      disabledIcon      CDATA #OPTIONAL
      hoverIcon         CDATA #OPTIONAL
      tooltip           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 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 pulldown menu. Each token in the path, except the last one, represents 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 pulldown.
toolbarPath - a named group within the local toolbar of the target view. If the group does not exist, it will be created. If omitted, the action will not appear in the local toolbar.
icon - a relative path for an icon that will be used to visually represent the action in its context. If omitted and the action should appear in the local 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.
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 greyed out. The path is relative to the location of the plugin.xml file of the contributing plug-in.
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.
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).
tooltip - used if the action is to appear in the local 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.
class - a fully qualified name of a class that implements org.eclipse.ui.IViewActionDelegate.
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:

multiple, 2+

   <!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 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 enablement criteria for an action extension are 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.

Action and menu labels may contain special characters that encode mnemonics which are specified using the ampersand ('&') character in front of a mnemonic character in the translatable 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.

Examples:

The following is an example of a view actions extension point (note the subelements and the way attributes are used):

   <extension point="org.eclipse.ui.viewActions">
      <viewContribution
         id="com.xyz.xyzViewC1"
         targetID="org.eclipse.ui.views.ResourceNavigator">
         <menu id="com.xyz.xyzMenu"
            label="XYZ Menu"
            path="additions">
            <separator name="group1"/>
         </menu>
         <action id="com.xyz.runXYZ"
              label="&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>
     </viewContribution>
   </extension>

In the example above, the specified action will only enable for a single selection (enablesFor attribute). In addition, each object in this selection must implement the specified interface (IFile) and must be a Java file. Multiple selection elements can be specified, meaning 'one of'.

API Information: The value of the class attribute must be a fully qualified name of a Java class that implements org.eclipse.ui.IViewActionDelegate. This interface is loaded as late as possible to avoid loading the entire plug-in before it is really needed. It extends org.eclipse.ui.IActionDelegate and adds an additional method that allows the delegate to initialize with the view instance it is contributing into.

Supplied Implementation: Each view normally comes with a number of standard items on the pulldown menu and local toolbar. Additions from other plug-ins will be appended to the standard complement. It is helpful to publish the action identifiers for a view within a public interface. For example, the actions and major groups for the workbench window are defined in org.eclipse.ui.IWorkbenchActionConstants.