mirror of
https://github.com/eclipse-cdt/cdt
synced 2025-07-05 08:05:24 +02:00
161 lines
13 KiB
HTML
Executable file
161 lines
13 KiB
HTML
Executable file
<!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>
|