| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| |
| <head> |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2002, 2007. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| <LINK REL="STYLESHEET" HREF="../../book.css" TYPE="text/css"> |
| <title>Plugging In Popup Menu Actions</title> |
| </head> |
| |
| <body bgcolor="#ffffff"> |
| <h1>Plugging In Popup Menu Actions</h1> |
| <p>The <samp><a href="../../../org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_ui_popupMenus.html">org.eclipse.ui.popupMenus</a></samp> extension point |
| from the base Eclipse Platform is used to contribute popup menus. |
| </p> |
| <p>The primary element in the markup for this extension point is the <b><samp><objectContribution></samp></b> element, |
| which scopes the remote objects to which the child elements apply: |
| </p> |
| <ul> |
| <li><b>id</b>.A unique ID for this extension point. Not used, but required by Eclipse.</li> |
| <li><a name="objectClass"></a> |
| <b>objectClass</b>. The element on which the popup menu action should appear. |
| To use this you need to know the class type of these objects for the <samp>objectClass</samp> attribute |
| of the <objectContribution> element: |
| <ul> |
| <li>Connections: <samp><A href="../../reference/api/org/eclipse/rse/core/model/IHost.html">org.eclipse.rse.core.model.IHost</A></samp></li> |
| <li>SubSystems: <samp><A href="../../reference/api/org/eclipse/rse/core/subsystems/ISubSystem.html">org.eclipse.rse.core.subsystems.ISubSystem</A></samp></li> |
| <li>Filter Pools: <samp><A href="../../reference/api/org/eclipse/rse/core/filters/ISystemFilterPoolReference.html">org.eclipse.rse.core.filters.ISystemFilterPoolReference</A></samp></li> |
| <li>Filters: <samp><A href="../../reference/api/org/eclipse/rse/core/filters/ISystemFilterReference.html">org.eclipse.rse.core.filters.ISystemFilterReference</A></samp></li> |
| <li>Remote Elements: your model objects, which are adaptable to <samp>ISystemViewElementAdapter</samp>. |
| For the RSE-provided reusable file, process and shell subsystems, these are |
| <samp><a href="../../reference/api/org/eclipse/rse/subsystems/files/core/subsystems/IRemoteFile.html">IRemoteFile</a></samp>, |
| <samp><a href="../../reference/api/org/eclipse/rse/subsystems/processes/core/subsystem/IRemoteProcess.html">IRemoteProcess</a></samp> and |
| <samp><a href="../../reference/api/org/eclipse/rse/subsystems/shells/core/subsystems/IRemoteCommandShell.html">IRemoteCommandShell</a></samp>, respectively. |
| In the Remote Command View, you'll also find |
| <samp><a href="../../reference/api/org/eclipse/rse/subsystems/shells/core/subsystems/IRemoteError.html">IRemoteError</a></samp> and |
| <samp><a href="../../reference/api/org/eclipse/rse/subsystems/shells/core/subsystems/IRemoteOutput.html">IRemoteOutput</a></samp>. |
| </li> |
| </ul></li> |
| <li><a name="filtering"></a> |
| <b><i>filtering attributes</i></b>.To scope which remote objects these actions should show up for. |
| Because all RSE elements adapt to |
| <samp><A href="../../reference/api/org/eclipse/rse/ui/view/ISystemViewElementAdapter.html">ISystemViewElementAdapter</A></samp>, |
| which in turn extends |
| <samp><A href="../../../org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/IActionFilter.html">org.eclipse.ui.IActionFilter</A></samp>, |
| it is possible to scope your actions to only appear for certain system types or subsystems, using |
| the extension point's <samp><filter></samp> element. For example:<br> |
| <pre><code> |
| <extension point="org.eclipse.ui.popupMenus"> |
| <objectContribution |
| id ="samples.ui.actions.TeamFilterActions" |
| objectClass="org.eclipse.rse.core.filters.ISystemFilterReference"> |
| <b><filter name="subsystemConfigurationId" value="samples.subsystems.factory"/></b> |
| <action id="samples.ui.actions.TeamFilterAction1" |
| label="Sample Team Filter Action" |
| class="samples.ui.actions.ShowJarContents"> |
| </action> |
| </objectContribution> |
| </extension> |
| </code></pre> |
| See <a href="other.html#scoping">Scoping</a> for all the filter <samp>names</samp> supported by RSE objects. |
| </li> |
| </ul> |
| <p>Within each <samp><objectContribution></samp> element are zero or more <B><samp><menu></samp></B> elements for |
| optionally defining cascading submenus, and <<B>action</B>> elements for the actual actions. |
| To have the actions show up in a cascading menu, use the <samp><menu></samp> element with these |
| attributes: |
| </p> |
| <ul> |
| <li><b>id</b>. Unique id for the submenu. Used later to target actions into this cascading submenu. |
| <li><b>label</b>. The text the user sees in the pop-up menu. |
| <li><b>path</b>. For multi-cascading menus, use this attribute to identify a previously specified menu that |
| this menu is to be nested within. The syntax is a bit tricky. It is <samp>id/group</samp>, where <samp>id</samp> |
| matches the id attribute from a previous <samp><menu></samp> element, and <samp>group</samp> matches the name attribute |
| of a <samp><separator></samp> sub-element within that previous <samp><menu></samp> element. For multi-nesting, repeat the <samp>id</samp> |
| part, as in <samp>id1/id2/id3/group</samp>. In this case, there must be a <samp><menu></samp> element with and id value of |
| <samp>id3</samp> that refers to another <samp><menu></samp> element <samp>id2</samp> via is path attribute, which in turn |
| refers to <samp><menu></samp> element <samp>id1</samp> via its <samp>path</samp> attribute. If the group does not exist, |
| it will be created. |
| <br> |
| For the root cascading menu, you can also use this to specify a group within the remote object's pop-up, |
| for where to place this cascading menu. The default is the <samp>additions</samp> group, which is near the |
| bottom of the pop-up menu. The RSE-supplied groups for pop-up menus are listed shortly in Table 4. There are |
| also a few RSE-supplied cascading menus listed in Table 4, which can be specified for the id prefix in order |
| to add a cascading menu to an RSE-supplied cascading menu. |
| </ul> |
| <P>Within each <samp><menu></samp> element are one or more <b><samp><separator></samp></b> elements that partition the cascading |
| menu into groups. Groups are simply named physical areas of the menu. The order in which they are defined is the order they |
| appear in the menu. Actions always go into groups. Groups avoid the need to specify relative information to identify where |
| within a pop-up menu to place actions. There is only one attribute for this element: |
| </P> |
| <ul> |
| <li><b>name</b>. The name to give this group. Users do not see this, but it is used in the <samp>action</samp> element to identify where to place |
| the action within this submenu. Groups exist in the order they are defined, top to bottom. Between groups is a separator unless |
| contiguous groups are empty. There is always a default group named <samp>additions</samp> supplied for you. |
| </ul> |
| <p>Finally, within <samp><objectContribution></samp> elements are one or more <b><samp><action></samp></b> elements identifying the |
| actual actions, each of which only show up if the scoping criteria is met for that parent <samp><objectContribution></samp> |
| element. The attributes for <samp><action></samp> elements are: |
| </p> |
| <ul> |
| <li><b>id</b>. Unique id for the action. |
| <li><b>label</b>. What the user sees in the pop-up menu. |
| <li><b>icon</b>. Optional icon to show beside the label. This is the name of a file qualified by a path relative to this plugin's directory. |
| <li><b>class</b>. Name of the class extending one of the classes listed in the documentation. |
| <li><b>menubarPath</b>. Where to put this action. This is optional and only required when you do not want the action to go into the |
| default location within the remote object's pop-up menu. This is a group name, optionally preceded by slash-delimited Ids for actions |
| that go inside cascading menus, where each Id matches an id attribute from a previously specified <samp><menu></samp> element. |
| If no menubarPath is specified, the action goes into the <samp><additions></samp> area of the object's popup menu, which is |
| near the bottom of the pop-up menu. The RSE-supplied groups for remote object pop-up menus are listed in Table 4, as well as menu Ids |
| for RSE-supplied cascading menus, should you wish to add an action to an RSE-supplied cascading menu. |
| <li><b>enablesFor</b>. Tells when to enable this action based on how many items are selected. Typically, specify "1" for |
| single-selection or "+" for multiple-selection. You can also change the enabled state of your action within your class, |
| by calling the <samp>setEnabled(boolean)</samp> method or overriding the <samp>getEnabled(Object[] currentlySelected)</samp> method that is called |
| when the selection changes. |
| <li><b>state</b>. Specify if this is a toggle (checkable) menu item. Specify "true" or "false" to indicate initial |
| toggle status. Call <samp>setChecked(boolean)</samp> in your class to change the toggled state. |
| <li><b>helpContextId</b>. Allows F1 help for this action. Optional. |
| </ul> |
| <p> |
| The <samp>path</samp> attribute for the <samp><menu></samp> element, and the <samp>menubarPath</samp> attribute for the <samp><action></samp> |
| element, are the most difficult to master. The rules are reasonably simple though: |
| </p> |
| <ol> |
| <li>To have your action show up in the initial pop-up menu, just specify a group name on the <samp>menubarPath</samp> attribute. That name can be |
| one of the RSE-supplied group names defined in Table 4, or your own group name, which will be created and appended to the end of the |
| pop-up menu. The default group is <samp>"additions"</samp>. |
| <br>Example: <samp>menubarPath="myGroup"</samp> |
| <li>To have your action show up in a simple RSE-supplied cascading menu within the pop-up menu, in your <samp><action></samp> element, |
| specify the RSE-supplied menu ID from Table 4 in the <samp>menubarPath</samp> attribute, then a slash followed by the name of a group. The only |
| RSE-supplied group for cascading menus is <samp>"additions"</samp>. If you specify anything else for the group, the group will be created for you |
| at the bottom of the menu. |
| <br>Example: <samp>menubarPath="menu.new/myGroup"</samp> |
| <li>To have your action show up in a simple cascading menu of your own, first define the menu with a <samp><menu></samp> element, |
| giving it an ID via the id attribute. In your <samp><action></samp> element, in the <samp>menubarPath</samp> attribute specify that id followed by a slash |
| and then the name of a group. That group name can be one specified on a <samp><separator></samp> element within your menu, or a new name, which |
| results in a new group at the bottom of the menu. In the latter case, there will be no separators delimiting the group, while in the former case |
| there will be. |
| <br>Example: <samp>menubarPath="myMenu1/myGroup"</samp> |
| <li>To have your action show up in a multi-cascading menu of your own, define each of the menu via <samp><menu></samp> elements. For all but the |
| first, identify the parent menu using the path attribute, specifying the Ids for each of the parent menus, slash-separated. At |
| the end of the path attribute, specify the group within the final parent menu into which this menu will be placed. Again, this |
| will either be a group defined with a <samp><separator></samp> element in the parent <samp>menu</samp> element, or specify a non-existing group that will be |
| created for you. Once your multi-cascading menu is created, you identify it in your <samp><action></samp> element via the <samp>menubarPath</samp> attribute, |
| specifying all the menu Ids up to the final menu, slash-separated, and then the group within that final menu, as usual. |
| <br>Example: <samp>menubarPath="myMenu1/myMenu2/myGroup"</samp> |
| </ol> |
| |
| <h2>Programming Details</h2> |
| <p>To use this extension point you will create a class that implements |
| <samp> |
| <A href="../../../org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/IObjectActionDelegate.html">IObjectActionDelegate</A> |
| </samp> from the Eclipse platform. |
| </p> |
| <br><hr> |
| <p>See the <a href="../tutorial/popup.html">pop-up menu action tutorial</a> for a step-by-step example.</p> |
| <p>See the <a href="../../../org.eclipse.platform.doc.isv/guide/workbench_basicext_popupMenus.htm">Eclipse Platform Programmer's Guide</a> |
| for more background information.</p> |
| </body> |
| </html> |
