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 to make an action visible or enabled.

Boolean expressions

The boolean expressions can contain simple boolean operators (NOT, AND, OR) and predefined expressions that can evaluate the following conditions:

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

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.

Legal notices.