Plugging In Popup Menu Actions
from the base Eclipse Platform is used to contribute popup menus.
The primary element in the markup for this extension point is the
which scopes the remote objects to which the child elements apply:
Within each <objectContribution> element are zero or more
optionally defining cascading submenus, and <action> elements for the actual actions.
To have the actions show up in a cascading menu, use the <menu> element with these
id. Unique id for the submenu. Used later to target actions into this cascading submenu.
label. The text the user sees in the pop-up menu.
path. 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 id/group, where id
matches the id attribute from a previous <menu> element, and group matches the name attribute
of a <separator> sub-element within that previous <menu> element. For multi-nesting, repeat the id
part, as in id1/id2/id3/group. In this case, there must be a <menu> element with and id value of
id3 that refers to another <menu> element id2 via is path attribute, which in turn
refers to <menu> element id1 via its path attribute. If the group does not exist,
it will be created.
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 additions 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.
Within each <menu> element are one or more
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:
name. The name to give this group. Users do not see this, but it is used in the action 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 additions supplied for you.
Finally, within <objectContribution> elements are one or more
elements identifying the
actual actions, each of which only show up if the scoping criteria is met for that parent <objectContribution>
element. The attributes for <action> elements are:
id. Unique id for the action.
label. What the user sees in the pop-up menu.
icon. Optional icon to show beside the label. This is the name of a file qualified by a path relative to this plugin's directory.
class. Name of the class extending one of the classes listed in the documentation.
menubarPath. 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 <menu> element.
If no menubarPath is specified, the action goes into the <additions> 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.
enablesFor. 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 setEnabled(boolean) method or overriding the getEnabled(Object currentlySelected) method that is called
when the selection changes.
state. Specify if this is a toggle (checkable) menu item. Specify "true" or "false" to indicate initial
toggle status. Call setChecked(boolean) in your class to change the toggled state.
helpContextId. Allows F1 help for this action. Optional.
The path attribute for the <menu> element, and the menubarPath attribute for the <action>
element, are the most difficult to master. The rules are reasonably simple though:
- To have your action show up in the initial pop-up menu, just specify a group name on the menubarPath 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 "additions".
- To have your action show up in a simple RSE-supplied cascading menu within the pop-up menu, in your <action> element,
specify the RSE-supplied menu ID from Table 4 in the menubarPath attribute, then a slash followed by the name of a group. The only
RSE-supplied group for cascading menus is "additions". If you specify anything else for the group, the group will be created for you
at the bottom of the menu.
- To have your action show up in a simple cascading menu of your own, first define the menu with a <menu> element,
giving it an ID via the id attribute. In your <action> element, in the menubarPath attribute specify that id followed by a slash
and then the name of a group. That group name can be one specified on a <separator> 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.
- To have your action show up in a multi-cascading menu of your own, define each of the menu via <menu> 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 <separator> element in the parent menu 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 <action> element via the menubarPath attribute,
specifying all the menu Ids up to the final menu, slash-separated, and then the group within that final menu, as usual.
To use this extension point you will create a class that implements
from the Eclipse platform.
pop-up menu action tutorial for a step-by-step example.
Eclipse Platform Programmer's Guide
for more background information.