Expressions

Description: Boolean expressions are used to define the visibility and enablement for many action extensions within the workbench. For instance, an enablement element can be defined within any action extension. This element contains a boolean expression defining the enablement criteria for the action. A visibility element can be defined for a popup menu action extension. This element contains a boolean expression defining the visibility criteria for the action.

Regardless of where the boolean expression is found, the syntax of the expression will follow the same form. The root element for enablement and visibility must contain one sub element. In the simplest case, this will consist of an objectClass, objectState, systemProperty, or pluginState element. In the more complex case, and, or, not elements can be combined to form a boolean expression. An and or or element may contain 1 or more sub elements. A not element must contain only 1 sub element.

An objectClass element is used to evaluate the class of each object in the selection. The name attribute of the objectClass contains a fully qualified class name. If each object in the selection implements this class, the expression is evaluated as true.

An objectState element is used to evaluate the state of each object in the selection. In most situations, the enablement or visibility of an action can be determined by selection type. In other situations this is not enough, and enablement or visibility must be determined using the selection state. For instance, you may contribute an action for all objects of type IFile which are read only. This read only criteria can only be declared by specifying an objectState element. It may have the following form ..

<objectState name="readOnly" value="true"/>

In the workbench, the evaluation of this expression is very difficult to accomplish, because the attributes of an object are type specific, and beyond the domain of the workbench itself. So the workbench will collaborate with the objects in the selection to evaluate the expression. This is done using an IActionFilter, an evaluation strategy for objectState elements. When an objectState element is evaluated, the workbench ask each object in the selection for an IActionFilter. It does this by testing to see if it implements IActionFilter. If that fails, the workbench will ask for a filter through through the IAdaptable mechanism. If a filter is found, the workbench will pass the objectState attributes to the filter to determine if they match the state of the selected object. If so, the term is evaluated as true. If there is no action filter, or there is no match, the term is evaluated as false.

Views and editors are encouraged to define an IActionFilter for each object in their selection. This makes it easier for other plugin developers to extend those views or editors with new, well qualified actions.

A systemProperty element is used to evaluate the state of some system property. Under the covers, the value of the system property is determined by invoking System.getProperty.

A pluginState element is used to evaluate the state of a plugin. The state of the plugin may be installed or activated.

Since: Release 2.0

Configuration Markup:

   <!ELEMENT objectClass EMPTY>
   <!ATTLIST objectClass
      name       CDATA #REQUIRED
   >

name - a fully qualified name of a class. The expression is evaluated as true only if the selection implement this class.

   <!ELEMENT objectState EMPTY>
   <!ATTLIST objectState
      name       CDATA #REQUIRED
      value      CDATA #REQUIRED
   >

name - the name of an object attribute. Acceptable values for this string reflect the object type, and should be publicly declared by the plugin where the object type is declared.
value - the required value of the object attribute. The acceptable values for the object attribute should be publicly declared.

   <!ELEMENT systemProperty EMPTY>
   <!ATTLIST systemProperty
      name       CDATA #REQUIRED
      value      CDATA #REQUIRED
   >

name - the name of the system property.
value - the required value of the system property.

   <!ELEMENT pluginState EMPTY>
   <!ATTLIST pluginState
      id         CDATA #REQUIRED
      value      (installed | activated)
   >

id - an id of a plugin which may or may not be registered in the plug-in registry.

value - the required state of the plugin. Currently two states are supported: installed and activated.

Examples:

The following is an example of an action set which uses the enablement element. The action set declares a menu with the label List Element, and then populates it with actions which are enabled by a selection of ListElements with various state. A ListElement has two attributes: name (a string) and flag (a boolean). In this example, the All action () is enabled whenever a ListElement is selected. The Red action () is enabled when a ListElement with name = red is selected. And the Not Red action () is enabled when a ListElement with name != red is selected.

