Boolean expressions and action filters
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 enablement expressions
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:
-
instanceof tests whether the type of the object in focus is a subtype of the specified type name.
-
test tests whether the value of a named property of the object in focus matches the specified value.
-
systemTest tests whether the value of a named system property matches the specified value.
-
equals tests whether the object in focus is equal to the specified value.
-
count tests the number of elements in a list.
-
with changes the object in focus to the object referenced by a supplied variable.
-
resolve changes the object in focus to the object referenced by a supplied variable, supplying additional
arguments with the variable.
-
adapt adapts the object in focus to the type specified.
-
iterate iterates over a variable that is a collection and combines the boolean value of each value using AND or OR.
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:
- the string "true" is converted into Boolean.TRUE
- the string "false" is converted into Boolean.FALSE
- if the string contains a dot, the interpreter tries to convert the value into a Float object
- if the string only consists of numbers, the interpreter converts the value into an Integer object
- the conversion into a Boolean, Float, or Integer can be suppressed by surrounding the string with single quotes.
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
|
viewActions
,
editorActions
,
actionSets
|
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.
|
popupMenus
|
(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.
|
Using objectState with content types
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.