1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
<!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>
|
