Popup Menus
Identifier
com.ibm.etools.systems.core.popupMenusDescription
This extension point is for defining actions that appear in the
popup menu of remote resources of the
Remote Systems view, in the Remote System Explorer perspective.
It is modelled after the Eclipse workbench extension point org.eclipse.ui.popupMenus.
However, because we know we are targeting remote resources, it
is simplified a bit. Specifically, there is no need to specify
the object class, as we assume these
actions apply to remote resources, which often share a common
object class. On the other hand, we
need additional filtering capabilities to scope which remote
resources these actions are to apply to.
To this end, there is a rich set of
filtering attributes to enable fine-grained scoping by a number
of criteria. These scoping attributes
are the same as those for our com.ibm.etools.systems.core.propertyPages
extension point.
Like the workbench extension point, unless you specify otherwise
, the action will show
up in the main popup menu in the "additions" group. To create
cascading sub-menus, first
define a submenu and named separator group within it, using the
menu element and its separator
sub-element. Then refer to that menu's id in your
action element's menubarPath
attribute:
menuid/separator-group-name.
While not fully documented here, this extension point supports the
<filter>
<visibility> and
<enablement> elements from the org.eclipse.ui.popupMenus
extension point. See its
documentation in the help for information on these elements.
For example:
<filter name="subsystemFactoryCategory" value="files"/>
<enablement>
<objectState name="hasChildren" value="true"/>
</enablement>
These elements are for conditionally deciding whether to show,
or enable,
the action(s). The names supported for the <filter>
element,
and the objectStates supported for the <visibility>
and
<enablement> elements are:
- "name". Will test the value for
an exact match on an object's name,
or beginning-of-name match if ends with an asterisk.
- "type". Will test the value for
an exact match on an object's type.
- "offline".Will test the value
against "true" if the user is working
in "offline" mode or "false" if not. Currently only supported
for iSeries connections.
- "connected". Will test the value
against "true" if the connection
containing the selected object is active or "false" if not.
- "hasChildren". Will test the value
against "true" if this object's
adapter reports that it has children or "false" if it doesn't
have children.
- "systemType". Will test the value
for an exact match on the system type of
this object's parent SystemConnection object.
You can specify multiple values if you comma-separate them.
- "subsystemFactoryId". Will test the value
for an exact match on the
ID of the subsystem factory that created this object's
subsystem. Returns false for SystemConnection objects.
You can specify multiple values if you comma-separate them.
- "subsystemFactoryCategory". Will test
the value for an exact match
on the category of the subsystem factory that created
this object's subsystem.
You can specify multiple values if you comma-separate them.
These objectstates are also supported via the
Eclipse org.eclipse.ui.popupMenus extension point,
for the
non-remote objects in the RSE: connections, subsystems, filter
pools
and filters.
Markup
<!ELEMENT extension (objectContribution+)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED
>
<!ELEMENT objectContribution (menu* , action*)>
<!ATTLIST objectContribution
id CDATA #REQUIRED
subsystemfactoryid CDATA #IMPLIED
subsystemfactoryCategory CDATA #IMPLIED
systemtypes CDATA #IMPLIED
namefilter CDATA #IMPLIED
typecategoryfilter CDATA #IMPLIED
typefilter CDATA #IMPLIED
subtypefilter CDATA #IMPLIED
subsubtypefilter CDATA #IMPLIED
>
- id - The id for this set of remote resource popup menu contributions. Must
be unique over all plug-ins.
It is suggested that the user qualify this with the plug-in id.
- subsystemfactoryid - One of the optional filters to scope the remote resources for
which the popup menu actions are to appear.
Specify as many of these filters as needed to explicitly scope
all the actions defined in this objectContribution element.
This filter specifies a subsystem factory id, such that these
actions will only appear for remote resources returned from subsystems of the given subsystem factory.
This ID can be scalar, or it can be generic to match on multiple subsystem factory IDs. The
IDs of the IBM-supplied subsystem factories that display remote resources in the Remote
Systems view are:
- filesLocal. For local file system resources, under
the "Files" subsystem.
- filesWindows. For remote Windows file system resources,
under the "Files" subsystem.
- files. For remote Unix and Linux file system resources,
under the "Files" subsystem.
- filesIFS. For remote iSeries unix file system resources,
under the "IFS Files" subsystem.
- files400. For remote iSeries native QSYS file system
resources, under the "iSeries Objects" subsystem.
- jobs400. For remote iSeries jobs, under the "iSeries
Jobs" subsystem.
- subsystemfactoryCategory - One of the optional filters to scope the remote resources for
which the popup menu actions are to appear.
Specify as many of these filters as needed to explicitly scope
all the actions defined in this objectContribution element.
This filter specifies a subsystem factory category, such that
these
actions will only appear for remote resources returned from subsystems
owned by factories
declared defined with the specified category.
This category can be scalar, or it can be generic to match on
multiple subsystem factory categories. The
categories of the IBM-supplied subsystem factories that display
remote resources in the Remote
Systems view are:
- files. For subsystems that list hierarchical file
system resources, such as folders and files.
- nativefiles. For subsystems that list non-hierarchical file
system resources, such as in the iSeries QSYS file system.
- commands. For subsystems that list remote commands.
- jobs. For subsystems that list remote jobs.
- systemtypes - One of the optional filters to scope the remote resources for
which the popup menu actions are to appear.
Specify as many of these filters as needed to explicitly scope
all the actions defined in this objectContribution element.
This filter specifies a single system type, or semicolon-separated list of system types,
or asterisk for all system types (the default).
Will scope these actions to only remote objects from systems of this type or types.
- namefilter - One of the optional filters to scope the remote resources for
which the popup menu actions are to appear.
Specify as many of these filters as needed to explicitly scope
all the actions defined in this objectContribution element.
This filter specifies a simple or generic resource name.
Only resources whose name matches this filter will show the actions
defined within this object contribution element.
- typecategoryfilter - One of the optional filters to scope the remote resources for
which the property page is to appear.
Specify as many of these filters as needed to explicitly scope this property page element.
This filter specifies a type category. Normally the subsystemfactoryid
is sufficient, but some subsystems display multiple types of
resources, and these are categorized by a type name that can
be used to scope property pages. Here are the type categories supported by IBM-
supplied subsystems:
- files. For hierarchical file systems resources.
- commands. For remote commands.
- jobs. For remote jobs.
The IBM-supplied subsystem for iSeries native file system objects also supports
these type categories:
- LIBRARIES. Set for libraries.
- OBJECTS. Set for objects, excluding files.
- OBJECTFILES. Set for file objects. Use OBJECTS*
to match on all objects.
- MEMBERS. Set for data and source file members.
- RECORDS. Set for record formats within files.
- FIELDS. Set for fields within record formats.
- MESSAGE_DESCRIPTIONS. Set for messages within message
files.
- typefilter - One of the optional filters to scope the remote resources for
which the popup menu actions are to appear.
Specify as many of these filters as needed to explicitly scope
all the actions defined in this objectContribution element.
This filter specifies a resource type, either simple or generic.
The resource types depends on the subsystem. The types
for IBM-supplied subsystems which support them are:
- filesXXX. Either folder or file.
- files400. This is the object's type (for objects),
such as *PGM, or member's type (for members),
such as RPGLE. Since * is a valid character in an iSeries
object type, use %ast. instead of * to prevent wildcard matching.
For example, to prevent matching on both *PGM and *SRVPGM, use %ast.PGM
for the type.
- subtypefilter - One of the optional filters to scope the remote resources for
which the popup menu actions are to appear.
Specify as many of these filters as needed to explicitly scope
all the actions defined in this objectContribution element.
This filter specifies a simple or generic resource subtype to
match. Not all subsystems support subtypes for their resources.
The IBM-supplied subsystems that do support this are:
- FilesXXX. This can be either subfolder for nested
folders only, or
root for the root folder or Windows' drives.
- Files400. For iSeries objects within a library, this is the
object's attribute. For members, it is either DTA or SRC.
For fields, it is the field's datatype (a single character).
- subsubtypefilter - One of the optional filters to scope the remote resources for
which the popup menu actions are to appear.
Specify as many of these filters as needed to explicitly scope
all the actions defined in this objectContribution element.
This filter specifies a simple or generic resource sub-subtype
to match. No IBM-supplied subsystems support sub-subtypes for
their resources today.
<!ELEMENT menu (separator*)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #REQUIRED
path CDATA #IMPLIED
>
- id - unique ID for this submenu, used later in the first part of the menubarPath attribute of
the action element or path attribute of a nested menu element. This is used to identify
the target sub-menu of the action or sub-submenu.
- label - readable text to show up in the popup menu, for this cascading menu. Do NOT specify ampersand
for mnemonics, as these are assigned for you. However, accelerator information is valid as defined
by the Eclipse rules.
- 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 the root cascading menu, you can also use this to specify
a group within the remote resource's
popup menu, where to place this cascading menu. In this case,
you would not specify an id. The default group is the additions group,
which is near the bottom of the popup menu.
The IBM pre-defined groups are:
- "group.new". This is where the cascading "New->" menu
is.
- "group.goto". This is where the cascading "Goto->"
menu is.
- "group.expandto". This is where the cascading "Expand
To->" menu is.
- "group.openwith". This is where the cascading "Open
With->" menu is.
- "group.browsewith". This is where the cascading "Browse
With->" menu is.
- "group.workwith". This is where the cascading "Work
With->" menu is.
- "group.build". Area of the menu reserved for build or refresh
related actions.
- "group.change". Area of the menu reserved for change-related actions.
- "group.reorganize". Area of the menu reserved for reorganize-related actions,
such as rename, move, copy, delete.
- "group.reorder". Area of the menu reserved for reorder-related actions,
such as move up or move down.
- "group.generate". Area of the menu reserved for code generation-related actions.
- "group.search". Area of the menu reserved for search-related actions.
- "group.connection". Area of the menu reserved for connection-related actions.
- "group.importexport". Area of the menu reserved for import or export-related actions.
- "group.adapter". Area of the menu reserved for actions queried from the remote resource adapters.
- "additions". Area of the menu reserved for actions that don't specify a group.
- "group.team". Area of the menu reserved for team-related actions.
- "group.properties". Area of the menu reserved for properties-related actions.
You may also desire to place your action in an IBM-supplied cascading menu.
To do this, for the ID-part, specify one of the following IBM-supplied menu IDs:
- "menu.new". This is the cascading "New->" menu.
- "menu.goto". This is the cascading "Goto->" menu.
- "menu.expandto". This is the cascading "Expand To->" menu.
- "menu.openwith". This is the cascading "Open With->" menu.
- "menu.browsewith". This is the cascading "Browse With->" menu.
- "menu.workwith". This is the cascading "Work With->" menu.
<!ELEMENT action EMPTY>
<!ATTLIST action
id CDATA #REQUIRED
label CDATA #REQUIRED
icon CDATA #IMPLIED
tooltip CDATA #IMPLIED
menubarPath CDATA #IMPLIED
enablesFor CDATA #IMPLIED
state (true | false) "false"#IMPLIED
helpContextId CDATA #IMPLIED
class CDATA #REQUIRED
>
- id - Unique ID for this action.
- label - Readable text to display in the popup menu for this action. Do NOT specify ampersand for mnemonics,
as these are assigned for you. However, accelerator information is valid, as defined by the Eclipse rules.
- icon - An optional image icon for the popup menu. This is a .gif file, given with a path relative to your plugin
directory.
- tooltip - Optional tooltip text for this action. This appears in the status bar when the action is selected.
- menubarPath - A slash-delimited path that is used to specify the location of the the action in the popup menu. Each token
in the path, except the last one, represents an existing submenu in the hierarchy, as defined via the id
attribute of a menu element previously defined. Alternatively, the ID of an IBM-supplied cascading
menu can be specified. The last token represents the named separator group into which the action will be added.
If no path is given, this must be an IBM-supplied group.
See the comments for the path attribute of the menu element for a list of the IBM-supplied cascading menus,
and IBM-supplied separator groups.
If a path is given, then this must match the name attribute of a separator sub-element
within one of your menu elements.
If the path is omitted, or this menubarPath attribute, the action will be added to the standard "additions" group.
- enablesFor - A value indicating the selection count which must be met to enable the action. If this attribute is specified and
the condition is met, the action is enabled. If the condition is not met, the action is disabled. If no attribute
is specified, the action is enabled for any number of resources selected. The following formats are supported:
- !. 0 items selected.
- ?. 0 or 1 items selected.
- +. 1 or more items selected.
- n+. n or more items selected. Example: 2+.
- n. A precise number of items selected. Example: 4
- *. Any number of items selected.
- state - Optional attribute indicating the action is a toggle type. That
is, is shown as a check box menu item. The attribute value will
be used as the initial state.
- helpContextId - Optional unique identifier indicating the help context ID for this action. When the action appears as a menu item, pressing
F1 while the menu item is highlighted will display help for the given context ID.
- class - Your action class that implements org.eclipse.ui.IObjectActionDelegate.
Typically you will extend one of the IBM-supplied classes, described in the API Information section.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name CDATA #REQUIRED
>
- name - The arbitrary, but unique with this menu, name to assign this group. You can specify this name
later in the menubarPath attribute of an action, or the group part of the path attribute of a
menu.
Example
The following is an example of a defining a simple popup menu
action for any files and folders in any system type, which only
shows when a single file or folder is selected:
Example One
<extension point="com.ibm.etools.systems.core.popupMenus">
<objectContribution
id="com.acme.actions.action1"
typecategoryfilter="files">
<action id="com.acme.action1"
label="Test Action for Files and Folders"
class="com.acme.actions.Action1"
enablesFor="1">
</action>
</objectContribution>
</extension>
The following example refines the first example so the action
only appears
for Java source files, not folders, and only for files in a local
connection.
Further, we show how to define multiple actions within one objectContribution:
Example Two
<extension point="com.ibm.etools.systems.core.popupMenus">
<objectContribution
id="com.acme.actions.action2"
typecategoryfilter="files"
typefilter="file"
namefilter="*.java"
subsystemfactoryid="ibm.filesLocal">
<action id="com.acme.action2a"
label="Test Action One for Local Java Files"
class="com.acme.actions.Action2a"
enablesFor="1">
</action>
<action id="com.acme.action2b"
label="Test Action Two for Local Java Files"
class="com.acme.actions.Action2b"
enablesFor="1">
</action>
</objectContribution>
</extension>
The following example refines the second example, by moving the
actions to our own single-cascading menu:
Example Three
<extension point="com.ibm.etools.systems.core.popupMenus">
<objectContribution
id="com.acme.actions.action3"
typecategoryfilter="files"
typefilter="file"
namefilter="*.java"
subsystemfactoryid="ibm.filesLocal">
<menu id="com.acme.menu"
label="Test Actions">
<separator name="taGroup"/>
</menu>
<action id="com.acme.action3a"
label="Test Action One for Local Java Files"
class="com.acme.actions.Action3a"
enablesFor="1"
menubarPath="com.acme.menu/taGroup">
</action>
<action id="com.acme.action3b"
label="Test Action Two for Local Java Files"
class="com.acme.actions.Action3b"
enablesFor="1"
menubarPath="com.acme.menu/taGroup">
</action>
</objectContribution>
</extension>
The following example refines the third example, by moving the
actions to our own multiple-cascading menu. Notice how
we
can define the same separator group in different menus since
they
are unrelated to each other:
Example Four
<extension point="com.ibm.etools.systems.core.popupMenus">
<objectContribution
id="com.acme.actions.action4"
typecategoryfilter="files"
typefilter="file"
namefilter="*.java"
subsystemfactoryid="ibm.filesLocal">
<menu id="com.acme.menu"
label="Test Actions">
<separator name="taGroup"/>
</menu>
<menu id="com.acme.menu2"
label="A Sub Menu"
path="com.acme.menu/taGroup">
<separator name="taGroup"/>
</menu>
<action id="com.acme.action4a"
label="Test Action One for Local Java Files"
class="com.acme.actions.Action4a"
enablesFor="1"
menubarPath="com.acme.menu/com.acme.menu2/taGroup">
</action>
<action id="com.acme.action4a"
label="Test Action Two for Local Java Files"
class="com.acme.actions.Action4b"
enablesFor="1"
menubarPath="com.acme.menu/com.acme.menu2/taGroup">
</action>
</objectContribution>
</extension>
The following example shows how to place actions within an
IBM-supplied cascading menu:
Example Five
<extension point="com.ibm.etools.systems.core.popupMenus">
<objectContribution
id="com.acme.actions.action5"
typecategoryfilter="files"
typefilter="file"
namefilter="*.java"
subsystemfactoryid="ibm.filesLocal">
<action id="com.acme.action5a"
label="Test Action One for Local Java Files"
class="com.acme.actions.Action5a"
enablesFor="1"
menubarPath="menu.openwith/additions">
</action>
<action id="com.acme.action5b"
label="Test Action Two for Local Java Files"
class="com.acme.actions.Action5b"
enablesFor="1"
menubarPath="menu.browsewith/additions">
</action>
</objectContribution>
</extension>
Remember, you can repeat the objectContribution elements as
needed, as well as the menu and action elements within them.
API Information
Your actions must all implement the interface org.eclipse.ui.IObjectActionDelegate.
Typically, you will subclass one of the supplied base classes
for this extension point:
- com.ibm.etools.systems.core.ui.actions.SystemAbstractPopupMenuExtensionAction,
in plugin com.ibm.etools.systems.core.
Base class offering generic support for any remote resource popup
menu action, for any system type.
- com.ibm.etools.systems.core.ui.actions.SystemAbstractRemoteFilePopupMenuExtensionAction,
in plugin com.ibm.etools.systems.core.
Specialized base class offering specific support for any remote
file or folder popup menu action, for any system type.
- com.ibm.etools.iseries.core.ui.actions.isv.ISeriesAbstractIFSPopupMenuExtensionAction,
in plugin com.ibm.etools.iseries.core.
Specialized base class offering specific support for iSeries
IFS file or folder popup menu actions.
- com.ibm.etools.iseries.core.ui.actions.isv.ISeriesAbstractQSYSPopupMenuExtensionAction,
in plugin com.ibm.etools.iseries.core.
Specialized base class offering specific support for popup menu
actions for iSeries objects in the QSYS file system.
Supplied Implementation
There is no supplied implementation for this extension point.
(C) Copyright IBM Corp. 2002 All Rights Reserved.