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 for more flexibility in determining when an action should be visible or enabled.
Boolean expressions can contain the boolean operators (NOT, AND, OR) combined with a predefined syntax for evaluating certain conditions. Many of these conditions test a particular object. The identity of the "object in focus" (the object being tested) depends upon the specific context of the enablement expression:
When specifying a value to be tested against any of these expressions, the value is assumed to be a string except for when the following conversions are successful:
A complete definition of enablement XML syntax can be found in the extension point reference documentation for any extension that defines an enablement element, such as org.eclipse.ui.popupMenus.
Prior to R3.0, these generalized boolean expressions were not available. The following predefined expressions were used to evaluate certain conditions without building a general expression. Note that any of these expressions could now be expressed with the more generalized syntax. The predefined expressions can still be used as follows:
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 plug-in (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 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.