Keyboard navigation for Swing

Contents
Swinging Duke

Swing's support for keyboard UI is designed with the following goals in mind:

All Swing widgets should support keyboard UI. It should be possible to use any Swing application without using the mouse at all.
Automatic keyboard action dispatching should meet the following criteria:
- There should be no need to write special code when writing a Swing-based application to support keyboard control.
- Very little code should be required to support keyboard input when writing a new widget.
- It should be possible for a widget to perform an action when a combination of keys is pressed, even if it does not have the focus.
Support for keyboard UI should include a public focus manager with the following features:
- The public focus manager should be pluggable.
- The default implementation of the public focus manager should provide a tab order matching the locale's "reading order."
- A widget should be able to change the default order by returning its next widget.
- There should be a way to exit from a widget -- for example, a text widget should implement some actions for Tab and Shift-Tab.
- It should be possible to navigate within a group of objects using the arrow keys.
- It should be possible for a container to hide its children from the focus manager.

Current AWT Keyboard Support

A component can request the focus by calling requestFocus().
A listener can receive some events when a component gets or loses the focus.
A listener can receive an event when a key is pressed.
Tab . / Shift-Tab can be used to change the focus from widgets to widgets, but there is no way to change this behavior.
A widget can determine whether it can be traversed by the focus.

Automatic Keyboard Action Dispatching

The best way to make any Swing-based application usable without a mouse is to make sure that no additional work is required from the application developer to make the application support keyboard UI. This really means that widgets developed in Swing should be able by themselves to negotiate with the system, declaring their favorite keyboard equivalencies and when these keyboard equivalencies are available. For some widgets, such as menus, the application developer will have to define the accelerators that make sense. For widgets such as buttons, the application developer will have to specify which button is the default button. These features are really widget properties and will be easy to handle inside an application builder.

From a widget developer's point of view, it should be very easy to support keyboard input. For a given feature, the code should be the same whether the input device that has triggered the feature is a keyboard or a mouse. This means that the input device that has triggered the feature is hidden from the code that actually implements the feature. One way to do this in Swing is to encapsulate the feature inside a Action object. Action objects can also answer the needs of another requirement: It is useful for a keyboard UI system to be able to discover whether a widget can perform an action. If the widget cannot perform the action, perhaps another widget that supports the same combination of keys should perform its action.

Assuming that any feature accessible from the keyboard has been factored into a set of Action, the last piece of code that should be implemented to drive a widget from the keyboard is the code that actually maps a combination of keys to an action. Since it is possible for a widget to perform an action even if it does not have the focus (think about a keyboard mnemonic or a menu), and because it is desirable to avoid requiring every single widget to provide the same kind of code to check the key event to trigger the right action, a solution is to have a registry system that handles the mapping.

Keyboard Action Registry

JComponent provides a set of methods that allows ComponentUI implementers to register and unregister an action for a set of keys. Also JComponent contains the implementation of the keyboard action registry.

The keyboard action registry's responsibility is to know about all the keys that can be handled by a tree of component and to invoke the right action when a set of keys is pressed. When a ComponentUI instance installs its UI, it registers its actions and keys. When the ComponentUI instance removes its UI, it removes its actions. Actual bindings are stored into the JComponent's properties.

Registering an action into the registry looks like this:

    registerKeyboardAction(Action anAction, 
		KeyStroke aKeyStroke, int aCondition)

The anAction parameter is the action that should be invoked when the proper keys are pressed and aCondition is verified. The aKeyStroke parameter describes the key(s) that will trigger the action. KeyStroke can store whether keys should be pressed or released for the action to be invoked. The aCondition parameter is an int value that describes when the action should be invoked. Its value can be:

WHEN_FOCUSED: The action should be invoked only when the component has the focus. For example, this option is useful to have the space bar causing the focused button to get pressed.
WHEN_FOCUSED_COMPONENT_PARENT: The action should be invoked when the component has the focus or is an ancestor of the focused component.
WHEN_IN_FOCUSED_WINDOW: The action should be invoked when the component has the focus or when it is in the window that contains the focus. For example, this condition is useful to implement mnemonics (labels selecting a component when the right key stroke occurs) or to make the default button pressed when return is pressed. The action will not be invoked if the focused widget did register another action for the same set of keys.
ALWAYS: The action should be invoked if a KeyEvent matching the key stroke occurs and no other component is claiming the same key stroke.

Invoking Actions

When an action is invoked, the keyboard registry determines what component should carry out the action by examining components that could handle the action in the following order:

The focus component that has the focus.
The first component on the path between the focused parent and the component tree root.
All components in the focused component tree, excluding the focused component, and including the path between the root and the focused component.
Any other action registered with the condition ALWAYS.

