Section 6.6. Key Bindings

6.6. Key Bindings

Both workbench actions and editor actions can have accelerator keys associated with them (see Section 7.3.5, Keyboard actions, on page 288 for how to programmatically associate accelerator keys). Originally, the accelerator was specified as part of the action declaration, but that approach did not prevent multiple actions from declaring the same accelerator and did not allow the user to change key bindings. The new approach involves associating actions and key bindings with commands and grouping those commands into categories (see Figure 6-11). In addition, each command has a scope indicating when it will be available to the user, and it is part of a configuration so that the user can select between different configurations to get different key bindings (e.g., Emacs key bindings vs. Eclipse key bindings).

Figure 6-11. Key binding declaration.

6.6.1. Categories

Categories are used to group commands for presentation to the user. Categories appear in the General > Keys preference page as the first column in the table on the View tab and the Command / Category drop-down list on the Modify tab. To add a key binding for the Add to Favorites action, first you need to define a category. Create a new org.eclipse.ui.commands extension (see Section 6.2.1, Defining a workbench window menu, on page 209 for an example of how extensions are added), then right-click and select New > category. Enter the following attributes for the new category:

description "Favorites Commands"

A description of the commands contained in the category.

id "com.qualityeclipse.favorites.commands"

The unique identifier for the category.

name "Favorites"

The text displayed to the user as the category name.

6.6.2. Commands

Commands are contained in categories and have key bindings associated with them. Actions then reference commands to associate key bindings. To add a command for the Add to Favorites action, right-click on the org.eclipse.ui.commands extension and select New > command. Enter the following attributes for the new command.

categoryId "com.qualityeclipse.favorites.commands"

The identifier for the category that contains the command.

description "Add the selection to the Favorites"

A description of the command.

id "com.qualityeclipse.favorites.commands.addToFavoritesView"

The unique identifier for the command.

name "Add to Favorites View"

The human-readable name for the command.

6.6.3. Key bindings

Commands do not reference key bindings; rather, key bindings are declared separately and reference commands. This allows for multiple key bindings to be associated with the same command. For example, the default accelerator for saving the contents of a file is Ctrl+S, but after switching to the Emacs configuration, the save accelerator becomes Ctrl+X Ctrl+S.

To add a key binding for the Add to Favorites action, create a new org.eclipse.ui.bindings extension (see Section 6.2.1, Defining a workbench window menu, on page 209 for an example of how extensions are added), then right-click and select New > key. Enter the following attributes for the new key binding. After completion, the Favorites key binding appears in the Keys preference page (see Figure 6-12).

Figure 6-12. Keys preference page showing Favorites key binding.

commandId "com.qualityeclipse.favorites.commands.addToFavoritesView"

The command triggered by the key binding.

contextId "org.eclipse.ui.textEditorScope"

The context in which the key binding is available to the user. Some of the predefined scopes include:

org.eclipse.ui.contexts.windowthe workbench window

org.eclipse.ui.textEditorScopetext editors

org.eclipse.ui.contexts.dialogdialogs

org.eclipse.jdt.ui.javaEditorScopejava editors

org.eclipse.debug.ui.debuggingdebugging views

org.eclipse.debug.ui.consoleconsole view

New contexts can be defined using the org.eclipse.ui.contexts extension point. If contextId is not specified, then it defaults to org.eclipse.ui.contexts.window.

schemeId "org.eclipse.ui.defaultAcceleratorConfiguration"

The scheme containing the key binding. Typically, key bindings are added to the default Eclipse configuration, but alternate key bindings, such as "org.eclipse.ui.emacsAcceleratorConfiguration," can be added to other configurations. New schemes can be defined by declaring a new scheme element in the org.eclipse.ui.bindings extension.

sequence "Ctrl+Shift+A"

