About Conditional Activation and Handler Policies
Conditional activation of a menu contribution is the definition of conditions that make a menu entry visible or hidden, and enabled or disabled.
In Sabre Red 360 the conditions that make menu entries visible are based on the component in active status. A handler policy provides the ability to make a visible menu entry either enabled or disabled.
You have a variety of options for implementing conditional menu activation in Sabre Red 360. Basic options are presented in Basic Menu Contributions. The basic topic shows how to do the following:
Add a menu contribution that is always visible and always enabled. This type of menu contribution does not have conditions or handler policies.
Make a menu contribution visible based on whether a specific command is active or enabled. In this case, the components are Sabre emulator and a Sample Editor. If either of the commands to open these editors is active, the menu entry that corresponds to the component is visible.
This advanced topic explains advanced conditional menu activation and handler policies that you can apply to Red Apps that are embedded either in editors or views. The step-by-step procedure shows how to do the following:
Display a menu entry only when a specific component is active. Otherwise, the menu entry is hidden. For this type of control, conditions are set on the menu.
Use a handler policy to control when a handler and its corresponding menu entry are enabled or disabled.
Add a reference to a definition in order to extract an expression.
The following figure illustrates the conditional activation of menus that the procedure in this book shows how to build.
Enabled state of menu entries with a dependency on the Sample Editor having active status
Visible and enabled states of a menu entry with a dependency on Sabre emulator having active status
Menu Control Based on an Active Component
In order to specify the conditions that make a menu contribution either visible or hidden, Eclipse provides the
visibleWhen element. The
visibleWhen element is added to the org.eclipse.ui.menus extension with the
checkEnabled child set to
false. A setting of
false is required to add conditions. Because Eclipse does not check the handler when
false, the menu entry is displayed whether the handler is or is not enabled. By adding handler policies and expressions, you can control the behavior of menus.
Policies to Activate and Enable Handlers
Eclipse provides the following parameters to control handlers:
activeWhenparameter controls when to activate a handler.
enabledWhenparameter controls when to enable a handler.
A command is active when there is at least one active handler that is associated with the command.
If you specify
activeWhen, but you do not set
enabledWhen, your handler will be activated conditionally and always enabled.
In other words, adding
activeWhen with conditions to a handler, and omitting
enabledWhen from the handler has the following results:
The handler is activated when the conditions are fulfilled, and the handler is always enabled. In Sabre Red 360, when the conditions on
activeWhen are met, the menu entry is visible and always enabled. (End-users can always select it.)
If you do not specify
activeWhen but you set
enabledWhen, your handler will always be active, but your handler is enabled only for the specified condition.
In other words, adding
enabledWhen to the handler with conditions while omitting
activeWhen from the handler has the following results:
The handler is always active (visible in Sabre Red 360), but it is only enabled when the conditions are fulfilled, meaning that end-users can only select the corresponding menu.
Scenario with activeWhen and enabledWhen
The following scenarios explain the
activeWhen and the
Suppose that you want to assign two different handlers to the same command: One handler is triggered when an Internet connection is established; the other handler catches the situation in which an Internet connection is not available. The
activeWhen statement defines the activation policy for each handler. When the command is triggered at runtime, Eclipse evaluates the conditions on
activeWhen for every handler that is assigned to this command and runs the appropriate handler.
An enabling handler is similar to adding a second layer of conditions. Suppose that Eclipse has run your handler and consequently, the handler is activated. However, you want to add more conditions to enable the handler. You want to add a Copy command to the Edit menu that is functional only with Sabre emulator. To define this behavior, you add a condition to
activeWhen that checks whether the active editor is Sabre emulator. In the
enabledWhen parameter you specify that the state for your handler is enabled only if any text is selected to be copied.
Use of Declared Variables and Definitions to Build Definitions
To build conditions for menus and handlers, you can create your own conditions from scratch using statements that include elements such as with and equals.
Sabre Red 360 provides a limited set of declared variables and definitions. The variables are used to build definitions. The declared definitions are designed for use with the reference element.
If these variables and definitions provide the functionality that you want, it is recommended that you use them. They are described in the topics that follow.
Sabre Red 360 Declared Variables for Building Definitions
This variable stores the identifier of an active editor.
<definition id="com.sabre.redapp.example.conditional.activation.editor"> <with variable="edgeActiveEditorId"> <equals value="com.sabre.redapp.example.editor.basic.SampleEditor"/> </with> </definition>
This variable stores an instance of an active editor.
<definition id="com.sabre.redapp.example.conditional.activation.editor"> <with variable="edgeActiveEditor"> <instanceof value="com.sabre.edge.app.emulator.editor.EmulatorEditor"/> </with> </definition>
This variable stores the identifier of an active part.
<definition id="com.sabre.redapp.example.conditional.activation.editPart"> <with variable="edgeActivePartId"> <instanceof value="com.sabre.edge.app.emulator.editor.EmulatorEditor"/> </with> </definition>
Sabre Red 360 Declared Definitions for Use with the reference Element
This definition checks whether the active editor is Sabre emulator.
This definition checks whether the active editor is Sabre emulator and whether it was loaded successfully. You do not need to know the emulator identifier when you use this definition.
This definition checks whether SiteMinder is available.
Use of Expressions to Build Complex Conditions
The use of expressions is a flexible and powerful way to build complex conditions. Eclipse provides several elements for
enabledWhen that you can use to build advanced expressions. The list of these elements is shown in the next figure.
You can combine some of these elements to build complex expressions and conditions for controlling menu activation. However, some of these elements cannot be used with Sabre Red 360.
The following describes the child elements of
visibleWhen that you can use with Sabre Red 360 plug-ins. For more information about these elements, consult the Eclipse documentation.
When multiple sub-element expressions are evaluated, Eclipse performs an
AND operation on the result.
This element checks whether the focused object is equal to the specified value property.
<activeWhen> <with variable="edgeActiveEditorId"> <equals value="com.sabre.redapp.example.editor.basic.SampleEditor"/> </with> </activeWhen>
This element performs an
instanceof check on the object that is in focus.
<enabledWhen> <with variable="edgeActiveEditor"> <instanceof value="com.sabre.redapp.example.editor.basic.SampleEditor"/> </with> </enabledWhen>
When multiple sub-element expressions are evaluated, Eclipse performs a
NOT operation on the result.
<visibleWhen checkEnabled="false"> <with variable="edgeActiveEditorId"> <not> <equals value="com.sabre.redapp.example.editor.basic.SampleEditor"/> </not> </with> </visibleWhen>
When multiple sub-element expressions are evaluated, Eclipse performs an
OR operation on the result.
reference element refers to an expression that is defined in org.eclipse.core.expressions.definitions . The
definitionId is the unique id of the expression definition to use for the evaluation.
<visibleWhen checkEnabled="false"> <reference definitionId="com.sabre.redapp.example.conditional.activation.editor"> </reference> </visibleWhen>
test element evaluates the value of a specific property on the focused object. It requires writing a Java class that implements the property tester.
with element changes the object to inspect or focus onto the object that the variable attribute references. In most cases, you will use
with together with other items such as
Reuse of Expressions with Reference Definitions
Eclipse has a mechanism that lets you use the same expression for different menu contributions and handlers that are either within the same plug-in or within other plug-ins. You create a definition with the reference element by extracting an expression to a definition, and then reference the definition from the
For more information, see the step-by-step procedure Controlling the Visibility and Activation of Menu Contributions. The procedure demonstrates how to use definitions to extract an expression that checks the active editor with a definition, and references the definition from a
menuContribution element in a plug-in.
The minimum required extension points for conditional activation follow:
org.eclipse.core.expressions.definitions . This is required if you are creating your own definitions.
You can use existing definitions within other plug-ins, such as Sabre Red 360 definitions, without this extension point.