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.

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

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.

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.

Configuration Markup:

<!ELEMENT extension (editorContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID IDREF #REQUIRED>

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



<!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) "push"

state        (true | false)

class        CDATA #REQUIRED

enablesFor   CDATA #IMPLIED

actionID     CDATA #IMPLIED

mode         (FORCE_TEXT) >

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



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



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



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



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



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


   <extension point="org.eclipse.ui.editorActions"> 
      <editorContribution 
         id="com.xyz.xyzContribution" 
         targetID="com.ibm.XMLEditor"> 
         <menu
            id="XYZ"
            label="&amp;XYZ Menu"> 
            <separator name="group1"/> 
         </menu> 
         <action 
            id="com.xyz.runXYZ" 
            label="&amp;Run XYZ Tool" 
            menubarPath="XYZ/group1" 
            toolbarPath="Normal/additions"
            style="toggle"
            state="true" 
            icon="icons/runXYZ.gif" 
            tooltip="Run XYZ Tool" 
            helpContextId="com.xyz.run_action_context" 
            class="com.xyz.actions.RunXYZ"> 
            <selection class="org.eclipse.core.resources.IFile" name="*.java"/> 
         </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 action is enabled if the selection contains only Java file resources.

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


   <extension point="org.eclipse.ui.editorActions"> 
      <editorContribution 
         id="com.xyz.xyz2Contribution" 
         targetID="com.ibm.XMLEditor"> 
         <menu 
            id="XYZ2" 
            label="&amp;XYZ2 Menu" 
            path="edit/additions"> 
            <separator name="group1"/> 
         </menu> 
         <action 
            id="com.xyz.runXYZ2" 
            label="&amp;Run XYZ2 Tool" 
            menubarPath="edit/XYZ2/group1"
            style="push"
            icon="icons/runXYZ2.gif" 
            tooltip="Run XYZ2 Tool" 
            helpContextId="com.xyz.run_action_context2" 
            class="com.xyz.actions.RunXYZ2"> 
            <enablement>
               <and>
                  <objectClass name="org.eclipse.core.resources.IFile"/>
                  <not>
                     <objectState name="extension" value="java"/>
                  </not>
               </and>
            </enablement>
         </action> 
      </editorContribution> 
   </extension> 

In the example above, the specified action will appear as a menu item in the sub-menu named "XYZ2 Menu" in the top level "Edit" menu. The action is enabled if the selection contains no Java file resources.

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.


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