The key sequence to assign to the command. Key sequences consist of one or more keystrokes, where a keystroke consists of a key on the keyboard, optionally pressed in combination with one or more of the following modifiers: Ctrl, Alt, Shift, Command, M1 (mapped to Ctrl or Command as appropriate on that platform), M2 (Shift) and M3 (Alt or Option as appropriate on that platform). Keystrokes are separated by spaces, and modifiers are separated by "+" characters. For example a key sequence of holding down the control key while pressing X followed by holding down the control key while pressing S would be "Ctrl+X Ctrl+S". Special keys are represented by ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, BREAK, BS, CAPS_LOCK, CR, DEL, END, ESC, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, FF, HOME, INSERT, LF, NUL, NUM_LOCK, NUMPAD_0, NUMPAD_1, NUMPAD_2, NUMPAD_3, NUMPAD_4, NUMPAD_5, NUMPAD_6, NUMPAD_7, NUMPAD_8, NUMPAD_9, NUMPAD_ADD, NUMPAD_DECIMAL, NUMPAD_DIVIDE, NUMPAD_ENTER, NUMPAD_EQUAL, NUMPAD_MULTIPLY, NUMPAD_SUBTRACT, PAGE_UP, PAGE_DOWN, PAUSE, PRINT_SCREEN, SCROLL_LOCK, SPACE, TAB, and VT. There are some alternative names for some common special keys. For example, both ESC and ESCAPE are the same, and CR, ENTER, and RETURN are all the same.

Other key binding attributes that are not used in the Favorites example include:

locale An optional attribute indicating that the key binding is only defined for a specified locale. Locales are specified according to the format declared in java.util.Locale.

platform An optional attribute indicating that the key binding is only defined for the specified platform. The possible values of the platform attribute are the set of the possible values returned by org.eclipse.swt.SWT.getPlatform().

6.6.4. Associating commands with actions

The final step in defining an accelerator for the Favorites example involves modifying the editor action defined in Section 6.5.5, Defining an editor top-level action, on page 248 to reference the new command created in Section 6.6.2, Commands, on page 252.

Select the editor action in the plug-in manifest and modify the definitionId attribute to have the value "com.qualityeclipse.favorites.commands.addToFavoritesView" so that the action now references the new command and associated key binding.

6.6.5. Keyboard accessibility

The keyboard can be used to select menu items in the workbench window. For example, if you press and release the Alt key and then press and release F (or press Alt+F), you will see the workbench window File menu drop down. If you look closely, you will see an underscore under at most one letter in each menu label and menu item label. When you are in this menu selection mode, pressing the letter with the underscore will activate that menu or menu command. Under some platforms, such as Windows XP, these underscores are not visible unless you activate menu selection mode.

In your plug-in manifest, you can specify which character in a menu's or menu item's label should have an underscore by preceding that character with the "&" character. For example, in the following declaration, the "&" before the letter "r" in the word "Favorites" causes that letter to have an underscore when you activate the menu selection mode (see Figure 6-13).

Figure 6-13. Plug-in manifest editor showing & for keyboard accessibility.

When viewing the XML for this same declaration, the & character appears as & because the & character has special meaning in XML.

<action        icon="icons/sample.gif"        label="Open Favo&rites View"    menubarPath="com.qualityeclipse.favorites.workbenchMenu/content"    style="push"    toolbarPath="Normal/additions"    tooltip="Open the Favorites view in the current workbench page"/> 

If you use this same approach with the Favorites menu declaration (see Section 6.2.1, Defining a workbench window menu, on page 209), you can use a sequence of keystrokes to open the Favorites view without touching the mouse.

• Press and release the Alt key to enter menu selection mode.

• Press and release "v" to get the Favorites menu to drop down.

• Press and release "r" to activate the Open Favorites View action.

  or

• Press Alt+V to get the Favorites menu to drop down.

• Press and release "r" to activate the Open Favorites View action.

Ready for Rational Software

Starting with this chapter, we will list IBM's relevant RFRS certification requirements and briefly discuss what is required to pass each test. We will also endeavor to make sure that the ongoing Favorites example complies with any relevant requirements. The rule definitions themselves are quoted with permission from IBM's official Ready for IBM Rational Software Integration Requirements document. To obtain more information about the RFRS program, see Appendix B, Ready for Rational Software, or visit the IBM Web site at www.developer.ibm.com/isv/rational/readyfor.html.