| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML> |
| <HEAD> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <TITLE> |
| Boolean expressions and action filters |
| </TITLE> |
| |
| <link rel="stylesheet" type="text/css" HREF="../book.css"> |
| </HEAD> |
| <BODY BGCOLOR="#ffffff"> |
| <H2> |
| Boolean expressions and action filters</H2> |
| <p> |
| 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 <b>boolean |
| expressions</b> for more flexibility in determining when an action should be visible or enabled.</p> |
| |
| |
| <h3>Boolean enablement expressions</h3> |
| <p>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: |
| </p> |
| <ul> |
| <li><b>instanceof</b> tests whether the type of the object in focus is a subtype of the specified type name.</li> |
| <li><b>test</b> tests whether the value of a named property of the object in focus matches the specified value.</li> |
| <li><b>systemTest</b> tests whether the value of a named system property matches the specified value. </li> |
| <li><b>equals</b> tests whether the object in focus is equal to the specified value.</li> |
| <li><b>count</b> tests the number of elements in a list.</li> |
| <li><b>with</b> changes the object in focus to the object referenced by a supplied variable.</li> |
| <li><b>resolve</b> changes the object in focus to the object referenced by a supplied variable, supplying additional |
| arguments with the variable.</li> |
| <li><b>adapt</b> adapts the object in focus to the type specified.</li> |
| <li><b>iterate</b> iterates over a variable that is a collection and combines the boolean value of each value using AND or OR.</li> |
| </ul> |
| <p> |
| 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: |
| </p> |
| <ul> |
| <li>the string "true" is converted into Boolean.TRUE</li> |
| <li>the string "false" is converted into Boolean.FALSE</li> |
| <li>if the string contains a dot, the interpreter tries to convert the value into a Float object</li> |
| <li>if the string only consists of numbers, the interpreter converts the value into an Integer object</li> |
| <li>the conversion into a Boolean, Float, or Integer can be suppressed by surrounding the string with single quotes.</li> |
| </ul> |
| <p>A complete definition of enablement XML syntax can be found in the extension point reference documentation for any |
| extension that defines an <b>enablement</b> element, such as |
| <b><a href="../reference/extension-points/org_eclipse_ui_popupMenus.html#e.enablement"> org.eclipse.ui.popupMenus</a></b>. |
| </p> |
| <p>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:</p> |
| <ul> |
| <li> |
| <p><b>objectClass</b> - true if each object in the |
| selection subclasses or implements the class.</p> |
| </li> |
| <li> |
| <p><b>objectState</b> - true if the named attribute equals the specified value. <b><a href="../reference/api/org/eclipse/ui/IActionFilter.html">IActionFilter</a> |
| </b>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.</p> |
| </li> |
| <li> |
| <p><b>systemProperty</b> - true if the named system |
| property equals the specified value.</p> |
| </li> |
| <li> |
| <p><b>pluginState</b> - specifies whether the specified |
| plug-in (by <b>id</b>) should be <b>installed</b> or <b>activated</b> </p> |
| </li> |
| </ul> |
| <p>For example, the following snippets represent enablement |
| expressions that could be used on a hypothetical action in an action set: </p> |
| <pre><action id="org.eclipse.examples.actionEnablement.class" |
| label="Red Element" |
| menubarPath="additions" |
| class="org.eclipse.examples.actionEnablement.ObjectTestAction"> |
| <enablement> |
| <b> <and> |
| <objectClass name="org.eclipse.examples.actionEnablement.TestElement"/> |
| <objectState name="name" value="red"/> |
| </and> |
| </b> </enablement> |
| </action></pre> |
| <pre><action id="org.eclipse.examples.actionEnablement.property" |
| label="Property" |
| menubarPath="additions" |
| class="org.eclipse.examples.actionEnablement.PropertyTestAction"> |
| <enablement> |
| <b> <systemProperty name="MyTestProperty" value="puppy"/> |
| </b> </enablement> |
| </action> </pre> |
| <pre><action id="org.eclipse.examples.actionEnablement.pluginState" |
| label="Installed" |
| menubarPath="additions" |
| class="org.eclipse.examples.actionEnablement.PluginTestAction"> |
| <enablement> |
| <b><pluginState id="x.y.z.anotherPlugin" value="installed"/> </b> |
| </enablement> |
| </action> </pre> |
| <p>See the reference documentation of the extension points |
| for more elaborate samples of these expressions and a complete description of |
| the XML.</p> |
| |
| |
| <p> |
| The following table lists extension points that contribute actions and |
| summarizes how XML markup attributes and boolean expressions can be used to |
| affect enablement.</p> |
| |
| |
| <TABLE BORDER="1" width="671"> |
| <TR> |
| <TH ROWSPAN="1" COLSPAN="1" width="118"> |
| <P CLASS="CellHeading"> |
| Extension point name</p> |
| </TH> |
| <TH ROWSPAN="1" COLSPAN="1" width="359"> |
| <P CLASS="CellHeading"> |
| Attributes affecting enablement</p> |
| </TH> |
| <TH ROWSPAN="1" COLSPAN="1" width="335"> |
| <P CLASS="CellHeading"> |
| Boolean expressions</p> |
| </TH> |
| </TR> |
| <TR> |
| <TD width="118"> |
| <p> |
| <b> |
| <a href="../reference/extension-points/org_eclipse_ui_viewActions.html"> |
| viewActions</a></b>,</p> |
| <p><b><a href="../reference/extension-points/org_eclipse_ui_editorActions.html">editorActions</a></b>,</p> |
| <p><b><a href="../reference/extension-points/org_eclipse_ui_actionSets.html">actionSets</a></b></p> |
| </TD> |
| <TD width="359"> |
| <p> |
| <b>enablesFor</b> - specifies the selection count that must be met for the |
| action to be enabled</p> |
| <p> |
| <b>selection</b> <b>class</b> - the class that the selected objects must |
| subclass or implement in order for the action to be enabled</p> |
| <p> |
| <b>selection</b> <b>name</b> - a wild card filter that can be applied to the |
| objects in the selection.</p> |
| </TD> |
| <TD width="335"> |
| <p> |
| <b>visibility</b> - a boolean expression. Controls whether the menu item |
| is visible in the menu.</p> |
| <p> |
| <b>enablement</b> - a boolean expression. Controls whether the menu item |
| is enabled in the menu. The <b>enablesFor</b> attribute and the <b>selection</b> <b>class</b> |
| and <b>name</b>, and must be |
| satisfied before applying the enablement expression.</p> |
| </TD> |
| </TR> |
| <TR> |
| <TD width="118"> |
| <p> |
| <b> |
| <a href="../reference/extension-points/org_eclipse_ui_popupMenus.html"> |
| popupMenus</a></b></p> |
| </TD> |
| <TD width="359"> |
| <p> |
| (For object contributions only.)</p> |
| <p> |
| <b>objectClass</b> - specifies the class that objects in the selection must |
| subclass or implement</p> |
| <p> |
| (For both object and viewer contributions)</p> |
| <p> |
| <b>enablesFor</b> - specifies the selection count that must be met for the |
| action to be enabled</p> |
| <p> |
| <b>selection</b> <b>class</b> - the class that the selected objects must |
| subclass or implement to enable the action</p> |
| <p> |
| <b>selection</b> <b>name</b> - a wild card filter that can be applied to the |
| objects in the selection.</p> |
| <p> |
| </p> |
| </TD> |
| <TD width="335"> |
| <p> |
| (For both object and viewer contributions)</p> |
| <p> |
| <b>visibility</b> - a boolean expression. Controls whether the menu item |
| is visible in the menu.</p> |
| <p><b>enablement</b> - a boolean expression. Controls |
| whether the menu item is enabled in the menu. |
| The <b>enablesFor</b> attribute and the <b>selection</b> <b>class</b> and <b>name</b>, and must be |
| satisfied before applying the enablement expression.</p> |
| </TD> |
| </TR> |
| </TABLE> |
| |
| <h3>Using objectState with content types</h3> |
| <p>The ability to define content types (see <a href="runtime_content.htm">Content types</a>) 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. |
| </p> |
| <pre> |
| <extension point="org.eclipse.ui.popupMenus"> |
| <objectContribution |
| id="com.example.objectContributions" |
| objectClass="org.eclipse.core.resources.IFile" |
| nameFilter="*.xml"> |
| <visibility> |
| <or> |
| <objectState |
| <b>name="contentTypeId"</b> |
| value="com.example.employeeRecordContentType"/> |
| <objectState |
| <b>name="contentTypeId"</b> |
| value="com.example.customerRecordContentType"/> |
| </or> |
| </visibility> |
| <action id="com.example.action1" |
| ... |
| </pre> |
| The <b>contentTypeId</b> 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 <a href="runtime_content.htm">Content types</a> for more detail |
| about the content type extension. |
| |
| |
| |
| </BODY> |
| </HTML> |
