The Java Tutorials have been written for JDK 8. Examples and practices described in this page don't take advantage of improvements introduced in later releases and might use technology no longer available.
See Java Language Changes for a summary of updated language features in Java SE 9 and subsequent releases.
See JDK Release Notes for information about new features, enhancements, and removed or deprecated options for all JDK releases.
Key events indicate when the user is typing at the keyboard. Specifically, key events are fired by the component with the keyboard focus when the user presses or releases keyboard keys. For detailed information about focus, see How to Use the Focus Subsystem.
To define special reactions to particular keys, use key bindings instead of a key listener. For further information, see How to Use Key Bindings.
Notifications are sent about two basic kinds of key events:
The first kind of event is called a key-typed event. The second kind is either a key-pressed or key-released event.
In general, you react to only key-typed events unless you need to know when the user presses keys that do not correspond to characters. For example, to know when the user types a Unicode character — whether by pressing one key such as 'a' or by pressing several keys in sequence — you handle key-typed events. On the other hand, to know when the user presses the F1 key, or whether the user pressed the '3' key on the number pad, you handle key-pressed events.
To fire keyboard events, a component must have the keyboard focus.
To make a component get the keyboard focus, follow these steps:
isFocusable
method returns true
. This state allows the component to receive the focus. For example, you can enable keyboard focus for a JLabel
component by calling the setFocusable(true)
method on the label.requestFocusInWindow
method when the component is clicked.The focus subsystem consumes focus traversal keys, such as Tab and Shift Tab. If you need to prevent the focus traversal keys from being consumed, you can call
component.setFocusTraversalKeysEnabled(false)
on the component that is firing the key events. Your program must then handle focus traversal on its own. Alternatively, you can use the
KeyEventDispatcher
class to pre-listen to all key events. The
focus page has detailed information on the focus subsystem.
You can obtain detailed information about a particular key-pressed event. For example, you can query a key-pressed event to determine if it was fired from an action key. Examples of action keys include Copy, Paste, Page Up, Undo, and the arrow and function keys. You can also query a key-pressed or key-released event to determine the location of the key that fired the event. Most key events are fired from the standard keyboard, but the events for some keys, such as Shift, have information on whether the user pressed the Shift key on the left or the right side of the keyboard. Likewise, the number '2' can be typed from either the standard keyboard or from the number pad.
For key-typed events you can obtain the key character value as well as any modifiers used.
You should not rely on the key character value returned from getKeyChar
unless it is involved in a key-typed event.
The following example demonstrates key events. It consists of a text field that you can type into, followed by a text area that displays a message every time the text field fires a key event. A button at the bottom of the window lets you clear both the text field and text area.
You can find the example's code in
KeyEventDemo.java
. Here is the demo's key event handling code:
public class KeyEventDemo ... implements KeyListener ... { ...//where initialization occurs: typingArea = new JTextField(20); typingArea.addKeyListener(this); //Uncomment this if you wish to turn off focus //traversal. The focus subsystem consumes //focus traversal keys, such as Tab and Shift Tab. //If you uncomment the following line of code, this //disables focus traversal and the Tab events //become available to the key event listener. //typingArea.setFocusTraversalKeysEnabled(false); ... /** Handle the key typed event from the text field. */ public void keyTyped(KeyEvent e) { displayInfo(e, "KEY TYPED: "); } /** Handle the key-pressed event from the text field. */ public void keyPressed(KeyEvent e) { displayInfo(e, "KEY PRESSED: "); } /** Handle the key-released event from the text field. */ public void keyReleased(KeyEvent e) { displayInfo(e, "KEY RELEASED: "); } ... private void displayInfo(KeyEvent e, String keyStatus){ //You should only rely on the key char if the event //is a key typed event. int id = e.getID(); String keyString; if (id == KeyEvent.KEY_TYPED) { char c = e.getKeyChar(); keyString = "key character = '" + c + "'"; } else { int keyCode = e.getKeyCode(); keyString = "key code = " + keyCode + " (" + KeyEvent.getKeyText(keyCode) + ")"; } int modifiersEx = e.getModifiersEx(); String modString = "extended modifiers = " + modifiersEx; String tmpString = KeyEvent.getModifiersExText(modifiersEx); if (tmpString.length() > 0) { modString += " (" + tmpString + ")"; } else { modString += " (no extended modifiers)"; } String actionString = "action key? "; if (e.isActionKey()) { actionString += "YES"; } else { actionString += "NO"; } String locationString = "key location: "; int location = e.getKeyLocation(); if (location == KeyEvent.KEY_LOCATION_STANDARD) { locationString += "standard"; } else if (location == KeyEvent.KEY_LOCATION_LEFT) { locationString += "left"; } else if (location == KeyEvent.KEY_LOCATION_RIGHT) { locationString += "right"; } else if (location == KeyEvent.KEY_LOCATION_NUMPAD) { locationString += "numpad"; } else { // (location == KeyEvent.KEY_LOCATION_UNKNOWN) locationString += "unknown"; } ...//Display information about the KeyEvent... } }
The corresponding adapter class is
KeyAdapter
.
Method | Purpose |
---|---|
keyTyped(KeyEvent) | Called just after the user types a Unicode character into the listened-to component. |
keyPressed(KeyEvent) | Called just after the user presses a key while the listened-to component has the focus. |
keyReleased(KeyEvent) | Called just after the user releases a key while the listened-to component has the focus. |
The KeyEvent
class inherits many useful methods from the
InputEvent
class, such as getModifiersEx
, and a couple of useful methods from the
ComponentEvent
and
AWTEvent
classes. See the InputEvent Class table in the mouse listener page for a complete list.
Method | Purpose |
---|---|
int getKeyChar() | Obtains the Unicode character associated with this event. Only rely on this value for key-typed events. |
int getKeyCode() | Obtains the key code associated with this event. The key code identifies the particular key on the keyboard that the user pressed or released. The KeyEvent class defines many key code constants for commonly seen keys. For example, VK_A specifies the key labeled A, and VK_ESCAPE specifies the Escape key. |
String getKeyText(int) String getKeyModifiersText(int) |
Return text descriptions of the event's key code and modifier keys, respectively. |
int getModifiersEx() String getModifiersExText(int modifiers) |
Return the extended modifiers mask for this event. There are methods inherited from the InputEvent class. Extended modifiers represent the state of all modal keys. The getModifiersExText method returns a string describing the extended modifier keys and mouse buttons. Since the getModifiersEx and getModifiersExText methods provide more information about key events, they are preferred over the getKeyText or getKeyModifiersText methods. |
boolean isActionKey() | Returns true if the key firing the event is an action key. Examples of action keys include Cut, Copy, Paste, Page Up, Caps Lock, the arrow and function keys. This information is valid only for key-pressed and key-released events. |
int getKeyLocation() | Returns the location of the key that fired this event. This provides a way to distinguish keys that occur more than once on a keyboard, such as the two shift keys, for example. The possible values are KEY_LOCATION_STANDARD , KEY_LOCATION_LEFT , KEY_LOCATION_RIGHT , KEY_LOCATION_NUMPAD , or KEY_LOCATION_UNKNOWN . This method always returns KEY_LOCATION_UNKNOWN for key-typed events. |
The following table lists the examples that use key listeners.
Example | Where Described | Notes |
---|---|---|
KeyEventDemo |
This section | Reports all key events that occur on a text field to demonstrate the circumstances under which key events are fired. |