Workbench Core Expressions

The workbench uses core expressions (See org.eclipse.core.expressions.definitions for a description) for enabledWhen and activeWhen for handlers, programmatic activation of contexts, and for visibleWhen for menu contributions. Core expressions are also used as conditionals for certain property page contribution and object contribution expressions, using the enablement element. In most cases, the workbench provides the IEvaluationContext that command core expressions are evaluate against.

The IEvaluationService provides methods that allow other clients and extension point builders to hook into the workbench core expressions.

Using Core Expressions in the Workbench

Core expressions are used declaratively in the plugin.xml files, and programmatically with some of the services provided in the workbench.

Note: Elements from workbench extension points that use core expressions, like enabledWhen, take one child core expression element. They do not and their elements together.

Declarative Expression Examples

1. Basic IStructuredSelection
2. IResources and the Package or Project Explorer
3. Active Contexts
4. Active Views and Editor
5. ActionSets and Contexts

Basic IStructuredSelection

Most of the tree or table like viewers return an IStructuredSelection. For example, the Project Explorer and Package Explorer.

When using the default variable you must treat it as an java.util.Collection. That means using <count> or <iterate>. The expression below returns true if all of the selected items are Person.

<enabledWhen>
    <iterate ifEmpty="false">
        <instanceof value="org.eclipse.ui.examples.contributions.model.Person"/>
    </iterate>
</enabledWhen>

This is equivalent to:

<enabledWhen>
    <with variable="selection">
        <iterate ifEmpty="false">
            <instanceof value="org.eclipse.ui.examples.contributions.model.Person"/>
        </iterate>
    </with>
</enabledWhen>

The behaviour of iterate is:

• iterate ands the results of evaluating its child expressions for each element in the collection, unless you set the operator attribute.
• iterate has the same semantics for its children as <and>
• iterate with an operator of and returns true if the collection is empty, unless you set the ifEmpty attribute.

If you want to be enabled if only one Person is selected, you can include a count element.

<enabledWhen>
    <with variable="selection">
        <count value="1"/>
        <iterate ifEmpty="false">
            <instanceof value="org.eclipse.ui.examples.contributions.model.Person"/>
        </iterate>
    </with>
</enabledWhen>

The same expression using the default variable:

<enabledWhen>
    <and>
        <count value="1"/>
        <iterate ifEmpty="false">
            <instanceof value="org.eclipse.ui.examples.contributions.model.Person"/>
        </iterate>
    </and>
</enabledWhen>

IResources and the Package or Project Explorer

The Package Explorer is a mixture of org.eclipse.core.resources.IResource, org.eclipse.jdt.core.IJavaElement and other classes. If you are trying to find all of the "*.java" files, you would need to:

1. Iterate through the default variable.
2. Adapt the selection elements to your class, in this case org.eclipse.core.resources.IResource.
3. Use one of the org.eclipse.core.resources property testers to test the org.eclipse.core.resources.IResource property.

<enabledWhen>
    <with variable="selection">
        <iterate ifEmpty="false">
            <adapt type="org.eclipse.core.resources.IResource">
                <test property="org.eclipse.core.resources.name"
                         value="*.java"/>
            </adapt>
        </iterate>
    </with>
</enabledWhen>

When working with the current selection and property testers it does not always make sense to use adapt. In these situations it is a good practice to check that the object under test is a valid type for that property tester:

<enabledWhen>
    <with variable="selection">
        <iterate ifEmpty="false">
            <instanceof type="org.eclipse.core.resources.IResource"/>
            <test property="org.eclipse.core.resources.name"
                     value="*.java"/>
        </iterate>
    </with>
</enabledWhen>

Active Contexts

If your handler should be enabled when your view or editor activates a context, you can use the activeContexts variable. Contexts are defined in the org.eclipse.ui.contexts extension point and activated programmatically using the org.eclipse.ui.contexts.IContextService.

<enabledWhen>
    <with variable="activeContexts">
        <iterate ifEmpty="false" operator="or">
            <equals value="org.example.view.context"/>
        </iterate>
    </with>
</enabledWhen>

Active Views and Editor

For handlers that are to be contributed to a specific view or editor, you can use activeEditorId and activePartId in the activeWhen clause. This is an example for a handler that should be active in text editors:

<activeWhen>
    <with variable="activeEditorId">
        <equals value="org.eclipse.ui.DefaultTextEditor"/>
    </with>
</activeWhen>

The following clause is for a handler that's active while in the Project Explorer:

<activeWhen>
    <with variable="activePartId">
        <equals value="org.eclipse.ui.navigator.ProjectExplorer"/>
    </with>
</activeWhen>

ActionSets and Contexts

As of 3.3 all org.eclipse.ui.actionSets (Deprecated) generate a context with a parent of org.eclipse.ui.contexts.actionSet. Contexts with this parent are filtered from the General > Keys preference page.

Showing an actionSet activates the matching context. This allows contributed commands to "join" actionSets, like the debug launch actionSet.

<enabledWhen>
    <with variable="activeContexts">
        <iterate ifEmpty="false" operator="or">
            <equals value="org.eclipse.debug.ui.launchActionSet"/>
        </iterate>
    </with>
</enabledWhen>

Note: commands that are enabled or visible with actionSets are not currently displayed in the Customize Perspective Dialog.

Variables Provided in the Workbench

The IEvaluationService provides the global selection as the default variable (in a java.util.Collection) for expression evaluation. It can either be empty, have one entry (if the ISelection was something like an ITextSelection), or have the contents of an IStructuredSelection.

The workbench publishes variables in ISources that can be used in the <with/> element and can be retrieved from the IEvaluationContext. Some of the variables may not be set, depending on the current application context when they are evaluated. The following table explains some of the more commonly used ones:

Property Testers Provided in the Workbench

The workbench provides a couple of property testers that can be used in core expressions. The expression defines a property attribute and then takes a combination of 'args' and a 'value' that is tester implementation dependent. The property attribute is the combination of the namespace and property name. For example, to test an IResource name the property would be org.eclipse.core.resources.name.