Pop-up Menus

This extension point is deprecated

Identifier:
org.eclipse.ui.popupMenus

Description:

WARNING: This extension point is DEPRECATED.
Do not use this extension point, it will be removed in future versions of this product. Instead, use the extension point org.eclipse.ui.commands

This extension point is used to add new actions to context menus owned by other plug-ins. Action contributions may be made against a specific object type (objectContribution) or against a specific context menu of a view or editor part (viewerContribution). When using objectContribution, the contribution will appear in all view or editor part context menus where objects of the specified type are selected. In contrast, using viewerContribution, the contribution will only appear in the specified context menu of a view or editor, regardless of the selection.

You can now use org.eclipse.ui.menus to place commands editor or view contexts menus as well.

When the selection is heterogeneous, the contribution will be applied if registered against a common type of the selection, if possible. If a direct match is not possible, matching against superclasses and superinterfaces will be attempted.

Selection can be further constrained through the use of a name filter. If used, all the objects in the selection must match the filter in order to apply the contribution.

Individual actions in an object contribution can use the attribute enablesFor to specify if it should only apply for a single, multiple, or any other selection type.

If these filtering mechanisms are inadequate an action contribution may use the filter mechanism. In this case the attributes of the target object are described in a series of name-value pairs. The attributes which apply to the selection are type-specific and beyond the domain of the workbench itself, so the workbench will delegate filtering at this level to the actual selection.

The objectContribution element uses the core expression enablement, as defined in org.eclipse.core.expressions.definitions.

An action's enablement and/or visibility can be defined using the elements enablement and visibility respectively, if the extension point supports it. These two elements contain a boolean expression that is evaluated to determine the enablement and/or visibility.

The syntax is the same for the enablement and visibility elements. Both contain only one boolean expression sub-element. In the simplest case, this will be an objectClass, objectState, pluginState, or systemProperty element. In the more complex case, the and, or, and not elements can be combined to form a boolean expression. Both the and, and or elements must contain 2 sub-elements. The not element must contain only 1 sub-element.

Configuration Markup:

