Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

---

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.