Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

Platform Plug-in Developer Guide Reference Extension Points Reference

Pop-up Menus

Identifier:

org.eclipse.ui.popupMenus

Description:

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 view or editor part context menu, 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

point - a fully qualified identifier of the target extension point
id - an optional identifier of the extension instance
name - an optional name of the extension instance

<!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 effects the enablement of the objectContribution not the contained actions.

id - a unique identifier used to reference this contribution
objectClass - a fully qualified name of the class or interface that all objects in the selection must subclass or implement.
nameFilter - an optional wild card filter for the name that can be applied to all objects in the selection. No contribution will take place if there is no match.
adaptable - a flag that indicates if types that adapt to IResource should use this object contribution. This flag is used only if objectClass adapts to IResource. Default value is false.

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

id - a unique identifier used to reference this contribution
targetID - the unique identifier of a context menu inside a view or editor part.

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

id - a unique identifier used as a reference for this action.
label - a translatable name used as the menu item text. The name can include mnenomic information.
definitionId - This specifies the command that this action is handling. This is used to decide which key binding to display in the pop-up menu.
menubarPath - a slash-delimited path ('/') used to specify the location of this action in the context menu. Each token in the path, except the last one, must represent a valid identifier of an existing menu in the hierarchy. The last token represents the named group into which this action will be added. If the path is omitted, this action will be added to the standard additions group defined by IWorkbenchActionConstants.MB_ADDITIONS.
icon - a relative path of an icon used to visually represent the action in its context. The path is relative to the location of the plugin.xml file of the contributing plug-in.
helpContextId - a unique identifier indicating the help context for this action. On some platforms, if the action appears as a menu item, then pressing the appropriate help key while the menu item is highlighted will display help. Not all platforms support this behaviour.

style - an optional attribute to define the user interface style type for the action. If defined, the attribute value will be one of the following:

	push	- as a regular menu item or tool item.
	radio	- as a radio style menu item or tool item. Actions with the radio style within the same menu or toolbar group behave as a radio set. The initial value is specified by the `state` attribute.
	toggle	- as a checked style menu item or as a toggle tool item. The initial value is specified by the `state` attribute.
	pulldown	- as a cascading style menu item.

state - an optional attribute indicating the initial state (either true or false), used when the style attribute has the value radio or toggle.
class - a name of the fully qualified class that implements org.eclipse.ui.IObjectActionDelegate (for object contributions), org.eclipse.ui.IViewActionDelegate (for viewer contributions to a view part), or org.eclipse.ui.IEditorActionDelegate (for viewer contributions to an editor part). For backwards compatibility, org.eclipse.ui.IActionDelegate may be implemented for object contributions.

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 items selected. The following attribute formats are supported:

	!	- 0 items selected
	?	- 0 or 1 items selected
	+	- 1 or more items selected
	multiple, 2+	- 2 or more items selected
	n	- a precise number of items selected.a precise number of items selected. For example: enablesFor=" 4" enables the action only when 4 items are selected
	*	- any number of items selected

The enablement criteria for an action extension are initially defined by enablesFor, selection and enablement. However, once the action delegate has been instantiated it may control the action enable state directly within its selectionChanged method.

overrideActionId - an optional attribute that specifies the identifier of an action which this action overrides. The action represented by this identifier will not be contributed to the context menu. The action identifier must be from a prerequisite plug-in only. This attribute is only applicable to action elements of an object contribution.
tooltip - a translatable text representing the action's tool tip. Only used if the action appears in the toolbar.

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

name - the name of an object's attribute. Acceptable names reflect the object type, and should be publicly declared by the plug-in where the object type is declared.
value - the required value of the object's attribute. The acceptable values for the object's attribute should be publicly declared.

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

name - the parameter name
value - the parameter value

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

class - A class that implements one of the interfaces listed for the class attribute. It may also implement org.eclipse.core.runtime.IExecutableExtension.

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

id - a unique identifier that can be used to reference this menu.
label - a translatable name used by the Workbench for this new menu. The name should include mnemonic information.
path - the location of the new menu starting from the root of the menu. Each token in the path must refer to an existing menu, except the last token which should represent a named group in the last menu in the path. If omitted, the new menu will be added to the additions named group of the menu.
icon - a relative path of an icon used to visually represent the menu in its context. The path is relative to the location of the plugin.xml file of the contributing plug-in.