<!ELEMENT extension (objectContribution* , viewerContribution*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED

>


The objectContribution element is deprecated

<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false"

>

This element is used to define a group of actions and/or menus for any viewer context menus for which the objects of the specified type are selected. enablement in this element refers to core expression enablement, as defined in org.eclipse.core.expressions.definitions, and affects the enablement of the objectContribution not the contained actions.



The viewerContribution element is deprecated

<!ELEMENT viewerContribution (visibility? , menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED

>

This element is used to define a group of actions and/or menus for a specific view or editor part context menu.



The action element is deprecated

<!ELEMENT action (selection* , enablement? , class?)>

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     IDREF #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId IDREF #IMPLIED

tooltip          CDATA #IMPLIED

>

This element defines an action that the user can invoke in the UI.



The filter element is deprecated

<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED

>

This element is used to evaluate the attribute state of each object in the current selection. A match only if each object in the selection has the specified attribute state. Each object in the selection must implement, or adapt to, org.eclipse.ui.IActionFilter.



The parameter element is deprecated

<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED

>

A parameter element to be used within an IExecutableExtension element. This will be passed as initialization data to the instantiated class.



The class element is deprecated

<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #IMPLIED

>

The element version of the class attribute. This is used when the class implements org.eclipse.core.runtime.IExecutableExtension and there is parameterized data that you wish used in its initialization.



<!ELEMENT menu (separator* , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED

icon  CDATA #IMPLIED

>

This element is used to defined a new menu.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED

>

This element is used to create a menu separator in the new menu.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED

>

This element is used to create a named group in the new menu. It has no visual representation in the new menu, unlike the separator element.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED

>

This element is used to help determine the action enablement based on the current selection. Ignored if the enablement element is specified.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element is used to define the enablement for the extension.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element is used to define the visibility for the extension.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean AND operation on the result of evaluating its two sub-element expressions.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean OR operation on the result of evaluating its two sub-element expressions.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean NOT operation on the result of evaluating its sub-element expressions.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED

>

This element is used to evaluate the class or interface of each object in the current selection. If each object in the selection implements the specified class or interface, the expression is evaluated as true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED

>

This element is used to evaluate the attribute state of each object in the current selection. If each object in the selection has the specified attribute state, the expression is evaluated as true. To evaluate this type of expression, each object in the selection must implement, or adapt to, org.eclipse.ui.IActionFilter interface.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed"

>

This element is used to evaluate the state of a plug-in. The state of the plug-in may be one of the following: installed (equivalent to the OSGi concept of "resolved") or activated (equivalent to the OSGi concept of "active").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED

>

This element is used to evaluate the state of some system property. The property value is retrieved from the java.lang.System.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

A generic root element. The element can be used inside an extension point to define its enablement expression. The children of an enablement expression are combined using the "and" operator.



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate | reference)>

This element represents a NOT operation on the result of evaluating its sub-element expression.



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

This element represents an AND operation on the result of evaluating all its sub-elements expressions.



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

This element represent an OR operation on the result of evaluating all its sub-element expressions.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED

>

This element is used to perform an instanceof check of the object in focus. The expression returns EvaluationResult.TRUE if the object's type is a sub type of the type specified by the attribute value. Otherwise EvaluationResult.FALSE is returned.



<!ELEMENT test EMPTY>

<!ATTLIST test

property              CDATA #REQUIRED

args                  CDATA #IMPLIED

value                 CDATA #IMPLIED

forcePluginActivation (true | false)

>

This element is used to evaluate the property state of the object in focus. The set of testable properties can be extended using the org.eclipse.core.expressions.propertyTesters extension point. The test expression returns EvaluationResult.NOT_LOADED if the property tester doing the actual testing isn't loaded yet and the attribute forcePluginActivation is set to false. If forcePluginActivation is set to true and the evaluation context used to evaluate this expression support plug-in activation then evaluating the property will result in activating the plug-in defining the tester.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED

>

Tests a system property by calling the System.getProperty method and compares the result with the value specified through the value attribute.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED

>

This element is used to perform an equals check of the object in focus. The expression returns EvaluationResult.TRUE if the object is equal to the value provided by the attribute value. Otherwise EvaluationResult.FALSE is returned.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED

>

This element is used to test the number of elements in a collection.



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

<!ATTLIST with

variable CDATA #REQUIRED

>

This element changes the object to be inspected for all its child element to the object referenced by the given variable. If the variable can not be resolved then the expression will throw an ExpressionException when evaluating it. The children of a with expression are combined using the "and" operator.



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED

>

This element changes the object to be inspected for all its child element to the object referenced by the given variable. If the variable can not be resolved then the expression will throw an ExpressionException when evaluating it. The children of a resolve expression are combined using the "and" operator.



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

<!ATTLIST adapt

type CDATA #REQUIRED

>

This element is used to adapt the object in focus to the type specified by the attribute type. The expression returns EvaluationResult.NOT_LOADED if either the adapter or the type referenced isn't loaded yet. It throws an ExpressionException during evaluation if the type name doesn't exist at all. The children of an adapt expression are combined using the "and" operator.



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

<!ATTLIST iterate

operator (or|and)

ifEmpty  (true | false)

>

This element is used to iterate over a variable that is of type java.util.Collection, or a variable that adapts to org.eclipse.core.expressions.IIterable. If the object in focus is not one of the above then a CoreException with an ExpressionStatus will be thrown while evaluating the expression. The child expressions of an iterate expression are combined using the "and" operator.



<!ELEMENT reference EMPTY>

<!ATTLIST reference

definitionId IDREF #REQUIRED

>

This element is used to reference an expression from the org.eclipse.core.expressions.definitions extension point. The expression definition will be evaluated within the current expression element using the current evaluation context.



Examples:
The following is an example of a pop-up menu extension point:


   <extension point="org.eclipse.ui.popupMenus"> 
      <objectContribution 
         id="com.xyz.C1" 
         objectClass="org.eclipse.core.resources.IFile" 
         nameFilter="*.java"> 
         <menu
            id="com.xyz.xyzMenu" 
            path="additions" 
            label="&amp;XYZ Java Tools"> 
            <separator name="group1"/> 
         </menu> 
         <action
            id="com.xyz.runXYZ" 
            label="&amp;Run XYZ Tool"
            style="push"
            menubarPath="com.xyz.xyzMenu/group1" 
            icon="icons/runXYZ.gif" 
            helpContextId="com.xyz.run_action_context" 
            class="com.xyz.actions.XYZToolActionDelegate" 
            enablesFor="1" /> 
      </objectContribution> 
      <viewerContribution 
         id="com.xyz.C2" 
         targetID="org.eclipse.ui.views.TaskList"> 
         <action
            id="com.xyz.showXYZ" 
            label="&amp;Show XYZ"
            style="toggle"
            state="true"
            menubarPath="additions" 
            icon="icons/showXYZ.gif" 
            helpContextId="com.xyz.show_action_context" 
            class="com.xyz.actions.XYZShowActionDelegate" /> 
      </viewerContribution> 
   </extension> 

In the example above, the specified object contribution action will only enable for a single selection (enablesFor attribute). In addition, each object in the selection must implement the specified interface (IFile) and must be a Java file. This action will be added into a submenu previously created. This contribution will be effective in any view that has the required selection.

In contrast, the viewer contribution above will only appear in the Tasks view context menu, and will not be affected by the selection in the view.

The following is an example of the filter mechanism. In this case the action will only appear for IMarkers which are completed and have high priority.


   <extension point="org.eclipse.ui.popupMenus"> 
      <objectContribution 
         id="com.xyz.C3" 
         objectClass="org.eclipse.core.resources.IMarker"> 
         <filter name="done" value="true"/> 
         <filter name="priority" value="2"/> 
         <action
            id="com.xyz.runXYZ" 
            label="High Priority Completed Action Tool" 
            icon="icons/runXYZ.gif" 
            class="com.xyz.actions.MarkerActionDelegate"> 
         </action> 
      </objectContribution> 
   </extension> 

The following is an other example of using the visibility element:


   <extension point="org.eclipse.ui.popupMenus"> 
      <viewerContribution 
         id="com.xyz.C4" 
         targetID="org.eclipse.ui.views.TaskList">
         <visibility>
            <and>
               <pluginState id="com.xyz" value="activated"/>
               <systemProperty name="ADVANCED_MODE" value="true"/>
            </and>
         </visibility>
         <action
            id="com.xyz.showXYZ" 
            label="&amp;Show XYZ"
            style="push"
            menubarPath="additions" 
            icon="icons/showXYZ.gif" 
            helpContextId="com.xyz.show_action_context" 
            class="com.xyz.actions.XYZShowActionDelegate"> 
         </action> 
      </viewerContribution> 
   </extension> 

In the example above, the specified action will appear as a menu item in the Task view context menu, but only if the "com.xyz" plug-in is active and the specified system property is set to true.

API Information:
The value of the action attribute class must be a fully qualified class name of a Java class that implements org.eclipse.ui.IObjectActionDelegate in the case of object contributions, org.eclipse.ui.IViewActionDelegate for contributions to context menus that belong to views, or org.eclipse.ui.IEditorActionDelegate for contributions to context menus that belong to editors. In all cases, the implementing class is loaded as late as possible to avoid loading the entire plug-in before it is really needed.

Note: For backwards compatibility, org.eclipse.ui.IActionDelegate may be implemented for object contributions.

Conext menu extension within a part is only possible when the target part publishes a menu for extension. This is strongly encouraged, as it improves the extensibility of the product. To accomplish this each part should publish any context menus which are defined by calling IWorkbenchPartSite.registerContextMenu. Once this has been done the workbench will automatically insert any action extensions which exist.

A menu id must be provided for each registered menu. For consistency across parts the following strategy should be adopted by all part implementors.

Any context menu which is registered with the workbench also should contain a standard insertion point with id IWorkbenchActionConstants.MB_ADDITIONS. Other plug-ins will use this value as a reference point for insertion. The insertion point may be defined by adding a GroupMarker to the menu at an appropriate location for insertion.

An object in the workbench which is the selection in a context menu may define an org.eclipse.ui.IActionFilter. This is a filtering strategy which can perform type specific filtering. The workbench will retrieve the filter for the selection by testing to see if it implements IActionFilter. If that fails, the workbench will ask for a filter through the IAdaptable mechanism.

Action and menu labels may contain special characters that encode mnemonics which are specified using the ampersand ('&') character in front of a selected character in the translated text. Since ampersand is not allowed in XML strings, use &amp; character entity.

If two or more actions are contributed to a menu by a single extension the actions will appear in the reverse order of how they are listed in the plugin.xml file. This behavior is admittedly unintuitive. However, it was discovered after the Eclipse Platform API was frozen. Changing the behavior now would break every plug-in which relies upon the existing behavior.

The selection and enablement elements are mutually exclusive. The enablement element can replace the selection element using the sub-elements objectClass and objectState. For example, the following:


 <selection
  class="org.eclipse.core.resources.IFile"
  name="*.java">
 </selection>
can be expressed using:

 <enablement>
  <and>
   <objectClass name="org.eclipse.core.resources.IFile"/>
   <objectState name="extension" value="java"/>
  </and>
 </enablement>

Supplied Implementation:
The workbench views have built-in context menus that already come loaded with a number of actions. Plug-ins can contribute to these menus. If a viewer has reserved slots for these contributions and they are made public, slot names can be used as paths. Otherwise, actions and submenus will be added at the end of the pop-up menu.


Copyright (c) 2000, 2007 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html