| <!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> |