| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> | |
| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
| <meta name="GENERATOR" content="Mozilla/4.5 [en] (WinNT; I) [Netscape]"> | |
| <title>Eclipse Workbench Extension Point: Action Sets</title> | |
| </head> | |
| <body link="#0000FF" vlink="#800080"> | |
| <center> | |
| <h1> | |
| Expressions</h1></center> | |
| <b><i>Description: </i></b>Boolean expressions are used to define the visibility | |
| and enablement for many action extensions within the workbench. For | |
| instance, an <i>enablement</i> element can be defined within any action | |
| extension. This element contains a boolean expression defining the | |
| enablement criteria for the action. A <i>visibility</i> element can | |
| be defined for a popup menu action extension. This element contains | |
| a boolean expression defining the visibility criteria for the action. | |
| <p>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 <i>objectClass</i>, <i>objectState</i>, <i>systemProperty</i>, | |
| or <i>pluginState</i> element. In the more complex case, <i>and</i>, | |
| <i>or</i>, not elements can be combined to form a boolean expression. | |
| An <i>and</i> or <i>or</i> element may contain 1 or more sub elements. | |
| A <i>not</i> element must contain only 1 sub element. | |
| <p>An <i>objectClass</i> 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. | |
| <p>An <i>objectState</i> 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 <tt>IFile</tt> which are read only. This read only | |
| criteria can only be declared by specifying an <i>objectState</i> element. | |
| It may have the following form .. | |
| <br> | |
| <blockquote><tt><objectState name="readOnly" value="true"/></tt></blockquote> | |
| 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 <tt>IActionFilter</tt>, an evaluation strategy for | |
| <i>objectState</i> elements. When an objectState element is evaluated, | |
| the workbench ask each object in the selection for an <tt>IActionFilter</tt>. | |
| It does this by testing to see if it implements <tt>IActionFilter</tt>. | |
| If that fails, the workbench will ask for a filter through through the | |
| <tt>IAdaptable</tt> mechanism. If a filter is found, the workbench | |
| will pass the <i>objectState</i> 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. | |
| <p>View and editors are encouraged to define an <tt>IActionFilter</tt> | |
| 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. | |
| <p>A <i>systemProperty</i> 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. | |
| <p>A <i>pluginState</i> element is used to evaluate the state of a plugin. | |
| The state of the plugin may be installed or activated. | |
| <p><b><i>Configuration Markup:</i></b> | |
| <p><tt> <!ELEMENT visibility (and | or | not | objectClass | |
| | objectState | systemProperty</tt> | |
| <br><tt> | pluginState)></tt><tt></tt> | |
| <p><tt> <!ELEMENT enablement (and | or | not | objectClass | |
| | objectState | systemProperty</tt> | |
| <br><tt> | pluginState)></tt><tt></tt> | |
| <p><tt> <!ELEMENT and (and | or | not | objectClass | objectState | |
| | systemProperty | pluginState)*></tt><tt></tt> | |
| <p><tt> <!ELEMENT or (and | or | not | objectClass | objectState | |
| | systemProperty | pluginState)*></tt><tt></tt> | |
| <p><tt> <!ELEMENT not (and | or | not | objectClass | objectState | |
| | systemProperty | pluginState)></tt><tt></tt> | |
| <p><tt> <!ELEMENT objectClass EMPTY></tt> | |
| <br><tt> <!ATTLIST objectClass</tt> | |
| <br><tt> name | |
| CDATA #REQUIRED</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>name</b> - a fully qualified name of a class. The expression is | |
| evaluated as true only if the selection implement this class.</li> | |
| </ul> | |
| <tt> <!ELEMENT objectState EMPTY></tt> | |
| <br><tt> <!ATTLIST objectState</tt> | |
| <br><tt> name | |
| CDATA #REQUIRED</tt> | |
| <br><tt> value | |
| CDATA #REQUIRED</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>name </b>- 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.</li> | |
| <li> | |
| <b>value</b> - the required value of the object attribute. The acceptable | |
| values for the object attribute should be publicly declared.</li> | |
| </ul> | |
| <tt> <!ELEMENT systemProperty EMPTY></tt> | |
| <br><tt> <!ATTLIST systemProperty</tt> | |
| <br><tt> name | |
| CDATA #REQUIRED</tt> | |
| <br><tt> value | |
| CDATA #REQUIRED</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>name </b>- the name of the system property.</li> | |
| <li> | |
| <b>value</b> - the required value of the system property.</li> | |
| </ul> | |
| <tt> <!ELEMENT pluginState EMPTY></tt> | |
| <br><tt> <!ATTLIST pluginState</tt> | |
| <br><tt> id | |
| CDATA #REQUIRED</tt> | |
| <br><tt> value | |
| (installed | activated)</tt> | |
| <br><tt> ></tt> | |
| <blockquote> | |
| <li> | |
| <b>id </b>- an id of a plugin which may or may not be registered in the | |
| plug-in registry.</li> | |
| <li> | |
| <b>value</b> - the required state of the plugin. Currently two states | |
| are supported: installed and activated.</li> | |
| </blockquote> | |
| <b><i>Examples:</i></b> | |
| <p>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 | |
| <tt>ListElements</tt> with various state. A <tt>ListElement</tt> | |
| has two attributes: <i>name</i> (a string) and <i>flag</i> (a boolean). | |
| In this example, the All action (<img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_a.jpg" height=13 width=24 align=ABSCENTER>) | |
| is enabled whenever a ListElement is selected. The Red action (<img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_b.jpg" height=13 width=24 align=ABSCENTER>) | |
| is enabled when a ListElement with name = red is selected. And the | |
| Not Red action (<img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_c.jpg" height=13 width=24 align=ABSCENTER>) | |
| is enabled when a ListElement with name != red is selected. | |
| <blockquote><tt><extension point = "org.eclipse.ui.actionSets"></tt> | |
| <br><tt> <actionSet id="org.eclipse.ui.tests.internal.ListElementActions"</tt> | |
| <br><tt> label="List Element"></tt> | |
| <br><tt> <menu id="org.eclipse.ui.tests.internal.ListElementMenu"</tt> | |
| <br><tt> | |
| label="List Element"</tt> | |
| <br><tt> | |
| path="additions"></tt> | |
| <br><tt> | |
| <separator name="group1"/></tt> | |
| <br><tt> </menu></tt> | |
| <br><img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_a.jpg" height=13 width=24 align=ABSCENTER><tt> | |
| <action id="org.eclipse.ui.tests.internal.ac1"</tt> | |
| <br><tt> | |
| label="All"</tt> | |
| <br><tt> | |
| menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"</tt> | |
| <br><tt> | |
| class="org.eclipse.ui.tests.api.MockActionDelegate"</tt> | |
| <br><tt> | |
| enablesFor="1"></tt> | |
| <br><tt> | |
| <enablement></tt> | |
| <br><tt> | |
| <objectClass name="org.eclipse.ui.tests.api.ListElement"/></tt> | |
| <br><tt> | |
| </enablement></tt> | |
| <br><tt> </action></tt> | |
| <br><img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_b.jpg" height=13 width=24 align=ABSCENTER><tt> | |
| <action id="org.eclipse.ui.tests.internal.ac2"</tt> | |
| <br><tt> | |
| label="Red"</tt> | |
| <br><tt> | |
| menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"</tt> | |
| <br><tt> | |
| class="org.eclipse.ui.tests.api.MockActionDelegate"</tt> | |
| <br><tt> | |
| enablesFor="1"></tt> | |
| <br><tt> | |
| <enablement></tt> | |
| <br><tt> | |
| <and></tt> | |
| <br><tt> | |
| <objectClass name="org.eclipse.ui.tests.api.ListElement"/></tt> | |
| <br><tt> | |
| <objectState name="name" value="red"/></tt> | |
| <br><tt> | |
| </and></tt> | |
| <br><tt> | |
| </enablement></tt> | |
| <br><tt> </action></tt> | |
| <br><img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_c.jpg" height=13 width=24 align=ABSCENTER><tt> | |
| <action id="org.eclipse.ui.tests.internal.ac3"</tt> | |
| <br><tt> | |
| label="Not Red"</tt> | |
| <br><tt> | |
| menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"</tt> | |
| <br><tt> | |
| class="org.eclipse.ui.tests.api.MockActionDelegate"</tt> | |
| <br><tt> | |
| enablesFor="1"></tt> | |
| <br><tt> | |
| <enablement></tt> | |
| <br><tt> | |
| <and></tt> | |
| <br><tt> | |
| <objectClass name="org.eclipse.ui.tests.api.ListElement"/></tt> | |
| <br><tt> | |
| <not></tt> | |
| <br><tt> | |
| <objectState name="name" value="red"/></tt> | |
| <br><tt> | |
| </not></tt> | |
| <br><tt> </and></tt> | |
| <br><tt> | |
| </enablement></tt> | |
| <br><tt> </action></tt> | |
| <br><tt> </actionSet></tt> | |
| <br><tt></extension></tt></blockquote> | |
| In the next example the <i>pluginState</i> element is used to control the | |
| enablement of actions in an action set. The Installed action (<img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_a.jpg" height=13 width=24 align=ABSCENTER>) | |
| is enabled when the plugin with <tt>x.y.z.myPlugin</tt> is installed. | |
| The Activated action (<img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_b.jpg" height=13 width=24 align=ABSCENTER>) | |
| is enabled when the same plugin has been activated. | |
| <blockquote><tt><extension point = "org.eclipse.ui.actionSets"></tt> | |
| <br><tt> <actionSet id="org.eclipse.ui.tests.internal.ListElementActions"</tt> | |
| <br><tt> label="List Element"></tt> | |
| <br><tt> <menu id="org.eclipse.ui.tests.internal.ListElementMenu"</tt> | |
| <br><tt> | |
| label="List Element"</tt> | |
| <br><tt> | |
| path="additions"></tt> | |
| <br><tt> | |
| <separator name="group1"/></tt> | |
| <br><tt> </menu></tt> | |
| <br><img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_a.jpg" height=13 width=24 align=ABSCENTER><tt> | |
| <action id="org.eclipse.ui.tests.internal.ac8"</tt> | |
| <br><tt> | |
| label="Installed"</tt> | |
| <br><tt> | |
| menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"</tt> | |
| <br><tt> | |
| class="org.eclipse.ui.tests.api.MockActionDelegate"></tt> | |
| <br><tt> | |
| <enablement></tt> | |
| <br><tt> | |
| <pluginState id="x.y.z.myPlugin" value="installed"/></tt> | |
| <br><tt> | |
| </enablement></tt> | |
| <br><tt> </action></tt> | |
| <br><img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_b.jpg" height=13 width=24 align=ABSCENTER><tt> | |
| <action id="org.eclipse.ui.tests.internal.ac10"</tt> | |
| <br><tt> | |
| label="Activated"</tt> | |
| <br><tt> | |
| menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"</tt> | |
| <br><tt> | |
| class="org.eclipse.ui.tests.api.MockActionDelegate"></tt> | |
| <br><tt> | |
| <enablement></tt> | |
| <br><tt> | |
| <pluginState id="x.y.z.myPlugin" value="activated"/></tt> | |
| <br><tt> | |
| </enablement></tt> | |
| <br><tt> </action></tt> | |
| <br><tt> </actionSet></tt> | |
| <br><tt></extension></tt></blockquote> | |
| In the next example the systemProperty element is demonstrated. The | |
| System Property action (<img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_a.jpg" height=13 width=24 align=ABSCENTER>) | |
| is enabled when the ActionExpressionVar system property is equal to "bubba". | |
| <blockquote><tt><extension point = "org.eclipse.ui.actionSets"></tt> | |
| <br><tt> <actionSet id="org.eclipse.ui.tests.internal.ListElementActions"</tt> | |
| <br><tt> label="List Element"></tt> | |
| <br><tt> <menu id="org.eclipse.ui.tests.internal.ListElementMenu"</tt> | |
| <br><tt> | |
| label="List Element"</tt> | |
| <br><tt> | |
| path="additions"></tt> | |
| <br><tt> | |
| <separator name="group1"/></tt> | |
| <br><tt> </menu></tt> | |
| <br><img SRC="../../org.eclipse.ui.articles.guidelines/doc/images/tag_a.jpg" height=13 width=24 align=ABSCENTER><tt> | |
| <action id="org.eclipse.ui.tests.internal.ac11"</tt> | |
| <br><tt> | |
| label="System Property"</tt> | |
| <br><tt> | |
| menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"</tt> | |
| <br><tt> | |
| class="org.eclipse.ui.tests.api.MockActionDelegate"></tt> | |
| <br><tt> | |
| <enablement></tt> | |
| <br><tt> | |
| <systemProperty name="ActionExpressionVar" value="bubba"/></tt> | |
| <br><tt> | |
| </enablement></tt> | |
| <br><tt> </action></tt> | |
| <br><tt> </actionSet></tt> | |
| <br><tt></extension></tt></blockquote> | |
| 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 <tt>ListElement</tt> is selected with <i>name = red</i> and | |
| <i>flag = true</i>. | |
| <blockquote><tt><extension point="org.eclipse.ui.popupMenus"></tt> | |
| <br><tt> <objectContribution id="oc6"</tt> | |
| <br><tt> objectClass="org.eclipse.ui.tests.api.ListElement"></tt> | |
| <br><tt> <visibility></tt> | |
| <br><tt> <and></tt> | |
| <br><tt> | |
| <objectState name="name" value="red"/></tt> | |
| <br><tt> | |
| <objectState name="flag" value="true"/></tt> | |
| <br><tt> </and></tt> | |
| <br><tt> </visibility></tt> | |
| <br><tt> <action id="oc4" label="Red And | |
| True"</tt> | |
| <br><tt> class="org.eclipse.ui.tests.api.MockActionDelegate"/></tt> | |
| <br><tt> </objectContribution></tt> | |
| <br><tt></extension></tt></blockquote> | |
| <p><br><b><i>Supplied Implementation:</i></b> For convenience, action filters | |
| have been defined for markers, resources, and projects. The name-value | |
| pairs for each are declared on <tt>IMarkerActionFilter</tt>, <tt>IResourceActionFilter</tt>, | |
| and <tt>IProjectActionFilter</tt>. | |
| <br> | |
| <p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corp. 2000, 2001. All Rights Reserved." BORDER=0 height=12 width=195></a> | |
| </body> | |
| </html> |