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 checkEnabled is 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:

The activeWhen parameter controls when to activate a handler.
The enabledWhen parameter controls when to enable a handler.

A command is active when there is at least one active handler that is associated with the command.

activeWhen

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.)

enabledWhen

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 enabledWhen parameters.

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

edgeActiveEditorId

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>

edgeActiveEditor

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>

edgeActivePartId

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

com.sabre.edge.command.definitions.editorMenu

This definition checks whether the active editor is Sabre emulator.

com.sabre.edge.command.definitions.editor

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.

com.sabre.edge.command.definitions.smAvailable

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 visibleWhen, activeWhen, and 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.

and

When multiple sub-element expressions are evaluated, Eclipse performs an AND operation on the result.

equals

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>

instanceOf

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>

not

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>

or

When multiple sub-element expressions are evaluated, Eclipse performs an OR operation on the result.

reference

The 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

The 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

The 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 equals or instanceOf.

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 menuContribution element.

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.

Extension Points

The minimum required extension points for conditional activation follow:

org.eclipse.ui.menus

org.eclipse.ui.handlers

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.