View source for Command Core Expressions

Core expressions are declarative or programmatic expressions based on the org.eclipse.core.expressions plugin.

= Expressions and the Command Framework =

The [[Platform Command Framework]] uses [[Platform Expression Framework|core expressions]] for enabledWhen and activeWhen for handlers, programmatic activation of contexts, and for visibleWhen for menu contributions.  The command framework provides the IEvaluationContext that command core expressions are evaluate against.

The IEvaluationContext provides a default variable for evaluations, and a number of named variables.  In the command framework, we provide the global selection as a <code>java.util.Collection</code> as the default variable.  It can either be empty, have one entry (if the ISelection was something like an ITextSelection), or have the contents of an IStructuredSelection.

The &lt;with/&gt; element can be used to change which variable the child expression elements are evaluating against.

= Variables and the Command Framework =

The variables used for command framework evaluation are listed in [https://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/bundles/org.eclipse.ui.workbench/Eclipse%20UI/org/eclipse/ui/ISources.java ISources.java]

Some of the variables may not be set, depending on the current application context when they are evaluated.

<table border="1">
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Since</th>
</tr>

<tr>
<td>activeContexts</td>
<td>A <code>java.util.Collection</code> of <code>java.lang.String</code></td>
<td>
This is a collection of the active context IDs as strings.  Most commonly used with &lt;iterate/&gt;, &lt;count/&gt;, and &lt;test/&gt; with a combined <code>org.eclipse.common.expressions.PropertyTester</code>.  In '''3.3''' action sets are mirrored by contexts whose parent is <code>org.eclipse.ui.actionSet</code>, and the active action sets show up in the list of active contexts.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activeActionSets</td>
<td>An <code>IActionSetDescriptor[]</code></td>
<td>
'''Note:''' This is currently not used as it points to an internal class and the type might change in any release.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activeShell</td>
<td><code>org.eclipse.swt.widgets.Shell</code></td>
<td>
The currently active shell.  It can be a dialog or workbench window shell.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activeWorkbenchWindowShell</td>
<td><code>org.eclipse.swt.widgets.Shell</code></td>
<td>
The active workbench window shell.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activeWorkbenchWindow</td>
<td><code>org.eclipse.ui.IWorkbenchWindow</code></td>
<td>
The active workbench window.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activeWorkbenchWindow.isCoolbarVisible</td>
<td><code>java.lang.Boolean</code></td>
<td>
Reports coolbar visibility for the currently active workbench window.
</td>
<td>3.3</td>
</tr>

<tr>
<td>activeWorkbenchWindow.isPerspectiveBarVisible</td>
<td><code>java.lang.Boolean</code></td>
<td>
Reports perspective bar visibility for the currently active workbench window.
</td>
<td>3.3</td>
</tr>

<tr>
<td>activeWorkbenchWindow.activePerspective</td>
<td><code>java.lang.String</code></td>
<td>
Reports the name of the current perspective of the active workbench window.
</td>
<td>3.4</td>
</tr>

<tr>
<td>activeEditor</td>
<td><code>org.eclipse.ui.IEditorPart</code></td>
<td>
The currently active editor.  This is remembered even if the editor is not the currently active part.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activeEditorId</td>
<td><code>java.lang.String</code></td>
<td>
The ID of the currently active editor.  This can be used for expressions on the editor type.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activePart</td>
<td><code>org.eclipse.ui.IWorkbenchPart</code></td>
<td>
The active part, which can be the same as the active editor.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activePartId</td>
<td><code>java.lang.String</code></td>
<td>
The ID of the currently active part.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activeSite</td>
<td><code>org.eclipse.ui.IWorkbenchPartSite</code></td>
<td>
The site of the currently active part.
</td>
<td>3.2</td>
</tr>

<tr>
<td>selection</td>
<td><code>org.eclipse.jface.viewers.ISelection</code></td>
<td>
The current global selection.  It is often used with &lt;test/&gt; elements with <code>org.eclipse.core.expressions.PropertyTester</code>, in programmatic core expressions, and in '''3.3''' with &lt;iterate/&gt; and &lt;count/&gt; elements.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activeMenu</td>
<td>A <code>java.util.Collection</code> of <code>java.lang.String</code></td>
<td>
This is the list of IDs of the showing context menu.  Examples are like #TextEditorRuler or a part ID. Most commonly used with &lt;iterate/&gt;, &lt;count/&gt;, and &lt;test/&gt; with a combined <code>org.eclipse.common.expressions.PropertyTester</code>.
</td>
<td>3.2</td>
</tr>

<tr>
<td>activeMenuSelection</td>
<td><code>org.eclipse.jface.viewers.ISelection</code></td>
<td>
This is a selection that is available while a context menu is showing.  It is the selection from the selection provider used to register the context menu, usually from <code>getSite().registerContextMenu(*)</code>.  It is usually the same as the <code>selection</code>variable, but not always.  This is more for legacy compatibility.
</td>
<td>3.3</td>
</tr>

<tr>
<td>activeMenuEditorInput</td>
<td><code>org.eclipse.jface.viewers.ISelection</code></td>
<td>
This is a selection that is available while a context menu is showing.  It is the selection from the editor input, usually if includeEditorInput was set to <code>true</code> during <code>getEditorSite().registerContextMenu(*)</code>.  This is more for legacy compatibility.
</td>
<td>3.3</td>
</tr>

<tr>
<td>activeFocusControl</td>
<td><code>org.eclipse.swt.widgets.Control</code></td>
<td>
A control that has focus and has been registered with the [https://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/bundles/org.eclipse.ui.workbench/Eclipse%20UI/org/eclipse/ui/swt/IFocusService.java IFocusService].
</td>
<td>3.3</td>
</tr>

<tr>
<td>activeFocusControlId</td>
<td><code>java.lang.String</code></td>
<td>
The ID of a control that has focus and has been registered with the <code>org.eclipse.ui.swt.IFocusService</code>.
</td>
<td>3.3</td>
</tr>

</table>

Note: All these variables can be used with &lt;test/&gt; and a <code>org.eclipse.common.expressions.PropertyTester</code>.

= Property Testers =

The Eclipse SDK 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 <code>org.eclipse.core.resources.name</code>.


<table border="1">
<tr>
<th>Namespace</th>
<th>Type</th>
<th>Implementation</th>
</tr>

<tr>
<td>org.eclipse.core.runtime</td>
<td>
<code>org.eclipse.core.runtime.Platform</code>
</td>
<td>
[https://git.eclipse.org/c/platform/eclipse.platform.runtime.git/tree/bundles/org.eclipse.core.expressions/src/org/eclipse/core/internal/expressions/propertytester/PlatformPropertyTester.java PlatformPropertyTester.java]
</td>
</tr>


<tr>
<th>Property</th>
<th colspan="2">Description</th>
</tr>

<tr>
<td>
product
</td>
<td colspan="2">
Test the id of the currently active product.
</td>
</tr>

<tr>
<td>
isBundleInstalled
</td>
<td colspan="2">
Test if a given bundle is installed in the running environment.  Use the args attribute to pass in the bundle id.
</td>
</tr>

<tr>
<td colspan="3" bgcolor="#000000" height="3px"/>
</tr>

<tr>
<th>Namespace</th>
<th>Type</th>
<th>Implementation</th>
</tr>

<tr>
<td>org.eclipse.core.resources</td>
<td>
<code>org.eclipse.core.resources.IResource</code>
</td>
<td>
[https://git.eclipse.org/c/platform/eclipse.platform.resources.git/tree/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/propertytester/ResourcePropertyTester.java ResourcePropertyTester.java]
</td>
</tr>


<tr>
<th>Property</th>
<th colspan="2">Description</th>
</tr>



<tr>
<td>
name
</td>
<td colspan="2">
A property indicating the file name (value <code>"name"</code>). "*" and "?" wild cards are supported.
</td>
</tr>

<tr>
<td>
path
</td>
<td colspan="2">
A property indicating the file path (value <code>"path"</code>). "*" and "?" wild cards are supported.
</td>
</tr>

<tr>
<td>
extension
</td>
<td colspan="2">
A property indicating the file extension (value <code>"extension"</code>). "*" and "?" wild cards are supported.
</td>
</tr>

<tr>
<td>
readOnly
</td>
<td colspan="2">
A property indicating whether the file is read only (value <code>"readOnly"</code>).
</td>
</tr>

<tr>
<td>
projectNature
</td>
<td colspan="2">
A property indicating the project nature (value <code>"projectNature"</code>).
</td>
</tr>

<tr>
<td>
persistentProperty
</td>
<td colspan="2">
A property indicating a persistent property on the selected resource (value <code>"persistentProperty"</code>). If two arguments are given, this treats the first as the property name, and the second as the expected property value. If only one argument (or just the expected value) is given, this treats it as the property name, and simply tests for existence of the property on the resource.
</td>
</tr>

<tr>
<td>
projectPersistentProperty
</td>
<td colspan="2">
A property indicating a persistent property on the selected resource's project. (value <code>"projectPersistentProperty"</code>). If two arguments are given, this treats the first as the property name, and the second as the expected property value. If only one argument (or just the expected value) is given, this treats it as the property name, and simply tests for existence of the property on the resource.
</td>
</tr>

<tr>
<td>
sessionProperty
</td>
<td colspan="2">
A property indicating a session property on the selected resource (value <code>"sessionProperty"</code>). If two arguments are given, this treats the first as the property name, and the second as the expected property value. If only one argument (or just the expected value) is given, this treats it as the property name, and simply tests for existence of the property on the resource.
</td>
</tr>

<tr>
<td>
projectSessionProperty
</td>
<td colspan="2">
A property indicating a session property on the selected resource's project. (value <code>"projectSessionProperty"</code>). If two arguments are given, this treats the first as the property name, and the second as the expected property value. If only one argument (or just the expected value) is given, this treats it as the property name, and simply tests for existence of the property on the resource.
</td>
</tr>

<tr>
<td colspan="3" bgcolor="#000000" height="3px"/>
</tr>

<tr>
<th>Namespace</th>
<th>Type</th>
<th>Implementation</th>
</tr>

<tr>
<td>org.eclipse.core.resources</td>
<td>
<code>org.eclipse.core.resources.IFile</code>
</td>
<td>
[https://git.eclipse.org/c/platform/eclipse.platform.resources.git/tree/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/propertytester/FilePropertyTester.java FilePropertyTester.java]
</td>
</tr>


<tr>
<th>Property</th>
<th colspan="2">Description</th>
</tr>



<tr>
<td>
contentTypeId
</td>
<td colspan="2">
A property indicating that we are looking to verify that the file matches the content type matching the given identifier. The identifier is provided as the expected value.
</td>
</tr>

<tr>
<td colspan="3" bgcolor="#000000" height="3px"/>
</tr>


<tr>
<th>Namespace</th>
<th>Type</th>
<th>Implementation</th>
</tr>

<tr>
<td>org.eclipse.core.resources</td>
<td>
<code>org.eclipse.core.resources.IProject</code>
</td>
<td>
[https://git.eclipse.org/c/platform/eclipse.platform.resources.git/tree/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/propertytester/ProjectPropertyTester.java ProjectPropertyTester.java]
</td>
</tr>


<tr>
<th>Property</th>
<th colspan="2">Description</th>
</tr>

<tr>
<td>
open
</td>
<td colspan="2">
A property indicating whether the project is open (value <code>"open"</code>).
</td>
</tr>

<tr>
<td colspan="3" bgcolor="#000000" height="3px"/>
</tr>


<tr>
<th>Namespace</th>
<th>Type</th>
<th>Implementation</th>
</tr>

<tr>
<td>org.eclipse.core.resources</td>
<td>
<code>org.eclipse.core.resources.mapping.ResourceMapping</code>
</td>
<td>
[https://git.eclipse.org/c/platform/eclipse.platform.resources.git/tree/bundles/org.eclipse.core.resources/src/org/eclipse/core/internal/propertytester/ResourceMappingPropertyTester.java ResourceMappingPropertyTester.java]
</td>
</tr>


<tr>
<th>Property</th>
<th colspan="2">Description</th>
</tr>

<tr>
<td>
projectPersistentProperty
</td>
<td colspan="2">
A property indicating a persistent property on the selected resource's project. (value <code>"projectPersistentProperty"</code>). If two arguments are given, this treats the first as the property name, and the second as the expected property value. If only one argument (or just the expected value) is given, this treats it as the property name, and simply tests for existence of the property on the resource.
</td>
</tr>

<tr>
<td colspan="3" bgcolor="#000000" height="3px"/>
</tr>


<tr>
<th>Namespace</th>
<th>Type</th>
<th>Implementation</th>
</tr>

<tr>
<td>org.eclipse.ui</td>
<td>
<code>org.eclipse.ui.IWorkbench</code>
</td>
<td>
[https://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/bundles/org.eclipse.ui.workbench/Eclipse%20UI/org/eclipse/ui/internal/activities/ActivityPropertyTester.java ActivityPropertyTester.java]
</td>
</tr>


<tr>
<th>Property</th>
<th colspan="2">Description</th>
</tr>


<tr>
<td>
isActivityEnabled
</td>
<td colspan="2">
Test if the activity in args is enabled.
</td>
</tr>

<tr>
<td>
isCategoryEnabled
</td>
<td colspan="2">
Test if the category in args is enabled.
</td>
</tr>

<tr>
<td colspan="3" bgcolor="#000000" height="3px"/>
</tr>


<tr>
<th>Namespace</th>
<th>Type</th>
<th>Implementation</th>
</tr>

<tr>
<td>org.eclipse.ui.workbenchWindow</td>
<td>
<code>org.eclipse.ui.IWorkbenchWindow</code>
</td>
<td>
[https://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/bundles/org.eclipse.ui.workbench/Eclipse%20UI/org/eclipse/ui/internal/OpenPerspectivePropertyTester.java OpenPerspectivePropertyTester.java]
</td>
</tr>


<tr>
<th>Property</th>
<th colspan="2">Description</th>
</tr>

<tr>
<td>
isPerspectiveOpen
</td>
<td colspan="2">
Tests if any perspective is open.
</td>
</tr>



</table>

= Expression examples =

Here are some examples.  I'll pretend all of the examples are deciding when a handler is active.

== Basic IStructuredSelection ==

A view provides a structured selection through its selection provider.  An example would be the InfoView in <b>org.eclipse.ui.examples.contributions</b>.  You can browse the [http://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.ui.examples.contributions/plugin.xml plugin.xml] and
[http://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.ui.examples.contributions/src/org/eclipse/ui/examples/contributions/view/InfoView.java InfoView.java] files.  The InfoView provides an <code>IStructuredSelection</code> with 0 or more <code>org.eclipse.ui.examples.contributions.model.Person</code>.

When using the default variable, you must treat it as an <code>java.util.Collection</code>.  That means using &lt;count&gt; or &lt;iterate&gt;

<source lang="xml">
<activeWhen>
    <iterate>
       <instanceof value="org.eclipse.ui.examples.contributions.model.Person"/>
    </iterate>
</activeWhen>
</source>
== Package Explorer IStructuredSelection ==

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

# Iterate through the default variable
# adapt the selection elements to your class, in this case <code>IResource</code>
# use one of the org.eclipse.core.resources property testers to test the IResource property

For example:

<source lang="xml">
<activeWhen>
    <iterate>
       <adapt type="org.eclipse.core.resources.IResource">
          <test property="org.eclipse.core.resources.name" 
                value="*.java"/>
       </adapt>
    </iterate>
</activeWhen>
</source>

== Active editor type ==

If you want your handler to be active for a specific type of editor, you can use <b>activeEditorId</b> to target your handler.

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

== Complex nested boolean expressions ==

You can also write complex nested boolean expressions, like <tt>'''(a & b & (c | d | (!e)))'''</tt>:

<source lang="xml">
<and>
  <test args="a" property="rcpAuthActivitiesExample.test" />
  <test args="b" property="rcpAuthActivitiesExample.test" />
  <or>
    <test args="c" property="rcpAuthActivitiesExample.test" />
    <test args="d" property="rcpAuthActivitiesExample.test" />
    <not>
      <test args="e" property="rcpAuthActivitiesExample.test" />
    </not>
  </or>
</and>
</source>

You can build the complete boolean expression out of arbitrary single boolean expressions. Not only property testers like in this example.

= New Core Expressions in 3.3 =

In 3.3 there were 2 additions to the core expressions framework.

== count and iterate ==

Count and iterate have always worked against <code>java.util.Collection</code>.  The &lt;count/&gt; and &lt;iterate&gt; elements can now be used on any variable that adapts to <code>org.eclipse.core.expressions.ICountable</code> and <code>org.eclipse.core.expressions.IIterable</code> or implements the interfaces directly.  It wasn't possible to use the java 1.5 constructs for iterable.

The workbench provides an adapter for <code>ISelection</code> and <code>IStructuredSelection</code>.

== definitions ==

The <b>org.eclipse.core.expressions.definitions</b> extension point was introduced.  You can create core expression definitions, and then reference them from other core expressions.
<source lang="xml">
<extension point="org.eclipse.core.expressions.definitions">
    <definition id="org.eclipse.ui.examples.contributions.view.inView">
       <with variable="activePartId">
          <equals value="org.eclipse.ui.examples.contributions.view"/>
       </with>
    </definition>
</extension>
</source>

Then:
<source lang="xml">
<activeWhen>
    <reference definitionId="org.eclipse.ui.examples.contributions.view.inView"/>
</activeWhen>
</source>
The referenced expression will be evaluated at this point.


[[Category:Eclipse Project]]