2.4 Accelerators - SWT: The Standard Widget Toolkit

2.4 Accelerators

A menu accelerator, also called a keyboard shortcut, is an application-defined key sequence that invokes a menu item. It gives the same result as though the user had selected the item with the mouse. Accelerators are always associated with menu items. In the same manner as items in the menu bar, accelerators are global to the window. When the user types an accelerator key, regardless of the focus control, a menu item is invoked. When an accelerator is triggered, the corresponding keystroke is consumed.^[17]

^[17] Accelerators run before the key event is delivered to the control and on some platforms use the low-level window system keyboard classification engine to process the key, destructively modifying the key event in operating system event queue. This stops the focus control from ever seeing the keystroke.

2.4.1 Specifying an Accelerator

Accelerators are represented in SWT using an integer encoding. The encoding consists of zero or more modifiers and a single character or key code. An accelerator that contains only modifiers is invalid and cannot trigger a menu item.

Table 2.12 shows some sample accelerators.

Table 2.12. Sample Accelerators

Accelerator	Keystroke
SWT.CTRL + 'A'	The <Ctrl> and <A> keys
SWT.SHIFT + SWT.ARROW_UP	The <Shift> and <UpArrow> keys
SWT.MOD1 + 'S'	The primary modifier and <S> keys
SWT.MOD1 + SWT.MOD2 + 'B'	The primary and secondary modifier and <B> keys

Accelerators are assigned to menu items using the method MenuItem.setAccelerator(). The Tool Bars and Menus chapter contains a complete description of the MenuItem class.

setAccelerator(int accelerator) Sets the accelerator for the item to be an integer that is composed of zero or more modifier masks and a key value. For example, the accelerator SWT.CTRL + 'A' causes the menu item to be invoked when the user presses a Ctrl+A key sequence. The accelerator SWT.MOD1 + 'A' is invoked when the user presses the primary modifier key and the <A> key. Setting the accelerator to zero removes it.

getAccelerator() Returns the accelerator for the item. The integer encoding that was assigned in setAccelerator() is returned (or zero if an accelerator has never been set).

The following code fragment creates an accelerator for the primary modifier SWT.MOD1 and the 'A' character and associates it with a menu item.

item.setText("Select &All\tCtrl+A");

item.setAccelerator(SWT.MOD1 + 'A');

item.addListener(SWT.Selection, new Listener() {

    public void handleEvent(Event e) {

        System.out.println("The item was selected.");

    }

});

A perceptive reader should immediately notice a problem. The menu item text contains the string "Ctrl+A" but the accelerator is SWT.MOD1 + 'A'. Does this imply that this code fails on the Macintosh where the primary modifier is not the <Ctrl> key? To answer this question, you need to understand the difference between the accelerator and the accelerator text.

2.4.2 Specifying the Accelerator Text

To allow complete control over the label of a menu item, the accelerator text is specified independently of the accelerator.^[18] An embedded \t character indicates that the following string is the accelerator text. On most platforms, the accelerator text is right-aligned within the menu.

^[18] Eclipse uses this feature to implement multiple accelerator key sequences (made popular by the Emacs text editor). These are not supported natively on any platform where SWT is implemented.

When both an accelerator and accelerator text are provided, depending on the platform, SWT may override the accelerator text with more appropriate accelerator text. For example, on the Macintosh, the accelerator text "Ctrl+A" is ignored when the accelerator SWT.MOD1 + 'A' is specified. The correct accelerator text, a sequence of Macintosh specific glyphs, appears in the menu.

IMPORTANT: You Must Provide Accelerator Text on Every Platform. On every platform other than the Macintosh, the accelerator text is not overridden. This means that you need to provide the accelerator text, assuming that you are not on a Macintosh. It is possible that by the time this book goes to print, the Macintosh behavior will be implemented on the rest of the platforms, and this problem will be fixed.