<!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: Pop-up Menus</title> | |
</head> | |
<body link="#0000FF" vlink="#800080"> | |
<center> | |
<h1> | |
Pop-up Menus</h1></center> | |
<b><i>Identifier: </i></b>org.eclipse.ui.popupMenus | |
<p><b><i>Description: </i></b>This extension point is used to add new actions | |
to pop-up menus owned by other plug-ins. Action contribution may | |
be made against a specific object type (<tt>objectContribution</tt>) or | |
against a specific popup menu. When registered for an object type, a contribution | |
will appear in all viewers where objects of the specified type are selected. | |
In contrast, registration against a popup menu will only appear in the | |
specified menu, regardless of the selection. | |
<p>When selection is heterogeneous, contribution will be applied if registered | |
against a common type of the selection, if possible. If a direct match | |
is not possible, matching against superclasses and superinterfaces will | |
be attempted. | |
<p>Selection can be further constrained through the use of a name filter. | |
If used, all the objects in the selection must match the filter in order | |
to apply the contribution. | |
<p>Individual actions in an object contribution can use attribute <tt>enablesFor</tt> | |
to specify if it should only apply for a single, multiple, or any other | |
selection type. | |
<p>If these filtering mechanisms are inadequate an action contribution | |
may use the <tt>filter</tt> mechanism. In this case the attributes | |
of the target object are described in a series of key value pairs. | |
The attributes which apply to the selection are type specific and beyond | |
the domain of the workbench itself, so the workbench will delegate filtering | |
at this level to the actual selection. | |
<p><b><i>Configuration Markup:</i></b> | |
<p><tt> <!ELEMENT objectContribution (filter | menu | action)* | |
(visibility)?></tt> | |
<br><tt> <!ATTLIST objectContribution</tt> | |
<br><tt> id | |
CDATA #REQUIRED</tt> | |
<br><tt> objectClass CDATA #REQUIRED</tt> | |
<br><tt> nameFilter CDATA #IMPLIED</tt> | |
<br><tt> adaptable (true|false) | |
#IMPLIED</tt> | |
<br><tt> ></tt> | |
<ul> | |
<li> | |
<b>id</b> - a unique identifier that can be used to reference this contribution</li> | |
<li> | |
<b>objectClass</b> - a fully qualified name of the class or interface that | |
all the objects in the selection must subclass or implement.</li> | |
<li> | |
<b>nameFilter</b> - an optional filter that will be applied against each | |
object in the selection. No contribution will take place if there is no | |
match.</li> | |
<li> | |
<b>adaptable</b> - a flag that indicates if types that adapt to IResource | |
should use this object contribution. This flag is used only if objectClass | |
adapts to IResource. Default value is false.</li> | |
</ul> | |
<tt> <!ELEMENT visibility (and | or | not | objectClass | |
| objectState | systemProperty</tt> | |
<br><tt> | pluginState)></tt> | |
<br><tt> <!ATTLIST visibility EMPTY></tt> | |
<blockquote>In version 2.0 of Eclipse, a <tt>visibility</tt> element may | |
be used in an <tt>objectContribution</tt> to define the visibility for | |
the action. This is not a replacement for the <tt>objectClass</tt> | |
attribute, which defines the primary target for the action. The <tt>visibility</tt> | |
element is used to refine the primary target. For more information | |
on the use of <tt>visibility</tt> element, refer to <a href="actionExpressions.html">actionExpressions.html</a>.</blockquote> | |
<tt> <!ELEMENT viewerContribution (menu | action)*></tt> | |
<br><tt> <!ATTLIST viewerContribution</tt> | |
<br><tt> id | |
CDATA #REQUIRED</tt> | |
<br><tt> targetID CDATA #REQUIRED</tt> | |
<br><tt> ></tt> | |
<ul> | |
<li> | |
<b>id</b> - a unique identifier that can be used to reference this contribution</li> | |
<li> | |
<b>targetID</b> - the unique identifier of a popup menu inside a view, | |
editor or viewer.</li> | |
</ul> | |
<tt> <!ELEMENT filter EMPTY></tt> | |
<br><tt> <!ATTLIST filter</tt> | |
<br><tt> name | |
CDATA #REQUIRED</tt> | |
<br><tt> value | |
CDATA #REQUIRED</tt> | |
<br><tt> ></tt> | |
<ul> | |
<li> | |
<b>name</b> - the name of an object attribute.</li> | |
<li> | |
<b>value</b> - the value of an object attribute. In combination with | |
the name attribute, the name value pair is used to define the target object | |
for an object action contribution.</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 submenu</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 submenu starting from the pop-up menu | |
as a root. If omitted, the menu will be added at the end of the pop-up | |
menu.</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> - the 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> icon | |
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 will be used for a pop-up menu | |
item label. The label can contain JFace-encoded mnemonic and accelerator | |
(see example).</li> | |
<li> | |
<b>menubarPath</b> - a slash-delimited path ('/') that is used to specify | |
the location of the action in the pop-up menu. Each token in the path except | |
the last one represents an existing submenu 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 be added to the standard | |
additions group defined by <tt>IWorkbenchActionConstants.MB_ADDITIONS</tt>.</li> | |
<li> | |
<b>icon</b> - a relative path for an icon that will be used to visually | |
represent the action in the pop-up menu. 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 pop-up menu, it will manifest itself | |
as a check box item.. If defined, attribute value will be used as the initial | |
state (either <tt>true</tt> or <tt>false</tt>)</li> | |
<li> | |
<b>helpContextId</b> - a unique identifier indicating the help context | |
id for this action. When the action appears as a menu item, pressing F1 | |
while the menu item is highlighted will display help for the given context | |
id.</li> | |
<li> | |
<b>class</b> - a name of the fully qualified class that implements <tt>org.eclipse.ui.IObjectActionDelegate | |
</tt>(for | |
object actions), <tt>org.eclipse.ui.IViewActionDelegate</tt> (for view-related | |
viewer actions), or <tt>org.eclipse.ui.IEditorActionDelegate</tt> (for | |
editor-related viewer actions). For backwards compatability, | |
<tt>org.eclipse.ui.IActionDelegate</tt> | |
may be implemented for object contributions.</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> | |
<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 | |
'@' followed by the series of modifiers and the final accelerator character | |
(for example, <tt>&amp;Save@Ctrl+S</tt>). Accelerators with more than | |
one modifier are obtained by chaining modifiers, 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 a pop-up menu extension point: | |
<p><tt> <extension point="org.eclipse.ui.popupMenus"></tt> | |
<br><tt> <objectContribution</tt> | |
<br><tt> id="com.xyz.C1"</tt> | |
<br><tt> objectClass="org.eclipse.core.resources.IFile"</tt> | |
<br><tt> nameFilter="*.java"></tt> | |
<br><tt> <menu id="com.xyz.xyzMenu"</tt> | |
<br><tt> | |
path="additions"</tt> | |
<br><tt> | |
label="&amp;XYZ Java Tools"></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> | |
icon="icons/runXYZ.gif"</tt> | |
<br><tt> | |
helpContextId="com.xyz.run_action_context"</tt> | |
<br><tt> | |
class="com.xyz.actions.XYZToolActionDelegate"</tt> | |
<br><tt> | |
enablesFor="1"></tt> | |
<br><tt> </action></tt> | |
<br><tt> </objectContribution></tt> | |
<br><tt> <viewerContribution</tt> | |
<br><tt> id="com.xyz.C2"</tt> | |
<br><tt> targetID="org.eclipse.ui.views.TaskList"></tt> | |
<br><tt> <action | |
id="com.xyz.showXYZ"</tt> | |
<br><tt> | |
label="&amp;Show XYZ"</tt> | |
<br><tt> | |
menubarPath="additions"</tt> | |
<br><tt> | |
icon="icons/showXYZ.gif"</tt> | |
<br><tt> | |
helpContextId="com.xyz.show_action_context"</tt> | |
<br><tt> | |
class="com.xyz.actions.XYZShowActionDelegate"></tt> | |
<br><tt> </action></tt> | |
<br><tt> </viewerContribution></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 | |
the selection must implement the specified interface (<tt>IFile</tt>) and | |
must be a Java file. This action will be added into a submenu previously | |
created. This contribution will be effective in any view that has the required | |
selection. | |
<p>In contrast, the viewer contribution above will only appear in the Tasks | |
view, and will not be affected by the selection in the view. | |
<p>The following is an example of the filter mechanism. In this case | |
the action will only appear for IMarkers which are completed and have high | |
priority. | |
<p><tt> <extension point="org.eclipse.ui.popupMenus"></tt> | |
<br><tt> <objectContribution</tt> | |
<br><tt> id="com.xyz.C1"</tt> | |
<br><tt> objectClass="org.eclipse.core.resources.IMarker"></tt> | |
<br><tt> <filter name="done" | |
value="true"/></tt> | |
<br><tt> <filter name="priority" | |
value="2"/></tt> | |
<br><tt> <action id="com.xyz.runXYZ"</tt> | |
<br><tt> | |
label="High Priority Completed Action Tool"</tt> | |
<br><tt> | |
icon="icons/runXYZ.gif"</tt> | |
<br><tt> | |
class="com.xyz.actions.MarkerActionDelegate"></tt> | |
<br><tt> </action></tt> | |
<br><tt> </objectContribution></tt> | |
<br><tt> </extension></tt> | |
<p><b><i>API Information: </i></b>The value of the action attribute | |
<tt>class</tt> | |
must be a fully qualified class name of a Java class that implements <tt>org.eclipse.ui.IObjectActionDelegate | |
</tt>in | |
the case of object contributions, <tt>org.eclipse.ui.IViewActionDelegate</tt> | |
for contributions to viewers that belong to views, or <tt>org.eclipse.ui.IEditorActionDelegate</tt> | |
for contributions to viewers that belong to editors. In all cases, | |
the implementing class is loaded as late as possible to avoid loading the | |
entire plug-in before it is really needed. | |
<p>Note: For backwards compatability, <tt>org.eclipse.ui.IActionDelegate</tt> | |
may be implemented for object contributions. | |
<p>Popup menu extension within a part is only possible when the target | |
part publishes a menu for extension. This is heartily encouraged, | |
as it improves the extensability of the product. To accomplish this | |
each part should publish any popup menus which are defined by calling <tt>IWorkbenchPartSite#registerContextMenu</tt>. | |
Once this has been done the workbench will automatically insert any action | |
extensions which exist. | |
<p>A menu id must be provided for each registered menu. For consistency | |
across parts the following strategy should be adopted by all part implementors. | |
<ul> | |
<li> | |
If the target part has only one context menu it should be registered with | |
<tt>id | |
== part id</tt>. This can be done easily by calling <tt>registerContextMenu(MenuManager, | |
ISelectionProvider)</tt>. Extenders may use the <tt>part id</tt> | |
itself as the <tt>targetID</tt> for the action extension.</li> | |
<li> | |
If the target part has more than one context menu a unique id should be | |
defined for each. Prefix each id with the view id and publish these | |
id's within the javadoc for the target part. Register each menu at | |
runtime by calling <tt>registerContextMenu(String, MenuManager, ISelectionProvider)</tt>. | |
Extenders will use the unique menu id as the <tt>targetID</tt> for the | |
action extension.</li> | |
</ul> | |
Any pop-up menu which is registered with the workbench also should contain | |
a standard insertion point with id <tt>IWorkbenchActionConstants.MB_ADDITIONS</tt>. | |
Other plug-ins will use this value as a reference point for insertion. | |
The insertion point may be defined by adding a <tt>GroupMarker</tt> to | |
the menu at an appropriate location for insertion. | |
<p>An object in the workbench which is the selection in a context menu | |
may define an <tt>org.eclipse.ui.IActionFilter</tt>. This is a filtering | |
strategy which can perform type specific filtering. The workbench | |
will retrieve the filter for the selection by testing to see if it implements | |
<tt>IActionFilter</tt>. | |
If that fails, the workbench will ask for a filter through the <tt>IAdaptable</tt> | |
mechanism. | |
<p><b><i>Supplied Implementation: </i></b>The workbench view have built-in | |
pop-up menus that already come loaded with a number of actions. Plug-ins | |
can contribute to these menus. If a viewer has reserved slots for these | |
contributions and they are made public, slot names can be used as paths. | |
Otherwise, actions and submenus will be added at the end of the pop-up | |
menu. | |
<p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corp. 2000, 2001. All Rights Reserved." BORDER=0 height=12 width=195></a> | |
</body> | |
</html> |