Plugging In Popup Menu Actions

The org.eclipse.ui.popupMenus extension point from the base Eclipse Platform is used to contribute popup menus.

The primary element in the markup for this extension point is the <objectContribution> element, which scopes the remote objects to which the child elements apply:

• id.A unique ID for this extension point. Not used, but required by Eclipse.
• objectClass. 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 objectClass attribute of the <objectContribution> element:
  • Connections: org.eclipse.rse.core.model.IHost
  • SubSystems: org.eclipse.rse.core.subsystems.ISubSystem
  • Filter Pools: org.eclipse.rse.core.filters.ISystemFilterPoolReference
  • Filters: org.eclipse.rse.core.filters.ISystemFilterReference
  • Remote Elements: your model objects, which are adaptable to ISystemViewElementAdapter. For the RSE-provided reusable file, process and shell subsystems, these are IRemoteFile, IRemoteProcess and IRemoteCommandShell, respectively. In the Remote Command View, you'll also find IRemoteError and IRemoteOutput.
• filtering attributes.To scope which remote objects these actions should show up for. Because all RSE elements adapt to ISystemViewElementAdapter, which in turn extends org.eclipse.ui.IActionFilter, it is possible to scope your actions to only appear for certain system types or subsystems, using the extension point's <filter> element. For example:
  

  
         <extension point="org.eclipse.ui.popupMenus">
             <objectContribution
                   id ="samples.ui.actions.TeamFilterActions"
                   objectClass="org.eclipse.rse.core.filters.ISystemFilterReference">
                   <filter name="subsystemFactoryId" value="samples.subsystems.factory"/>
                   <action id="samples.ui.actions.TeamFilterAction1"
                           label="Sample Team Filter Action"
                            class="samples.ui.actions.ShowJarContents">
                   </action>
             </objectContribution>
         </extension>
      

  See Scoping for all the filter names supported by RSE objects.

Within each <objectContribution> element are zero or more <menu> elements for 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 attributes:

• 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 <separator> 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 <action> 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:

1. 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".
   Example: menubarPath="myGroup"
2. 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.
   Example: menubarPath="menu.new/myGroup"
3. 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.
   Example: menubarPath="myMenu1/myGroup"
4. 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.
   Example: menubarPath="myMenu1/myMenu2/myGroup"

Programming Details

To use this extension point you will create a class that extends the SystemAbstractPopupMenuExtensionAction class in the package org.eclipse.rse.ui.actions. This is your action class, and when the user selects your action, the run() method in your action class will be called. You will rarely extend the SystemAbstractPopupMenuExtensionAction base class directly, though. Instead there are subclasses of it that offer additional functionality for specific types of remote objects, as shown here:

See the pop-up menu action tutorial for a step-by-step example.

See the Eclipse Platform Programmer's Guide for more background information.