Editor Menus, Toolbars and Actions

Identifier: org.eclipse.ui.editorActions

Description: This extension point is used to add actions to the menu and toolbar for editors registered by other plug-ins.

The initial contribution set for an editor is defined by another extension point (org.eclipse.ui.editors). One set of actions is created and shared by all instances of the same editor type. When invoked, these action act upon the active editor. This extension point follows the same pattern. Each action extension is created and shared by all instances of the same editor type. The action class is required to implement org.eclipse.ui.IEditorActionDelegate. The active editor is passed to the delegate by invoking IEditorActionDelegate#setActiveEditor.

Configuration Markup:

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

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

editorID - a unique identifier of a previously registered editor that is the target of this contribution

   <!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 root of the menu bar. If omitted, the menu will be added into the slot additions on the menu bar. Each token in the path must refer to an existing menu in the workbench, except the last one, which represents 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 can be added.

   <!ELEMENT action (selection)* (enablement)?>
   <!ATTLIST action
      id                NMTOKEN #REQUIRED
      label             CDATA #REQUIRED
      accelerator       CDATA #IMPLIED
      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).
accelerator - the accelerator for the action. This is specified as a combination of the keys CTRL, SHIFT and ALT and an accelrator key. These values are not internationalized and should not be translated. Specification of the accelerator for the entry title should be done in the label - this value will not be used to build a menu entry.
menubarPath - a slash-delimited absolute path ('/') that is used to specify the location of the action in the menu bar. The path may only point to menus that belong to the target editor. 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 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.
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.
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.
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 - used if the action is to appear in the tool bar. 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 tool bar, it will become a toggle button. If defined, attribute value will be used as initial state (either true or false).
class - the name of the fully qualified class that implements org.eclipse.ui.IEditorActionDelegate.
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 and accelerators 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.
Optional accelerators are specified at the and of the name string, using @ followed by the series of modifiers and the final accelerator character (for example, &Save@Ctrl+S). Modifiers can be chained using the '+' sign as the delimiter (as in @Ctrl+Shift+S).

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 an editor action extension point:

   <extension point="org.eclipse.ui.editorActions">
      <editorContribution
         id="com.xyz.xyzContribution"
         targetID="com.ibm.XMLEditor">
         <menu id="XYZ" label="&XYZ Menu">
            <separator name="group1"/>
         </menu>
         <action
              id="com.xyz.runXYZ"
              label="&Run XYZ Tool"
              menubarPath="XYZ/group1"
              toolbarPath="Normal/additions"
              state="true"
              icon="icons/runXYZ.gif"
              tooltip="Run XYZ Tool"
              helpContextId="com.xyz.run_action_context"
              class="com.xyz.actions.RunXYZ">
         </action>
      </editorContribution>
   </extension>

In the example above, the specified action will appear as a check box item in the new top-level menu named "XYZ Menu", and as a toggle button in the toolbar.

The following is an example of an editor action extension point:

   <extension point="org.eclipse.ui.editorActions">
      <editorContribution
         id="com.xyz.xyz2Contribution"
         targetID="com.ibm.XMLEditor">
         <menu
            id="XYZ2"
            label="&XYZ2 Menu"
            path="edit/additions">
            <separator name="group1"/>
         </menu>
         <action
              id="com.xyz.runXYZ2"
              label="&Run XYZ2 Tool"
              menubarPath="edit/XYZ2/group1"
              state="true"
              icon="icons/runXYZ2.gif"
              tooltip="Run XYZ2 Tool"
              helpContextId="com.xyz.run_action_context2"
              class="com.xyz.actions.RunXYZ2">
         </action>
      </editorContribution>
   </extension>

In the example above, the specified action will appear as a check box item in the sub-menu named "XYZ2 Menu" in the top level "Edit" menu.

API Information: The value of the class attribute must be a fully qualified name of a Java class that implements org.eclipse.ui.IEditorActionDelegate. This interface is loaded as late as possible to avoid loading the entire plug-in before it is really needed. The method setActiveEditor will be called each time an editor of the specified type is activated. Only one set of actions and menus will be created for all instances of the specified editor type, regardless of the number of editor instances currently opened in the workbench.

This extension point can be used to contribute actions into menus previously created by the target editor. In addition, menus and actions can be contributed to the workbench window. The identifiers for actions and major groups within the workbench window are defined in org.eclipse.ui.IWorkbenchActionConstants. These should be used as a reference point for the addition of new actions. 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.

Actions and menus added into these paths will only be shown while the associated editor is active. When the editor is closed, menus and actions will be removed.

Supplied Implementation: The workbench provides a built-in "Default Text Editor". Plug-ins can contribute into this default editor or editors provided by other plug-ins.