The previous section showed how to hide or show a specific KeyBinding depending on the open editor type. However, it doesn't stop the command from being called via the menu, or from it showing up in the menu itself. Instead of just hiding the KeyBinding, the menu can be hidden as well by adding a visibleWhen block to the command.
The expressions framework provides a number of variables, including activeContexts, which contains a list of the active contexts at the time. Since many contexts can be active simultaneously, the active contexts is a list (for example, [dialogAndWindow,window,textEditor,javaEditor])—so to find an entry (in effect, a contains operation), an iterate with equals expression is used. Although it's possible to copy and paste expressions between places where they are used, it is preferable to reuse an identical expression.
- Open the
plugin.xmlfile, and add declare an expression using the expressions extension point as follows:<extension point="org.eclipse.core.expressions.definitions"> <definition id="when.hello.is.active"> <with variable="activeContexts"> <iterate operator="or"> <equals value="org.eclipse.ui.contexts.dialog"/> </iterate> </with> </definition> </extension> - Add a Visible-When expression to the Handled Menu Item – Hello element by choosing CoreExpression from the dropdown:
- Run the target Eclipse instance, and verify that the menu is hidden until a dialog is opened. If this behavior is not seen, run the Eclipse application with the
-cleanargument to clear the workspace. After clearing, it will be necessary to open a dialog to verify that the menu visibility is correct.
Menus have a visibleWhen guard that is evaluated when the menu is shown. If it is false, then the menu is hidden.
The expressions syntax is based on nested XML elements with certain conditions. For example, an <and> block is true if all of its children are true, whereas an <or> block is true if at least one of its children is true. Variables can also be used with a property test using a combination of a <with> block (which binds the specified variable to the stack) and an <equals> block or other comparison.
In the case of variables that have lists, an <iterate> can be used to step through elements using either operator="or" or operator="and" to dynamically calculate enablement.
There are a number of variables that can be used in tests; these are listed in the Eclipse help documentation under the Workbench Core Expressions chapter, and include:
activeContexts: This is a list of context IDs that are active at the timeactiveShell: This is the active shell (dialog or window)activeWorkbenchWindow: This is the active windowactiveEditor: This is the current or last active editoractivePart: This is the active part (editor or view)selection: This is the current selectionorg.eclipse.core.runtime.Platform: This is thePlatformobject
The Platform object is useful for performing dynamic tests using test, such as:
<test value="ACTIVE" property="org.eclipse.core.runtime.bundleState" args="org.eclipse.core.expressions"/> <test property="org.eclipse.core.runtime.isBundleInstalled" args="org.eclipse.core.expressions"/>
Knowing if a bundle is installed is often useful; it's better to only enable functionality if a bundle is started (or in OSGi terminology, ACTIVE). As a result, uses of isBundleInstalled have been replaced by bundleState=ACTIVE tests.
The org.eclipse.core.expressions extension point defined a virtual condition that is re-evaluated when the user's context changes, so that both the menu and the handler can be made visible and enabled at the same time.
Since references can be used anywhere, expressions can also be defined in terms of other expressions. As long as the expressions aren't recursive, they can be built up in any manner.