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.
An action's enablement and/or visibility can be defined using the elements enablement and visibility respectively. 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.
<!ELEMENT extension (objectContribution* , viewerContribution*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!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.
<!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.
<!ELEMENT action (selection* , enablement? , class?)>
<!ATTLIST action
id CDATA #REQUIRED
label CDATA #REQUIRED
definitionId IDREF #IMPLIED
menubarPath CDATA #IMPLIED
icon 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.
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. |
! | - 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.
<!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.
<!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.
<!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.
org.eclipse.core.runtime.IExecutableExtension
.<!ELEMENT menu (separator* , groupMarker*)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #REQUIRED
path 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 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.
<!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.
<!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 a 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 a ExpressionException when evaluating it. The children of a with 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 not loaded if either the adapter or the type referenced isn't loaded yet. It throws a 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. If the object in focus is not of type java.util.Collection then an ExpressionException will be thrown while evaluating the expression.
<!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.
<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="&XYZ Java Tools"> <separator name="group1"/> </menu> <action id="com.xyz.runXYZ" label="&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="&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="&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.
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