<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED

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

name - the name of the menu separator. This name can later be referenced as the last token in a menu path. Therefore, a separator also serves as named group into which actions and menus can be added.

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

name - the name of the group marker. This name can later be referenced as the last token in the menu path. It serves as named group into which actions and menus can be added.

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

class - a fully qualified name of the class or interface that each object in the selection must implement in order to enable the action.
name - an optional wild card filter for the name that can be applied to all objects in the selection. If specified and the match fails, the action will be disabled.

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

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

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

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

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.

name - a fully qualified name of a class or interface. The expression is evaluated as true only if all objects within the selection implement this class or interface.

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

name - the name of an object's attribute. Acceptable names reflect the object type, and should be publicly declared by the plug-in where the object type is declared. @see IResourceActionFilter for a list of the supported constants
value - the required value of the object's attribute. The acceptable values for the object's attribute should be publicly declared.

<!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").

id - the identifier of a plug-in which may or may not exist in the plug-in registry.
value - the required state of the 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.

name - the name of the system property.
value - the required value of the system property.

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

This element represent a NOT operation on the result of evaluating it's sub-element expression.

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

This element represent an AND operation on the result of evaluating all it's 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 it's 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.

value - a fully qualified name of a class or interface.

<!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 propery tester 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.

property - the name of an object's property to test.
args - additional arguments passed to the property tester. Multiple arguments are separated by commas. Each individual argument is converted into a Java base type using the same rules as defined for the value attribute of the test expression.
value - the expected value of the property. Can be omitted if the property is a boolean property. The test expression is supposed to return EvaluationResult.TRUE if the property matches the value and EvaluationResult.FALSE otherwise. The value attribute is converted into a Java base type using the following rules:
- the string "true" is converted into Boolean.TRUE
- the string "false" is converted into Boolean.FALSE
- if the string contains a dot then the interpreter tries to convert the value into a Float object. If this fails the string is treated as a java.lang.String
- if the string only consists of numbers then the interpreter converts the value in an Integer object.
- in all other cases the string is treated as a java.lang.String
- the conversion of the string into a Boolean, Float, or Integer can be suppressed by surrounding the string with single quotes. For example, the attribute value="'true'" is converted into the string "true"
forcePluginActivation - a flag indicating whether the plug-in contributing the property tester should be loaded if necessary. As such, this flag should be used judiciously, in order to avoid unnecessary plug-in activations. Most clients should avoid setting this flag to true. This flag is only honored if the evaluation context used to evaluate this expression allows plug-in activation. Otherwise the flag is ignored and no plug-in loading takes place.

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

property - the name of an system property to test.
value - the expected value of the property. The value is interpreted as a string value.

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

value - the expected value. The value provided as a string is converted into a Java base type using the same rules as for the value attribute of the test expression.

<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED

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

value - an expression to specify the number of elements in a list. Following wildcard characters can be used:

*

any number of elements

?

no elements or one element

+

one or more elements

!

no elements

-N)

less than N elements

(N-

greater than N elements

integer value

the list must contain the exact number of elements

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

variable - the name of the variable to be used for further inspection. It is up to the evaluator of an extension point to provide the variable in the variable pool.

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

variable - the name of the variable to be resolved. This variable is then used as the object in focus for child element evaluation. It is up to the evaluator of an extension point to provide a corresponding variable resolver (see IVariableResolver) through the evaluation context passed to the root expression element when evaluating the expression.
args - additional arguments passed to the variable resolver. Multiple arguments are separated by commas. Each individual argument is converted into a Java base type using the same rules as defined for the value attribute of the test expression.

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

type - the type to which the object in focus is to be adapted.

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

operator - either "and" or "or". The operator defines how the results of all the child expressions applied to each child of the Collection or IIterable will be combined and what (if any) short circuit evaluation will be used. If not specified, "and" will be used.
ifEmpty - the value return from the iterate expression if the collection is empty. If not specified then true is returned when the operator equals "and" and false is return if the operator equals "or".

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

definitionId - The unique id of an expression from org.eclipse.core.expressions.definitions.

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.

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 https://www.eclipse.org/legal/epl-v10.html