This low-level event is generated by a component object (such as a text field) when a key is pressed, released, or typed. The event is passed to every KeyListener
or KeyAdapter
object which registered to receive such events using the component's addKeyListener
method. (KeyAdapter
objects implement the KeyListener
interface.) Each such listener object gets this KeyEvent
when the event occurs.
"Key typed" events are higher-level and generally do not depend on the platform or keyboard layout. They are generated when a Unicode character is entered, and are the preferred way to find out about character input. In the simplest case, a key typed event is produced by a single key press (e.g., 'a'). Often, however, characters are produced by series of key presses (e.g., 'shift' + 'a'), and the mapping from key pressed events to key typed events may be many-to-one or many-to-many. Key releases are not usually necessary to generate a key typed event, but there are some cases where the key typed event is not generated until a key is released (e.g., entering ASCII sequences via the Alt-Numpad method in Windows). No key typed events are generated for keys that don't generate Unicode characters (e.g., action keys, modifier keys, etc.).
The getKeyChar method always returns a valid Unicode character or CHAR_UNDEFINED. Character input is reported by KEY_TYPED events: KEY_PRESSED and KEY_RELEASED events are not necessarily associated with character input. Therefore, the result of the getKeyChar method is guaranteed to be meaningful only for KEY_TYPED events.
For key pressed and key released events, the getKeyCode method returns the event's keyCode. For key typed events, the getKeyCode method always returns VK_UNDEFINED.
"Key pressed" and "key released" events are lower-level and depend on the platform and keyboard layout. They are generated whenever a key is pressed or released, and are the only way to find out about keys that don't generate character input (e.g., action keys, modifier keys, etc.). The key being pressed or released is indicated by the getKeyCode method, which returns a virtual key code.
Virtual key codes are used to report which keyboard key has been pressed, rather than a character generated by the combination of one or more keystrokes (such as "A", which comes from shift and "a").
For example, pressing the Shift key will cause a KEY_PRESSED event with a VK_SHIFT keyCode, while pressing the 'a' key will result in a VK_A keyCode. After the 'a' key is released, a KEY_RELEASED event will be fired with VK_A. Separately, a KEY_TYPED event with a keyChar value of 'A' is generated.
Notes:
WARNING: Aside from those keys that are defined by the Java language (VK_ENTER, VK_BACK_SPACE, and VK_TAB), do not rely on the values of the VK_ constants. Sun reserves the right to change these values as needed to accomodate a wider range of keyboards in the future.
Field Detail |
private boolean isProxyActive
public static final int KEY_FIRST
public static final int KEY_LAST
public static final int KEY_TYPED
public static final int KEY_PRESSED
public static final int KEY_RELEASED
public static final int VK_LEFT
public static final int VK_UP
public static final int VK_RIGHT
public static final int VK_DOWN
public static final int VK_COMMA
public static final int VK_MINUS
public static final int VK_PERIOD
public static final int VK_SLASH
public static final int VK_0
public static final int VK_SEMICOLON
public static final int VK_EQUALS
public static final int VK_A
public static final int VK_OPEN_BRACKET
public static final int VK_BACK_SLASH
public static final int VK_CLOSE_BRACKET
public static final int VK_SEPARATER
public static final int VK_SEPARATOR
public static final int VK_F1
public static final int VK_F2
public static final int VK_F3
public static final int VK_F4
public static final int VK_F5
public static final int VK_F6
public static final int VK_F7
public static final int VK_F8
public static final int VK_F9
public static final int VK_F10
public static final int VK_F11
public static final int VK_F12
public static final int VK_F13
public static final int VK_F14
public static final int VK_F15
public static final int VK_F16
public static final int VK_F17
public static final int VK_F18
public static final int VK_F19
public static final int VK_F20
public static final int VK_F21
public static final int VK_F22
public static final int VK_F23
public static final int VK_F24
public static final int VK_KP_UP
public static final int VK_KP_DOWN
public static final int VK_KP_LEFT
public static final int VK_KP_RIGHT
public static final int VK_DEAD_GRAVE
public static final int VK_DEAD_ACUTE
public static final int VK_DEAD_CIRCUMFLEX
public static final int VK_DEAD_TILDE
public static final int VK_DEAD_MACRON
public static final int VK_DEAD_BREVE
public static final int VK_DEAD_ABOVEDOT
public static final int VK_DEAD_DIAERESIS
public static final int VK_DEAD_ABOVERING
public static final int VK_DEAD_DOUBLEACUTE
public static final int VK_DEAD_CARON
public static final int VK_DEAD_CEDILLA
public static final int VK_DEAD_OGONEK
public static final int VK_DEAD_IOTA
public static final int VK_DEAD_VOICED_SOUND
public static final int VK_DEAD_SEMIVOICED_SOUND
public static final int VK_AMPERSAND
public static final int VK_ASTERISK
public static final int VK_QUOTEDBL
public static final int VK_LESS
public static final int VK_GREATER
public static final int VK_BRACELEFT
public static final int VK_BRACERIGHT
public static final int VK_AT
public static final int VK_COLON
public static final int VK_CIRCUMFLEX
public static final int VK_DOLLAR
public static final int VK_EURO_SIGN
public static final int VK_EXCLAMATION_MARK
public static final int VK_INVERTED_EXCLAMATION_MARK
public static final int VK_LEFT_PARENTHESIS
public static final int VK_NUMBER_SIGN
public static final int VK_PLUS
public static final int VK_RIGHT_PARENTHESIS
public static final int VK_UNDERSCORE
public static final int VK_WINDOWS
public static final int VK_CONTEXT_MENU
public static final int VK_CONVERT
public static final int VK_NONCONVERT
public static final int VK_ACCEPT
public static final int VK_ALPHANUMERIC
public static final int VK_KATAKANA
public static final int VK_HIRAGANA
public static final int VK_FULL_WIDTH
public static final int VK_HALF_WIDTH
public static final int VK_ROMAN_CHARACTERS
public static final int VK_ALL_CANDIDATES
public static final int VK_PREVIOUS_CANDIDATE
public static final int VK_CODE_INPUT
public static final int VK_JAPANESE_KATAKANA
public static final int VK_JAPANESE_HIRAGANA
public static final int VK_JAPANESE_ROMAN
public static final int VK_KANA_LOCK
public static final int VK_INPUT_METHOD_ON_OFF
public static final int VK_CUT
public static final int VK_COPY
public static final int VK_PASTE
public static final int VK_UNDO
public static final int VK_AGAIN
public static final int VK_FIND
public static final int VK_PROPS
public static final int VK_STOP
public static final int VK_COMPOSE
public static final int VK_ALT_GRAPH
public static final int VK_BEGIN
public static final int VK_UNDEFINED
public static final char CHAR_UNDEFINED
public static final int KEY_LOCATION_UNKNOWN
KEY_TYPED
events do not have a keyLocation; this value is used instead.public static final int KEY_LOCATION_STANDARD
public static final int KEY_LOCATION_LEFT
public static final int KEY_LOCATION_RIGHT
public static final int KEY_LOCATION_NUMPAD
int keyCode
char keyChar
keyChar
is a valid unicode character that is fired by a key or a key combination on a keyboard.int keyLocation
KEY_LOCATION_UNKNOWN
, KEY_LOCATION_STANDARD
, KEY_LOCATION_LEFT
, KEY_LOCATION_RIGHT
, and KEY_LOCATION_NUMPAD
.Constructor Detail |
private KeyEvent(java.awt.Component source, int id, long when, int modifiers, int keyCode, char keyChar, int keyLocation, boolean isProxyActive)
KeyEvent
object. Note that passing in an invalid id
results in unspecified behavior. This method throws an IllegalArgumentException
if source
is null
.
source
- the Component
that originated the eventid
- an integer identifying the type of eventwhen
- a long integer that specifies the time the event occurredmodifiers
- the modifier keys down during event (shift, ctrl, alt, meta) Either extended _DOWN_MASK or old _MASK modifiers should be used, but both models should not be mixed in one event. Use of the extended modifiers is preferred.keyCode
- the integer code for an actual key, or VK_UNDEFINED (for a key-typed event)keyChar
- the Unicode character generated by this event, or CHAR_UNDEFINED (for key-pressed and key-released events which do not map to a valid Unicode character)keyLocation
- identifies the key location. The only legal values are KEY_LOCATION_UNKNOWN
, KEY_LOCATION_STANDARD
, KEY_LOCATION_LEFT
, KEY_LOCATION_RIGHT
, and KEY_LOCATION_NUMPAD
.IllegalArgumentException
- if id
is KEY_TYPED
and keyChar
is CHAR_UNDEFINED
; or if id
is KEY_TYPED
and keyCode
is not VK_UNDEFINED
; or if id
is KEY_TYPED
and keyLocation
is not KEY_LOCATION_UNKNOWN
; or if keyLocation
is not one of the legal values enumerated above.IllegalArgumentException
- if source
is nullpublic KeyEvent(java.awt.Component source, int id, long when, int modifiers, int keyCode, char keyChar)
KeyEvent
object. Note that passing in an invalid id
results in unspecified behavior. This method throws an IllegalArgumentException
if source
is null
.
source
- the Component
that originated the eventid
- an integer identifying the type of eventwhen
- a long integer that specifies the time the event occurredmodifiers
- the modifier keys down during event (shift, ctrl, alt, meta) Either extended _DOWN_MASK or old _MASK modifiers should be used, but both models should not be mixed in one event. Use of the extended modifiers is preferred.keyCode
- the integer code for an actual key, or VK_UNDEFINED (for a key-typed event)keyChar
- the Unicode character generated by this event, or CHAR_UNDEFINED (for key-pressed and key-released events which do not map to a valid Unicode character)IllegalArgumentException
- if id
is KEY_TYPED
and keyChar
is CHAR_UNDEFINED
; or if id
is KEY_TYPED
and keyCode
is not VK_UNDEFINED
IllegalArgumentException
- if source
is nullpublic KeyEvent(java.awt.Component source, int id, long when, int modifiers, int keyCode)
Method Detail |
private static native void initIDs()
public int getKeyCode()
KEY_TYPED
events, the keyCode is VK_UNDEFINED
.)public void setKeyCode(int keyCode)
keyCode
- an integer corresponding to an actual key on the keyboard.public char getKeyChar()
KEY_TYPED
event for shift + "a" returns the value for "A". KEY_PRESSED
and KEY_RELEASED
events are not intended for reporting of character input. Therefore, the values returned by this method are guaranteed to be meaningful only for KEY_TYPED
events.
CHAR_UNDEFINED
is returned.public void setKeyChar(char keyChar)
keyChar
- a char corresponding to to the combination of keystrokes that make up this event.public void setModifiers(int modifiers)
NOTE: use of this method is not recommended, because many AWT implementations do not recognize modifier changes. This is especially true for KEY_TYPED
events where the shift modifier is changed.
modifiers
- an integer combination of the modifier constants.public int getKeyLocation()
KEY_LOCATION_UNKNOWN
for KEY_TYPED
events.public static java.lang.String getKeyText(int keyCode)
public static java.lang.String getKeyModifiersText(int modifiers)
String
describing the modifier key(s), such as "Shift", or "Ctrl+Shift". These strings can be localized by changing the awt.properties
file. Note that InputEvent.ALT_MASK
and InputEvent.BUTTON2_MASK
have the same value, so the string "Alt" is returned for both modifiers. Likewise, InputEvent.META_MASK
and InputEvent.BUTTON3_MASK
have the same value, so the string "Meta" is returned for both modifiers.
public boolean isActionKey()
true
if the key is an "action" key, false
otherwisepublic java.lang.String paramString()
private void setNewModifiers()
private void setOldModifiers()
private void readObject(java.io.ObjectInputStream s)