Designing Event-Driven Java GUI Programs

A graphical Java program often has many components on screen at once: text fields, buttons, panels, and more. When you press a key, the program must decide which of those components should hear about it. Mouse input solves this problem with a simple rule. A click belongs to whichever component sits under the cursor. Keyboard input does not work that way, because pressing a key does not depend on where the pointer is.

This article follows a single question through a small event-driven program: when a key goes down, comes back up, or produces a character, which listener method runs, and what information does the event object carry? By the end you should be able to predict the event counts for one keystroke and track down a handler that reads the wrong event type or the wrong value.

Input focus is the rule that answers the question of where keyboard input goes. At any moment, exactly one interface element on the screen holds input focus, and every keyboard event is directed to that element. Focus is not determined by the pointer. It belongs to one component at a time, and that component is the one whose registered listeners receive the key events.

Read the diagram from left to right. A key press is not sent to a location on the screen. It is sent to the focused component. Only that component's KeyEvent object is created and delivered to the listeners registered with it. The component that lost focus receives no key events until it regains focus. When you trace a keyboard bug, the question is therefore never only what key was pressed, but which component was holding focus at that moment.

A keyboard-handling object needs three roles to work. The KeyEvent class describes the event itself. A listener object must implement the KeyListener interface, which requires the three methods keyPressed, keyReleased, and keyTyped. Finally, the listener must be registered with the component that will generate the events, written as component.addKeyListener(listener). That component is the one holding focus when the keys are pressed. The component and the listener can be the same object.

Before reading the trace, decide what you expect. Suppose you want to type an uppercase A by holding Shift, pressing A, and then releasing both keys. The source says that an uppercase A can generate two keyPressed events, two keyReleased events, and one keyTyped event. The sequence below shows how those events come about, one step at a time.

Notice that the two keyPressed events come from two physical keys, Shift and A, and the two keyReleased events come from the same two keys going up. Only one keyTyped event appears, because keyTyped reports the character produced, and only one uppercase A appears on the screen. Pressing Shift by itself does not type a character, so Shift contributes to keyPressed and keyReleased but never to keyTyped. This is why the source describes keyTyped as tied to the character, while keyPressed and keyReleased are tied to physical keys.

The three KeyListener methods answer three different questions. keyPressed tells you that a physical key went down. keyReleased tells you that a physical key came back up. keyTyped tells you which character was produced, and a single character may come from several key presses. Use keyTyped when you need the character that appeared on screen. Use keyPressed and keyReleased when you need to notice that a key such as Shift has changed state.

The class above is only the listener. To receive events it must be registered with the focused component, for example by calling component.addKeyListener(watcher). If the component never holds focus, none of these methods will run for keys pressed while another component is active.

Every key has an integer code, and the event parameter carries the code of the key pressed or released. You obtain it with evt.getKeyCode(). You do not need to memorize a table of numbers, because KeyEvent provides a named constant for each key, such as KeyEvent.VK_SHIFT. The arrow keys follow the same pattern with KeyEvent.VK_LEFT, KeyEvent.VK_RIGHT, KeyEvent.VK_UP, and KeyEvent.VK_DOWN. The VK prefix stands for Virtual Keyboard. Different keyboards send different raw codes, but Java translates them into its own virtual codes, so the same constants work across keyboards and platforms.

A key code tells you which key moved, but it does not tell you which character appeared on the screen. For that, call evt.getKeyChar() inside keyTyped. The method returns a char, so the result can be compared with character literals or stored as a single character.

The two methods disagree for Shift. getKeyCode() identifies the Shift key on keyPressed and keyReleased, while keyTyped never fires for Shift alone, so there is no character to read. For the letter A, getKeyCode() identifies the key that moved, and getKeyChar() inside keyTyped returns the character that appeared. A handler that expects a character from a key code, or a key code from a keyTyped character, will therefore read the wrong value even though the program compiles.

When a handler prints an unexpected result, check the event type first, then the value it reads. If the wrong method is handling the key, the divergence is in the event type. If the right method runs but the value is wrong, the divergence is in the value. If nothing runs at all, check whether the component holding focus has the listener registered.