<!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]"> | |
<meta name="Author" content="Build"> | |
<title>Eclipse Workbench Extension Point: Action Sets</title> | |
</head> | |
<body link="#0000FF" vlink="#800080"> | |
<center> | |
<h1> | |
Action Sets</h1></center> | |
<b><i>Identifier: </i></b>org.eclipse.ui.actionSets | |
<p><b><i>Description: </i></b>This extension point is used to add menus, | |
menu items and toolbar buttons to the common areas in the workbench window. | |
These contributions are collectively known as an <i>action set</i> and | |
appear within the workbench window by user preference. | |
<p><b><i>Configuration Markup:</i></b> | |
<p><tt> <!ELEMENT actionSet (menu)* (action)* (description?)></tt> | |
<br><tt> <!ATTLIST actionSet</tt> | |
<br><tt> id CDATA | |
#REQUIRED</tt> | |
<br><tt> label CDATA #REQUIRED</tt> | |
<br><tt> visible (true | |
| false) #IMPLIED</tt> | |
<br><tt> ></tt> | |
<br><tt> <!ELEMENT description (#PCDATA)></tt> | |
<ul> | |
<li> | |
<b>id</b> - a unique name that will be used to identify this action set.</li> | |
<li> | |
<b>label</b> - a translatable name that will be used in the workbench window | |
menu to represent this action set.</li> | |
<li> | |
<b>visible</b> - an optional attribute indicating whether the action set | |
should be initially visible in the workbench window. The user may | |
override this option from the "Customize Perspective Dialog".</li> | |
<li> | |
<b>description</b> - an optional subelement whose body should contain text | |
providing short description of the action set.</li> | |
</ul> | |
<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> - a text label of the new menu. The label should include mnemonic | |
information.</li> | |
<li> | |
<b>path</b> - a location of the menu starting from the root of the menu | |
bar. If omitted, the menu will be added between the Perspective and Window | |
menus on the menu bar. Each token in the path must refer to an existing | |
menu in the workbench, except the last one, which should represent 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 and submenus can be added.</li> | |
</blockquote> | |
<tt> <!ELEMENT action (selection)*></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> tooltip | |
CDATA #IMPLIED</tt> | |
<br><tt> helpContextId | |
CDATA #IMPLIED</tt> | |
<br><tt> state | |
(true | false) #IMPLIED</tt> | |
<br><tt> pulldown | |
(true | false) #IMPLIED</tt> | |
<br><tt> class | |
CDATA #REQUIRED</tt> | |
<br><tt> enablesFor | |
CDATA #IMPLIED</tt> | |
<br><font face="Courier New"><font size=-2> ></font></font> | |
<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 menu bar. Each token in the path except | |
the last one must represent a valid ID of 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 | |
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 in the tool bar.</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>tooltip</b> - a value of the tool tip text if the action is to appear | |
in the 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>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>). This attribute is mutually exclusive with <tt>pulldown</tt>.</li> | |
<li> | |
<b>pulldown</b> - an optional attribute indicating that the action has | |
an additional pulldown menu. If the action appears in a toolbar, | |
and the attribute value is true, a pulldown menu will appear beside the | |
action. If the action appears in a menu this attribute is ignored. | |
This attribute is mutually exclusive with <tt>state</tt>.</li> | |
<li> | |
<b>class</b> - a fully qualified name of a class which implements <tt>org.eclipse.ui.IWorkbenchWindowActionDelegate</tt> | |
or <tt>org.eclipse.ui.IWorkbenchWindowPulldownDelegate</tt>. The | |
latter should be implemented in cases where <tt>pulldown</tt> is true.</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 for the name 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> | |
It is important to note that the workbench does not generate menus on plug-in's | |
behalf: menu paths must reference menus that already exist. | |
<p>The enablement criteria for an action extension are initially defined | |
by | |
<tt>enablesFor</tt> and <tt>selection</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 a series of modifiers and the final accelerator character (for | |
example, <tt>&amp;Save@Ctrl+S</tt>). Modifier can be chained using | |
the + sign as the delimiter (as in <tt>@Ctrl+Shift+S</tt>).</li> | |
</ol> | |
<b><i>Examples:</i></b> | |
<p>The following is an example of an action set (note the subelements and | |
the way attributes are used): | |
<p><tt> <extension point = "org.eclipse.ui.actionSets"></tt> | |
<br><tt> <actionSet id="com.xyz.actionSet"</tt> | |
<br><tt> | |
label="My Actions"</tt> | |
<br><tt> | |
visible="true"></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> </actionSet></tt> | |
<br><tt> </extension></tt> | |
<p>In the example above, the specified action, named "My Actions", is initially | |
visible within each perspective. It will only enable for a single | |
selection (<tt>enablesFor</tt> attribute). In addition, objects within | |
the selection must implement the specified interface (<tt>IFile</tt>) and | |
must be a Java file. | |
<p><b><i>API Information: </i></b>The value of the <tt>class</tt> attribute | |
must be the fully qualified name of a class that implements <tt>org.eclipse.ui.IWorkbenchWindowActionDelegate</tt> | |
or <tt>org.eclipse.ui.IWorkbenchWindowPulldownDelegate</tt>. The | |
latter should be implemented in cases where <tt>pulldown</tt> is true. | |
This class is loaded as late as possible to avoid loading the entire plug-in | |
before it is really needed. | |
<p><b><i>Supplied Implementation:</i></b> Plug-ins may use this extension | |
point to add new top level menus (for example, Debug). Plug-ins can also | |
define named groups which allow other plug-ins to contribute their actions | |
into them. | |
<p>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> | |
Omitting the <tt>path</tt> attribute will result in adding the new menu | |
into the <tt>additions</tt> menu bar group. | |
<p>The default groups in a workbench window are defined in the IWorkbenchActionConstants | |
interface. These constants can be used in code for dynamic contribution. | |
The values can also be copied into an XML file for fine grained integration | |
with the existing workbench menus and toolbar. | |
<p>Various menu and toolbar items within the workbench window are defined | |
algorithmically. In these cases a separate mechanism must be used | |
to extend the window. For example, adding a new workbench view results | |
in a new menu item appearing in the Perspective menu. Import, Export, and | |
New Wizards extensions are also added automatically to the window. | |
<br> | |
<p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corporation 2000, 2001" BORDER=0 height=12 width=195></a> | |
</body> | |
</html> |