Riena/Key Bindings

{{#eclipseproject:rt.riena}}

Riena Project ▶ Getting Started ▶ Key Bindings

This document

• provides an introduction to key binding definition in Eclipse,
• lists the default Riena key bindings,
• explains how to best extend or replace them, and
• provides migration instructions from Riena 1.1.

Intro to Key Bindings

Key bindings are defined using the org.eclipse.ui.bindings Extension Point (details). A key binding assigns a key sequence (F10) to a command (what to do) in a given scheme and context:

  <extension
         point="org.eclipse.ui.bindings">
      <scheme
            id="my.key.bindings"
            name="My Key Bindings"
            parentId="org.eclipse.riena.ui.defaultBindings">
      </scheme>
      <key
            commandId="org.eclipse.riena.example.client.exitCommand"
            contextId="org.eclipse.ui.contexts.window"
            schemeId="my.key.bindings"
            sequence="F10">
      </key>
  </extension>

Schemes

A Scheme is used to create a named group of key bindings. A running application can set the active scheme to put one group of key bindings in control of the application.

A scheme can reference a parent scheme, via the optional parentId attribute, to inherit any key bindings held by the parent - but can still reassign inherited key bindings to other commands. We have defined a Riena scheme with the id org.eclipse.riena.ui.defaultBindings for the default key bindings supported by a Riena application. If you need your own key bindings, we recommend that you define your own scheme and declare org.eclipse.riena.ui.defaultBindings as your parent scheme. This will give you the predefined bindings and allow you to overwrite any of those.

Contexts

A key binding also references a Context, which assigns this key binding to a specific situation within that scheme. The key binding will only be active in that situation. The platform already defines several standard contexts, via the org.eclipse.ui plugin. The most common contexts are:

• org.eclipse.ui.contexts.window - a window is open - most common case
• org.eclipse.ui.contexts.dialog - a dialog is open
• org.eclipse.ui.textEditorScope - edit text content - implies contexts.window

Currently all key bindings defined by Riena are assigned to the 'org.eclipse.ui.contexts.window' context. If you define your own key bindings, you will most likely use this context as well. If you do define your own, you should know that contexts can also be extended but cannot overwrite or inherit key bindings.

References

• Basic workbench extension points using commands
• Schemes
• org.eclipse.ui.bindings extension point
• Contexts and key bindings
• org.eclipse.ui.contexts extension point

Default Riena Key Bindings

Starting with Riena 1.2 a Riena application has the following standard key bindings:

• Next SubApplication - Ctrl+PgDn
• Previous SubApplication - Ctrl+PgUp
• Focus on Navigation Tree - F6
• Focus on Workarea - F7
• Focus on Window Menu - F10 (windows only)
• Focus on Window Toolbar - F10; Tab (windows only)
• Close Module - Ctrl+W
• Close Module Group - Ctrl+Shift+W
• Next Module/ModuleGroup - Ctrl+Down
• Prev Module/ModuleGroup - Ctrl+Up
• Next/Previous navigation element: Arrow Down / Arrow Up. This will move to the next available SubModule / Module or Module Group.
• Quit Application - Alt+F4 (windows only)

These keys are assigned to the scheme org.eclipse.riena.ui.defaultBindings, which is the default active scheme for Riena apps. The are also assigned to the context org.eclipse.ui.contexts.window. This means they are only active when the window has the focus, not in dialogs.

The standard key bindings can be extended or replaced, as described next.

Defining your own Key Bindings

The best way to define your own key bindings, is to create a new scheme that extends Riena's scheme 'org.eclipse.riena.ui.defaultBindings'.

The benefit of defining your own scheme is that you automatically inherit all key bindings provided by Riena (included bindings added in a later version), while making sure that your bindings will always overwrite the predefined ones, without conflict.

To accomplish this use the org.eclipse.ui.bindings extension point to define your own scheme, while referencing 'org.eclipse.riena.ui.defaultBindings' in the parentId attribute. Then define new key elements as needed and assign them to your scheme, via their schemeId attribute:

  <extension
         point="org.eclipse.ui.bindings">
      <!-- here you define your own scheme and extend Riena's -->
      <scheme
            id="my.key.bindings"
            name="My Key Bindings"
            parentId="org.eclipse.riena.ui.defaultBindings"> <!-- inherits from this -->
      </scheme>
      <!-- here you define your own key bindings -->
      <key
            commandId="org.eclipse.riena.example.client.exitCommand"
            contextId="org.eclipse.ui.contexts.window"
            schemeId="my.key.bindings" <!-- assigns key binding to your scheme -->
            sequence="F10">
      </key>
      <!--- more key elements --->
  </extension>

In addition, your SwtApplication subclass must overwrite the getKeyScheme() method and return the identifier of your scheme definition:

  public class MyApplication extends SwtApplication {
    // ...
    protected String getKeyScheme() {
      return "my.key.bindings"; //$NON-NLS-1$
    }
  }

Migrating from Riena 1.1 to 1.2

Riena 1.1 did not define any key bindings at all and was using the default scheme org.eclipse.ui.defaultAcceleratorConfiguration. When migrating to Riena 1.2 we recommend that you define your own scheme, which should reference the default scheme:

  <scheme
    id="my.key.bindings"
    name="My Key Bindings"
    parentId="org.eclipse.riena.ui.defaultBindings">
  </scheme>

Refer to the previous section for more details. Below are the recommended migration strategies.

If you use the standard scheme...

If you like to keep using the standard scheme, just modify getKeyScheme() in your SwtApplication subclass to return the String "org.eclipse.ui.defaultAcceleratorConfiguration". Note that you will inherit all key bindings defined by the Eclipse platform, which may not be ideal.

Alternatively you can define your own scheme as detailed above. Then reassign your own key bindings to that scheme, by changing the schemeId attribute of your key definitions.

If you use you own scheme...

If you use your own scheme, just modify getKeyScheme() in your SwtApplication subclass to return the appropriate scheme identifier.

Optionally, you may consider setting the parentId attribute of your scheme definition to "org.eclipse.riena.ui.defaultBindings". This way you will inherit the default key bindings provided by Riena.