Revision as of 15:48, 6 October 2009

Riena 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 predefined 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

In addition to the scheme a key binding also references a Context, which assigns this key binding to a specific situation within the 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 context. If you define your own, you will most likely want to use this context as well.

You will find that the predefined contexts, listed above, are enough to cover all but the most advanced use cases. So you likely will not need to define your own contexts. If you do, note 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, which 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'. This gives you a double advantage: you inherit the standard key bindings defined by Riena (see prev. section) and you are free to override any predefined key bindings with your own definition.

To accomplish this use the org.eclipse.ui.bindings extension point, to define your own scheme and then assign any new key bindings to this scheme:

  <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">
      </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"
            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$
    }
  }

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.

Migrating from Riena 1.1 to 1.2

Riena 1.1 did not define any keybindings and was using the default scheme org.eclipse.ui.defaultAcceleratorConfiguration. When migrating to Riena 1.2 you have several choices: (a) define your own scheme to extend Riena's standard scheme (recommended), (b) use Riena's standard scheme, (c) continue using the scheme you were using before.

TDB