| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> | |
| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
| <meta name="GENERATOR" content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]"> | |
| <title>Eclipse Workbench Extension Point: Editor Actions</title> | |
| </head> | |
| <body link="#0000FF" vlink="#800080"> | |
| <center> | |
| <h1> | |
| Editor Menus, Toolbars and Actions</h1></center> | |
| <b><i>Identifier: </i></b>org.eclipse.ui.editorActions | |
| <p><b><i>Description: </i></b>This extension point is used to add actions | |
| to the menu and toolbar for editors registered by other plug-ins. | |
| <p>The initial contribution set for an editor is defined by another extension | |
| point (<a href="org_eclipse_ui_editors.html">org.eclipse.ui.editors</a>). | |
| 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 <tt>org.eclipse.ui.IEditorActionDelegate</tt>. | |
| The active editor is passed to the delegate by invoking <tt>IEditorActionDelegate#setActiveEditor</tt>. | |
| <p><b><i>Configuration Markup:</i></b> | |
| <p><tt> <!ELEMENT editorContribution (menu | action)*></tt> | |
| <br><tt> <!ATTLIST editorContribution</tt> | |
| <br><tt> id | |
| CDATA #REQUIRED</tt> | |
| <br><tt> targetID CDATA #REQUIRED</tt> | |
| <br><tt> ></tt> | |
| <blockquote> | |
| <li> | |
| <b>id</b> - a unique identifier that can be used to reference this contribution</li> | |
| <li> | |
| <b>editorID</b> - a unique identifier of a previously registered editor | |
| that is the target of this contribution</li> | |
| </blockquote> | |
| <tt> <!ELEMENT menu (separator)+></tt> | |
| <br><tt> <!ATTLIST menu</tt> | |
| <br><tt> id | |
| CDATA #REQUIRED</tt> | |
| <br><tt> label | |
| CDATA #REQUIRED</tt> | |
| <br><tt> path | |
| CDATA #IMPLIED</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>id</b> - a unique identifier that can be used to reference this menu</li> | |
| <li> | |
| <b>label</b> - the text label of the new menu. The label should include | |
| mnemonic information.</li> | |
| <li> | |
| <b>path</b> - the location of the menu starting from the root of the menu | |
| bar. If omitted, the menu will be added into the slot <tt>additions</tt> | |
| 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.</li> | |
| </ul> | |
| <tt> <!ELEMENT separator EMPTY></tt> | |
| <br><tt> <!ATTLIST separator</tt> | |
| <br><tt> name | |
| CDATA #REQUIRED</tt> | |
| <br><tt> ></tt> | |
| <blockquote> | |
| <li> | |
| <b>name</b> - 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.</li> | |
| </blockquote> | |
| <tt> <!ELEMENT action (selection)* (enablement)?></tt> | |
| <br><tt> <!ATTLIST action</tt> | |
| <br><tt> id | |
| NMTOKEN #REQUIRED</tt> | |
| <br><tt> label | |
| CDATA #REQUIRED</tt> | |
| <br><tt> accelerator | |
| CDATA #IMPLIED</tt> | |
| <br><tt> menubarPath | |
| CDATA #IMPLIED</tt> | |
| <br><tt> toolbarPath | |
| CDATA #IMPLIED</tt> | |
| <br><tt> icon | |
| CDATA #IMPLIED</tt> | |
| <br><tt> disabledIcon | |
| CDATA #OPTIONAL</tt> | |
| <br><tt> hoverIcon | |
| CDATA #OPTIONAL</tt> | |
| <br><tt> tooltip | |
| CDATA #IMPLIED</tt> | |
| <br><tt> helpContextId | |
| CDATA #IMPLIED</tt> | |
| <br><tt> state | |
| (true | false) #IMPLIED</tt> | |
| <br><tt> class | |
| CDATA #REQUIRED</tt> | |
| <br><tt> enablesFor | |
| CDATA #IMPLIED</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>id</b> - a unique identifier that can be used as a reference for this | |
| action.</li> | |
| <li> | |
| <b>label</b> - 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).</li> | |
| <li> | |
| <b>accelerator</b> - 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.</li> | |
| <li> | |
| <b>menubarPath</b> - 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.</li> | |
| <li> | |
| <b>toolbarPath</b> - 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.</li> | |
| <li> | |
| <b>icon</b> - 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.</li> | |
| <li> | |
| <b>disabledIcon</b> - 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.</li> | |
| <li> | |
| <b>hoverIcon</b> - 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.</li> | |
| <li> | |
| <b>tooltip</b> - used if the action is to appear in the tool bar. Otherwise, | |
| it is ignored.</li> | |
| <li> | |
| <b>helpContextId -</b> 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.</li> | |
| <li> | |
| <b>state</b> - 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 <tt>true</tt> | |
| or <tt>false</tt>).</li> | |
| <li> | |
| <b>class</b> - the name of the fully qualified class that implements <tt>org.eclipse.ui.IEditorActionDelegate</tt>.</li> | |
| <li> | |
| <b>enablesFor</b> - 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:</li> | |
| <ul> | |
| <br><b>!</b> - 0 items selected | |
| <br><b>?</b> - 0 or 1 items selected | |
| <br><b>+</b> - 1 or more items selected | |
| <br><b>multiple, 2+</b> - 2 or more items selected | |
| <br><b>n</b> - a precise number of items selected. Example: 4. | |
| <br><b>*</b> - any number of items selected</ul> | |
| </ul> | |
| <tt> <!ELEMENT selection EMPTY></tt> | |
| <br><tt> <!ATTLIST selection</tt> | |
| <br><tt> class | |
| CDATA #REQUIRED</tt> | |
| <br><tt> name | |
| CDATA #IMPLIED</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>class</b> - 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.</li> | |
| <li> | |
| <b>name</b> - 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.</li> | |
| </ul> | |
| <tt> <!ELEMENT enablement (and | or | not | objectClass | |
| | objectState | systemProperty</tt> | |
| <br><tt> | pluginState)></tt> | |
| <br><tt> <!ATTLIST enablement EMPTY></tt> | |
| <blockquote>In version 2.0 of Eclipse, an <tt>enablement</tt> element may | |
| be used to define the enablement for the action. For more information | |
| on the use of <tt>enablement</tt> element, refer to <a href="actionExpressions.html">actionExpressions.html</a>.</blockquote> | |
| The enablement criteria for an action extension are initially defined by | |
| <tt>enablesFor, | |
| selection</tt> and <tt>enablement</tt>. However, once the action | |
| delegate has been instantiated, it may control the action enable state | |
| directly within its | |
| <tt>selectionChanged</tt> method. | |
| <p>Action and menu labels may contain special characters that encode mnemonics | |
| and accelerators using the following rules: | |
| <ol> | |
| <li> | |
| 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 <tt>&amp;</tt> character entity.</li> | |
| <li> | |
| Optional accelerators are specified at the and of the name string, using | |
| <tt>@</tt> | |
| followed by the series of modifiers and the final accelerator character | |
| (for example, <tt>&amp;Save@Ctrl+S</tt>). Modifiers can be chained | |
| using the '+' sign as the delimiter (as in <tt>@Ctrl+Shift+S</tt>).</li> | |
| </ol> | |
| 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. | |
| <p><b><i>Examples:</i></b> | |
| <p>The following is an example of an editor action extension point: | |
| <p><tt> <extension point="org.eclipse.ui.editorActions"></tt> | |
| <br><tt> <editorContribution</tt> | |
| <br><tt> id="com.xyz.xyzContribution"</tt> | |
| <br><tt> targetID="com.ibm.XMLEditor"></tt> | |
| <br><tt> <menu id="XYZ" | |
| label="&amp;XYZ Menu"></tt> | |
| <br><tt> | |
| <separator name="group1"/></tt> | |
| <br><tt> </menu></tt> | |
| <br><tt> <action</tt> | |
| <br><tt> | |
| id="com.xyz.runXYZ"</tt> | |
| <br><tt> | |
| label="&amp;Run XYZ Tool"</tt> | |
| <br><tt> | |
| menubarPath="XYZ/group1"</tt> | |
| <br><tt> | |
| toolbarPath="Normal/additions"</tt> | |
| <br><tt> | |
| state="true"</tt> | |
| <br><tt> | |
| icon="icons/runXYZ.gif"</tt> | |
| <br><tt> | |
| tooltip="Run XYZ Tool"</tt> | |
| <br><tt> | |
| helpContextId="com.xyz.run_action_context"</tt> | |
| <br><tt> | |
| class="com.xyz.actions.RunXYZ"></tt> | |
| <br><tt> </action></tt> | |
| <br><tt> </editorContribution></tt> | |
| <br><tt> </extension></tt> | |
| <p>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. | |
| <p>The following is an example of an editor action extension point: | |
| <p><tt> <extension point="org.eclipse.ui.editorActions"></tt> | |
| <br><tt> <editorContribution</tt> | |
| <br><tt> id="com.xyz.xyz2Contribution"</tt> | |
| <br><tt> targetID="com.ibm.XMLEditor"></tt> | |
| <br><tt> <menu</tt> | |
| <br><tt> | |
| id="XYZ2"</tt> | |
| <br><tt> | |
| label="&amp;XYZ2 Menu"</tt> | |
| <br><tt> | |
| path="edit/additions"></tt> | |
| <br><tt> | |
| <separator name="group1"/></tt> | |
| <br><tt> </menu></tt> | |
| <br><tt> <action</tt> | |
| <br><tt> | |
| id="com.xyz.runXYZ2"</tt> | |
| <br><tt> | |
| label="&amp;Run XYZ2 Tool"</tt> | |
| <br><tt> | |
| menubarPath="edit/XYZ2/group1"</tt> | |
| <br><tt> | |
| state="true"</tt> | |
| <br><tt> | |
| icon="icons/runXYZ2.gif"</tt> | |
| <br><tt> | |
| tooltip="Run XYZ2 Tool"</tt> | |
| <br><tt> | |
| helpContextId="com.xyz.run_action_context2"</tt> | |
| <br><tt> | |
| class="com.xyz.actions.RunXYZ2"></tt> | |
| <br><tt> </action></tt> | |
| <br><tt> </editorContribution></tt> | |
| <br><tt> </extension></tt> | |
| <p>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. | |
| <p><b><i>API Information: </i></b>The value of the <tt>class</tt> attribute | |
| must be a fully qualified name of a Java class that implements <tt>org.eclipse.ui.IEditorActionDelegate</tt>. | |
| This interface is loaded as late as possible to avoid loading the entire | |
| plug-in before it is really needed. The method <tt>setActiveEditor</tt> | |
| 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. | |
| <p>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 <tt>org.eclipse.ui.IWorkbenchActionConstants</tt>. | |
| 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 <tt>path</tt> | |
| attribute: | |
| <ul> | |
| <li> | |
| <tt>additions</tt> - represents a group to the left of the Window menu.</li> | |
| </ul> | |
| 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. | |
| <p><b><i>Supplied Implementation:</i></b> The workbench provides a built-in | |
| "Default Text Editor". Plug-ins can contribute into this default editor | |
| or editors provided by other plug-ins. | |
| <p><a href="hglegal2002.htm"><img SRC="ngibmcpy2002.gif" ALT="Copyright IBM Corporation and others 2000, 2002." BORDER=0></a> | |
| </body> | |
| </html> |