• Purpose:
  • Allow JComponent objects to respond to the keyboard
• Uses in the Java API:
  • Mnemonics (AbstractButton, JLabel, and JTabbedPane)
  • Accelerators (JMenutItem)

• Advantages of Key Bindings:
  • Use the command pattern (i.e., Action objects) so are more maintainable
  • Don't require the JComponent to have the focus
  • Make it easy to change bindings
• Advantages of Key Listeners:
  • Provide lower-level access (e.g., to presses and releases)

• KeyStroke :
  • An encapsulation of a key action (including modifiers like Alt, Ctrl, Meta, and Shift) on a keyboard (or equivalent input device)
• InputMap :
  • Maps/binds a KeyStroke to an Object (usually a String)
• ActionMap :
  • Maps/binds an Action to an Object (usually a String)

• One ActionMap Object:
  • Maps/binds an Action to a String that has been mapped/bound to a KeyStroke)
• Three InputMap Objects:
  • One for when the JComponent has the focus
  • One for when the JComponent contains (or is) the component that has the focus
  • One for when the JComponent is in the window that has the focus

• The Steps:
  1. The user types a key.
  2. One or more InputMap objects is searched for a matching binding
  3. When a binding is found the ActionMap is searched for a matching Action
  4. If the Action is enabled it's actionPerformed() method is called (and the process is terminated), otherwise the search continues
• InputMap Search Order:
  1. The focused component's WHEN_FOCUSED map
  2. The focused component's WHEN_ANCESTOR_OF_FOCUSED_COMPONENT map
  3. The WHEN_ANCESTOR_OF_FOCUSED_COMPONENT maps of enabled containers (in order)
  4. The WHEN_IN_FOCUSED_WINDOW maps (in no particular order)

An ArrowPad

javaexamples/keybindings/ArrowPad.java

import java.awt.*;
import java.awt.event.*;
import javax.swing.*;

/**
 * A virtual arrow pad that responds to wasd key presses.
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
public class ArrowPad extends JPanel
{
    JButton      down, left, right, up;
    
    /**
     * Default Constructor.
     */
    public ArrowPad()
    {
        super();
        ArrowAction action;        

        down  = new JButton("\u2193");
        left  = new JButton("\u2190");
        right = new JButton("\u2192");
        up    = new JButton("\u2191");

        down.setActionCommand("DOWN");        
        left.setActionCommand("LEFT");        
        right.setActionCommand("RIGHT");        
        up.setActionCommand("UP");        

        // The same Action is used here for all of the JButton
        // objects. One could, instead, have a different Action for
        // each.
        action = new ArrowAction();
        down.addActionListener(action);
        left.addActionListener(action);
        right.addActionListener(action);
        up.addActionListener(action);

        setupKeyBindings();
        performLayout();
    }


    /**
     * Perform the necessary steps to layout this ArrowPad.
     */
    private void performLayout()
    {
        Box         bottom, main, top;

        setLayout(new FlowLayout(FlowLayout.CENTER));

        main   = Box.createVerticalBox();
        bottom = Box.createHorizontalBox();
        top    = Box.createHorizontalBox();
        
        top.add(up);

        bottom.add(left);
        bottom.add(down);
        bottom.add(right);

        main.add(top);
        main.add(bottom);
        
        add(main);
    }


    /**
     * Setup the key bindings to use.
     *
     * In this implementation, the wasd keys correspond to the virtual
     * up, left, down, and right buttons. One could, alternatively or
     * additionally, use the arrow keys and/or the arrow keys on the
     * numeric keypad.
     */
    private void setupKeyBindings()
    {
        ActionMap actionMap;        
        InputMap  inputMap;

        actionMap = this.getActionMap();
        inputMap  = this.getInputMap(JComponent.WHEN_IN_FOCUSED_WINDOW);
        
        inputMap.put(KeyStroke.getKeyStroke(KeyEvent.VK_W, 0), "w");
        actionMap.put("w", new ClickAction(up));

        inputMap.put(KeyStroke.getKeyStroke(KeyEvent.VK_A, 0), "a");
        actionMap.put("a", new ClickAction(left));

        inputMap.put(KeyStroke.getKeyStroke(KeyEvent.VK_S, 0), "s");
        actionMap.put("s", new ClickAction(down));

        inputMap.put(KeyStroke.getKeyStroke(KeyEvent.VK_D, 0), "d");
        actionMap.put("d", new ClickAction(right));
    }
}
        

The Action for the JButton Objects

javaexamples/keybindings/ArrowAction.java

import java.awt.event.*;
import javax.swing.*;

/**
 * A placeholder for an Action associated with arrow buttons.
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
public class ArrowAction extends AbstractAction
{
    /**
     * Handle an actionPerformed() message (required by AbstractAction).
     * Specifically, output the action command on the console.
     *
     * @param evt  The ActionEvent that generated the message.
     */
    public void actionPerformed(ActionEvent evt)
    {
        System.out.println(evt.getActionCommand());
    }
}
        

The Action for the ActionMap

javaexamples/keybindings/ClickAction.java

import java.awt.event.*;
import javax.swing.*;

/**
 * A ClickAction object can be used to programmatically
 * generate a button click.
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
public class ClickAction extends AbstractAction
{
    private static final int    DELAY = 50; // millis
    
    private AbstractButton       button;
    

    /**
     * Explicit Value Constructor.
     *
     * @param button   The button to click
     */
    public ClickAction(AbstractButton button)
    {
        super();
        this.button = button;
    }

    /**
     * Handle an actionPerformed() message (required by AbstractAction).
     * Specifically, give the focus to and click the button.
     *
     * @param evt  The ActionEvent that generated the message.
     */
    public void actionPerformed(ActionEvent evt)
    {
        button.grabFocus();
        // Programmatically perform a "click". This does the same
        // thing as if the user had pressed and released the button.
        //The button stays visually "pressed" for DELAY milliseconds.
        button.doClick(DELAY);
    }
}