The following pseudo-code illustrates how this sequence of actions takes place:

Input: a KeyEvent KE

If the focused component has some registered actions and
        one of these registered action A has been registered with (charKey,modifiers)
        that matches KE,
        do
        if A is enabled, invoke A and stop
        done
else for all components C on the path from the focused component's
        parent to the root of the component tree (both included)
        do
        if C has registered an action A with a (charKey,modifiers) that matches KE and 
                a condition equals to WHEN_IN_FOCUSED_WINDOW or ALWAYS
                do
                if A is enabled, invoke A and stop
                done
        done

for all components C in the focused component tree excluding the focused component
    do
    if C has registered an action A with a (charCode,modifiers) that matches KE and a condition equals
         to WHEN_IN_FOCUSED_WINDOW or ALWAYS,
        do
        if A is enabled invoke A and stop
        done
    done

Finally, if an action A has been registered with a (charCode,modifiers) that matches

KE and a condition equals to ALWAYS
     if A is enabled invoke A.

Integration with AWT 1.1

The basic idea is that JComponent overloads processKeyEvent() in the following way:

public void processKeyEvent(KeyEvent anEvent) { 
    super.processKeyEvent(anEvent); 
    if(anEvent.isConsumed()) 
        return; 
  
    /*** Give the keyboard UI registry system a chance to process the key event ***/ 
    if(anEvent.getID() == KeyEvent.KEY_PRESSED) { 
        processKeyBindings(anEvent); 
    } 
}

It is the responsibility of all ComponentUI objects to mark the event consumed if the event has been consumed.

The Keyboard Registry API

This is the proposed API for the keyboard registry:

public class JComponent {
    .... 
  /** Register a new keyboard action. 
      *  anAction will be invoked if a key event matching aKeyStroke 
      * occurs and aCondition is verified. aCondition can currently be: 
      * <UL> 
      * <LI> WHEN_FOCUSED:  the action will be invoked only when the receiving 
      * JComponent has the focus. 
      * <LI> WHEN_IN_FOCUSED_WINDOW: the action will be invoked when the 
      * receiving JComponent has the focus or is in the window that contains the focused container. 
      * </UL> 
      * If an action has already been registered for the receiving container, with the same key stroke, 
      * anAction will replace the action. 
      */ 
    public void registerKeyboardAction(Action anAction,KeyStroke aKeyStroke,int aCondition); 
  
   /** Unregister a keyboard action given a KeyStroke **/ 
    public void unregisterKeyboardAction(KeyStroke aKeyStroke); 
  
    /** Return the registered key strokes **/ 
    public KeyStroke[] getRegisteredKeyStrokes();
    /** Return the condition that has been registered with a key stroke **/ 
    public int getConditionForKeyStroke(KeyStroke aKeyStroke);
    /** Return the action that has been registered with a key stroke **/ 
    public Action getActionForKeyStroke(KeyStroke aKeyStroke);
    /** Unregister all keyboard actions **/ 
    public void resetKeyboardActions(); 
    .... 
}

Examples

The following examples illustrate two ways in which you might use Swing's keyboard UI:

First Example: A ListBox

The first example shows how arrow keys could be used to move the selection in a list box up and down. In the list box's ComponentUI:

void intallUI(JComponent c) { 
    /** Install sub-components **/ 
    ...
    /** Install event listeners **/ 
    ...
    /** Install key bindings  scrollDownAction and scrollUpAction are defined actions **/ 
   c.registerKeyboardAction(scrollDownAction, 
                                            KeyStroke.getKeyStroke(KeyEvent.DOWN, 0), 
                                            WHEN_FOCUSED); 
   c.registerKeyboardAction(scrollUpAction, 
                                            KeyStroke.getKeyStroke(KeyEvent.UP,0), 
                                            WHEN_FOCUSED); 
}
void deinstallUI(JComponent c) { 
    /** Remove sub-components and event listeners **/ 
    ... 
    /** Remove key bindings **/ 
    c.resetKeyboardActions(); 
}

Second Example: A Label

In this example, a label needs to know when Control + A is pressed so its associated JTextField can get the focus. In The label's ComponentUI:

void intallUI(JComponent c) { 
    /** Install sub-components **/ 
    ...
    /** Install event listeners **/ 
    ...
    /** Install key bindings  setFocus is a defined action that causes the associated container to be focused **/ 
   c.registerKeyboarAction(setFocus, 
                                          KeyStroke.getKeyStroke('a',InputEvent.CTRL_MASK), 
                                          WHEN_IN_FOCUSED_WINDOW); 
}
void deinstallUI(JComponent c) { 
    /** Remove sub-components and event listeners **/ 
    ... 
    /** Remove key bindings **/ 
    c.resetKeyboardActions();
}