KEYMAPS

You may have never considered the details of what happens
when you type characters into a text area. But this process is
important to understand, especially if you're trying to customize 
how an application handles input from the keyboard.


Swing text components use what are called "keymaps". A keymap maps 
keyboard keys to resulting actions. For example, the Backspace key 
deletes the character preceding the text caret. Or the Delete 
key removes the character after the caret. By contrast, simply typing 
a character such as "z" inserts that character as text content.

It's possible to override the default keymap with your own, as this
example illustrates:

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

    public class KeyMap {
        public static void main(String args[]) {
            JFrame frame = new JFrame("Keymap demo");
            frame.addWindowListener(new WindowAdapter() {
                public void windowClosing(WindowEvent e) {
                    System.exit(0);
                }
            });

            final JTextPane pane = new JTextPane();
            pane.setPreferredSize(new Dimension(600, 400));

            Keymap km = pane.getKeymap();
            KeyStroke ks = KeyStroke.getKeyStroke(
                KeyEvent.VK_Z, Event.CTRL_MASK);
            Action act = new TextAction("Ctrl-Z") {
                public void actionPerformed(ActionEvent e) {
                    pane.replaceSelection("ZZZ");
                }
            };
            km.addActionForKeyStroke(ks, act);

            JPanel panel = new JPanel();
            panel.add("Center", pane);

            frame.getContentPane().add(panel);
            frame.pack();
            frame.setVisible(true);
        }
    }

This demo overrides the default action for Ctrl-Z (which is to do
nothing). With this override in place, Ctrl-Z inserts "ZZZ" into
the text pane. In other words, a keystroke (a combination of a key 
and possibly a modifier like Ctrl) has been added to the keymap. 
And an action has been specified for the keystroke such that 
replaceSelection is called to insert text or replace selected text  
with new text.

This feature can be used in an application such as a word processor,
where the user binds arbitrary text strings to keys.

There are several interesting points to note about keymaps. One is
that a default keymap is set up for you when you use JTextPane. It
contains bindings for keystrokes such as Ctrl-X (cut selected text).
The example above changes this keymap by adding a keystroke/action
pair to it. This modification will be reflected in all text panes
in the application. So if you don't want to disturb the default
keymap, you can create your own.

If you set a keymap to null, as in:

    pane.setKeymap(null);

then keyboard input to the text pane is disabled.

There is also the concept of parent and child keymaps. If a
keystroke is not resolved in a child keymap, then it is searched for
in the parent. An application might, for example, create its own
keymap, and use the default keymap as a parent. The parent keymap 
is used to resolve keystrokes not found in the application-specific 
keymap. In the example above, Ctrl-Z might be resolved in a keymap 
that has been created in the application, with Ctrl-X resolved in 
the default parent keymap.