When a plug-in contributes an action to the workbench UI using one of the menu extension points, it can specify the conditions under which the menu item is visible and/or enabled in the menu. In addition to supplying simple enabling conditions, such as selection counts and selection classes, plug-ins can use boolean expressions to make an action visible or enabled.
The boolean expressions can contain simple boolean operators (NOT, AND, OR) and predefined expressions that can evaluate the following conditions:
objectClass - true if each object in the selection subclasses or implements the class.
objectState - true if the named attribute equals the specified value. IActionFilter assists in evaluating the expression. An action filter dynamically computes the enablement criteria for an action based on the target selection and the value of named attributes.
systemProperty - true if the named system property equals the specified value.
pluginState - specifies whether the specified plugin (by id) should be installed or activated
For example, the following snippets represent enablement expressions that could be used on a hypothetical action in an action set:
<action id="org.eclipse.examples.actionEnablement.class" label="Red Element" menubarPath="additions" class="org.eclipse.examples.actionEnablement.ObjectTestAction"> <enablement> <and> <objectClass name="org.eclipse.examples.actionEnablement.TestElement"/> <objectState name="name" value="red"/> </and> </enablement> </action>
<action id="org.eclipse.examples.actionEnablement.property" label="Property" menubarPath="additions" class="org.eclipse.examples.actionEnablement.PropertyTestAction"> <enablement> <systemProperty name="MyTestProperty" value="puppy"/> </enablement> </action>
<action id="org.eclipse.examples.actionEnablement.pluginState" label="Installed" menubarPath="additions" class="org.eclipse.examples.actionEnablement.PluginTestAction"> <enablement> <pluginState id="x.y.z.anotherPlugin" value="installed"/> </enablement> </action>
See the reference documentation of the extension points below for more elaborate samples of these expressions and a complete description of the XML.
The following table lists extension points that contribute actions and summarizes how XML markup attributes and boolean expressions can be used to affect enablement.
Extension point name |
Attributes affecting enablement |
Boolean expressions |
---|---|---|
enablesFor - specifies the selection count that must be met for the action to be enabled selection class - the class that the selected objects must subclass or implement in order for the action to be enabled selection name - a wild card filter that can be applied to the objects in the selection. |
visibility - a boolean expression. Controls whether the menu item is visible in the menu. enablement - a boolean expression. Controls whether the menu item is enabled in the menu. The enablesFor attribute and the selection class and name, and must be satisfied before applying the enablement expression. |
|
(For object contributions only.) objectClass - specifies the class that objects in the selection must subclass or implement (For both object and viewer contributions) enablesFor - specifies the selection count that must be met for the action to be enabled selection class - the class that the selected objects must subclass or implement to enable the action selection name - a wild card filter that can be applied to the objects in the selection.
|
(For both object and viewer contributions) visibility - a boolean expression. Controls whether the menu item is visible in the menu. enablement - a boolean expression. Controls whether the menu item is enabled in the menu. The enablesFor attribute and the selection class and name, and must be satisfied before applying the enablement expression. |
The ability to define content types (see Content types) can be combined
with boolean expressions to define very specific enablement or visibility conditions based on
the content type of a resource. For example, the following snippet makes a popup menu item visible only if the
selected file's content matches the plug-in's specialized content types.
<extension point="org.eclipse.ui.popupMenus">
<objectContribution
id="com.example.objectContributions"
objectClass="org.eclipse.core.resources.IFile"
nameFilter="*.xml">
<visibility>
<or>
<objectState
name="contentTypeId"
value="com.example.employeeRecordContentType"/>
<objectState
name="contentTypeId"
value="com.example.customerRecordContentType"/>
</or>
</visibility>
<action id="com.example.action1"
...
The contentTypeId attribute can be used in an objectState expression to check the content type of
the selected xml file. This allows a plug-in to apply very specific content checking before enabling or showing
menu actions related to specific types of files. See Content types for more detail
about the content type extension.