<extension point = "org.eclipse.ui.actionSets">
    <actionSet id="org.eclipse.ui.tests.internal.ListElementActions"
        label="List Element">
        <menu id="org.eclipse.ui.tests.internal.ListElementMenu"
            label="List Element"
            path="additions">
            <separator name="group1"/>
        </menu>
     <action id="org.eclipse.ui.tests.internal.ac1"
            label="All"
            menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
            class="org.eclipse.ui.tests.api.MockActionDelegate"
            enablesFor="1">
            <enablement>
                 <objectClass name="org.eclipse.ui.tests.api.ListElement"/>
            </enablement>
        </action>
     <action id="org.eclipse.ui.tests.internal.ac2"
            label="Red"
            menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
            class="org.eclipse.ui.tests.api.MockActionDelegate"
            enablesFor="1">
            <enablement>
             <and>
              <objectClass name="org.eclipse.ui.tests.api.ListElement"/>
              <objectState name="name" value="red"/>
             </and>
            </enablement>
        </action>
     <action id="org.eclipse.ui.tests.internal.ac3"
            label="Not Red"
            menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
            class="org.eclipse.ui.tests.api.MockActionDelegate"
            enablesFor="1">
            <enablement>
             <and>
              <objectClass name="org.eclipse.ui.tests.api.ListElement"/>
               <not>
               <objectState name="name" value="red"/>
              </not>
          </and>
            </enablement>
        </action>
    </actionSet>
</extension>

In the next example the pluginState element is used to control the enablement of actions in an action set. The Installed action (

) is enabled when the plugin with x.y.z.myPlugin is installed. The Activated action (

) is enabled when the same plugin has been activated.

<extension point = "org.eclipse.ui.actionSets">
    <actionSet id="org.eclipse.ui.tests.internal.ListElementActions"
        label="List Element">
        <menu id="org.eclipse.ui.tests.internal.ListElementMenu"
            label="List Element"
            path="additions">
            <separator name="group1"/>
        </menu>
     <action id="org.eclipse.ui.tests.internal.ac8"
            label="Installed"
            menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
            class="org.eclipse.ui.tests.api.MockActionDelegate">
            <enablement>
             <pluginState id="x.y.z.myPlugin" value="installed"/>
            </enablement>
        </action>
     <action id="org.eclipse.ui.tests.internal.ac10"
            label="Activated"
            menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
            class="org.eclipse.ui.tests.api.MockActionDelegate">
            <enablement>
             <pluginState id="x.y.z.myPlugin" value="activated"/>
            </enablement>
        </action>
    </actionSet>
</extension>

In the next example the systemProperty element is demonstrated. The System Property action (

) is enabled when the ActionExpressionVar system property is equal to "bubba".

<extension point = "org.eclipse.ui.actionSets">
    <actionSet id="org.eclipse.ui.tests.internal.ListElementActions"
        label="List Element">
        <menu id="org.eclipse.ui.tests.internal.ListElementMenu"
            label="List Element"
            path="additions">
            <separator name="group1"/>
        </menu>
     <action id="org.eclipse.ui.tests.internal.ac11"
            label="System Property"
            menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
            class="org.eclipse.ui.tests.api.MockActionDelegate">
            <enablement>
             <systemProperty name="ActionExpressionVar" value="bubba"/>
            </enablement>
        </action>
    </actionSet>
</extension>

Here is one final example, which demonstrates the declaration of visibility for a popup menu action extension. The Red and True action is visible whenever a ListElement is selected with name = red and flag = true.

<extension point="org.eclipse.ui.popupMenus">
    <objectContribution id="oc6"
      objectClass="org.eclipse.ui.tests.api.ListElement">
      <visibility>
         <and>
             <objectState name="name" value="red"/>
             <objectState name="flag" value="true"/>
         </and>
      </visibility>
      <action id="oc4" label="Red And True"
           class="org.eclipse.ui.tests.api.MockActionDelegate"/>
    </objectContribution>
</extension>

Supplied Implementation: For convenience, action filters have been defined for markers, resources, and projects. The name-value pairs for each are declared on IMarkerActionFilter, IResourceActionFilter, and IProjectActionFilter.