Popup Menus

Identifier

com.ibm.etools.systems.core.popupMenus

Description

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:

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
   >

   <!ELEMENT menu (separator*)>
   <!ATTLIST menu
     id    CDATA #REQUIRED
     label CDATA #REQUIRED
     path  CDATA #IMPLIED
   >

   <!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
   >

   <!ELEMENT separator EMPTY>
   <!ATTLIST separator
     name CDATA #REQUIRED
   >

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:

Supplied Implementation

There is no supplied implementation for this extension point.

(C) Copyright IBM Corp. 2002 All Rights Reserved.