<!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.5 [en] (WinNT; I) [Netscape]"> | |
<title>Eclipse Workbench Extension Point: View Actions</title> | |
</head> | |
<body link="#0000FF" vlink="#800080"> | |
<center> | |
<h1> | |
View Menus, Toolbars and Actions</h1></center> | |
<b><i>Identifier: </i></b>org.eclipse.ui.viewActions | |
<p><b><i>Description: </i></b>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. | |
<p><b><i>Configuration Markup:</i></b> | |
<p><tt> <!ELEMENT viewContribution (menu | action)*></tt> | |
<br><tt> <!ATTLIST viewContribution</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>targetID</b> - the unique identifier of the view (as specified in the | |
registry) into which the contribution is made.</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 pulldown, with | |
the last token representing the named group. If omitted, the menu will | |
be added at the end of the pulldown.</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> - 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> 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>menubarPath</b> - 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.</li> | |
<li> | |
<b>toolbarPath</b> - 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.</li> | |
<li> | |
<b>icon</b> - 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.</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 greyed 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>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 toolbar, it will become a toggle button. | |
If defined, the attribute value will be used as the initial state (either | |
<tt>true</tt> | |
or <tt>false</tt>).</li> | |
<li> | |
<b>tooltip</b> - used if the action is to appear in the local toolbar. | |
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>class</b> - a fully qualified name of a class that implements <tt>org.eclipse.ui.IViewActionDelegate</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 | |
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 <tt>&amp;</tt> character entity.</li> | |
<p>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 a view actions extension point (note | |
the subelements and the way attributes are used): | |
<p><tt> <extension point="org.eclipse.ui.viewActions"></tt> | |
<br><tt> <viewContribution</tt> | |
<br><tt> id="com.xyz.xyzViewC1"</tt> | |
<br><tt> targetID="org.eclipse.ui.views.ResourceNavigator"></tt> | |
<br><tt> <menu id="com.xyz.xyzMenu"</tt> | |
<br><tt> | |
label="XYZ Menu"</tt> | |
<br><tt> | |
path="additions"></tt> | |
<br><tt> | |
<separator name="group1"/></tt> | |
<br><tt> </menu></tt> | |
<br><tt> <action id="com.xyz.runXYZ"</tt> | |
<br><tt> | |
label="&amp;Run XYZ Tool"</tt> | |
<br><tt> | |
menubarPath="com.xyz.xyzMenu/group1"</tt> | |
<br><tt> | |
toolbarPath="Normal/XYZ"</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> | |
enablesFor="1"/></tt> | |
<br><tt> | |
<selection class="org.eclipse.core.resources.IFile" name="*.java"></tt> | |
<br><tt> </action></tt> | |
<br><tt> </viewContribution></tt> | |
<br><tt> </extension></tt> | |
<p>In the example above, the specified action will only enable for a single | |
selection (<tt>enablesFor</tt> attribute). In addition, each object in | |
this selection must implement the specified interface (<tt>IFile</tt>) | |
and must be a Java file. Multiple <tt>selection</tt> elements can be specified, | |
meaning 'one of'. | |
<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.IViewActionDelegate</tt>. | |
This interface is loaded as late as possible to avoid loading the entire | |
plug-in before it is really needed. It extends <tt>org.eclipse.ui.IActionDelegate</tt> | |
and adds an additional method that allows the delegate to initialize with | |
the view instance it is contributing into. | |
<p><b><i>Supplied Implementation:</i></b> 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. | |
<p><a href="hglegal2002.htm"><img SRC="ngibmcpy2002.gif" ALT="Copyright IBM Corporation and others 2000, 2002." BORDER=0></a> | |
</body> | |
</html> |