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.
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*)>
This element is used to define a group of editor actions and/or menus.
<!ATTLIST editorContribution<!ELEMENT action (selection* | enablement?)>
This element defines an action that the user can invoke in the UI.
<!ATTLIST actionpush | - 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. |
! | - 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 |
<!ELEMENT menu (separator+ , groupMarker*)>
This element is used to defined a new menu.
<!ATTLIST menu<!ELEMENT separator EMPTY>
This element is used to create a menu separator in the new menu.
<!ATTLIST separator<!ELEMENT groupMarker EMPTY>
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.
<!ATTLIST groupMarker<!ELEMENT selection EMPTY>
This element is used to help determine the action enablement based on the current selection. Ignored if the enablement element is specified.
<!ATTLIST selection<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>
This element is used to define the enablement for the action.
<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>
This element is used to define the visibility for the action.
<!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>
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.
<!ATTLIST objectClass<!ELEMENT objectState EMPTY>
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.
<!ATTLIST objectState<!ELEMENT pluginState EMPTY>
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.
<!ATTLIST pluginState<!ELEMENT systemProperty EMPTY>
This element is used to evaluate the state of some system property. The property value is retrieved from the java.lang.System.
<!ATTLIST systemProperty
<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" 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="&XYZ2 Menu" path="edit/additions"> <separator name="group1"/> </menu> <action id="com.xyz.runXYZ2" label="&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.
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 class 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:
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.
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.
Action and menu labels may contain special characters that encode mnemonics using the following rules:
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: 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, 2003 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Common Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/cpl-v10.html