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
. The getExtendedKeyCode
method
may also be used with many international keyboard layouts.
"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
and getExtendedKeyCode
methods, which return 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.
Pressing and releasing a key on the keyboard results in the generating the following key events (in order):
But in some cases (e.g. auto-repeat or input method is activated) the order could be different (and platform dependent).KEY_PRESSED
KEY_TYPED
(is only generated if a valid Unicode character could be generated.)KEY_RELEASED
Notes:
VK_Q
when using a U.S. keyboard layout also
generates a unique code for Russian or Hebrew layout. There is no a
VK_
constant for these and many other codes in various layouts. These codes
may be obtained by using getExtendedKeyCode
and are used whenever
a VK_
constant is used.
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.
An unspecified behavior will be caused if the id
parameter
of any particular KeyEvent
instance is not
in the range from KEY_FIRST
to KEY_LAST
.
KeyAdapter
,
KeyListener
,
Tutorial: Writing a Key Listener,
Serialized FormModifier and Type | Field and Description |
---|---|
static char |
CHAR_UNDEFINED
KEY_PRESSED and KEY_RELEASED events which do not map to a
valid Unicode character use this for the keyChar value.
|
static int |
KEY_FIRST
The first number in the range of ids used for key events.
|
static int |
KEY_LAST
The last number in the range of ids used for key events.
|
static int |
KEY_LOCATION_LEFT
A constant indicating that the key pressed or released is in
the left key location (there is more than one possible location
for this key).
|
static int |
KEY_LOCATION_NUMPAD
A constant indicating that the key event originated on the
numeric keypad or with a virtual key corresponding to the
numeric keypad.
|
static int |
KEY_LOCATION_RIGHT
A constant indicating that the key pressed or released is in
the right key location (there is more than one possible location
for this key).
|
static int |
KEY_LOCATION_STANDARD
A constant indicating that the key pressed or released
is not distinguished as the left or right version of a key,
and did not originate on the numeric keypad (or did not
originate with a virtual key corresponding to the numeric
keypad).
|
static int |
KEY_LOCATION_UNKNOWN
A constant indicating that the keyLocation is indeterminate
or not relevant.
|
static int |
KEY_PRESSED
The "key pressed" event.
|
static int |
KEY_RELEASED
The "key released" event.
|
static int |
KEY_TYPED
The "key typed" event.
|
static int |
VK_0
VK_0 thru VK_9 are the same as ASCII '0' thru '9' (0x30 - 0x39)
|
static int |
VK_1
|
static int |
VK_2
|
static int |
VK_3
|
static int |
VK_4
|
static int |
VK_5
|
static int |
VK_6
|
static int |
VK_7
|
static int |
VK_8
|
static int |
VK_9
|
static int |
VK_A
VK_A thru VK_Z are the same as ASCII 'A' thru 'Z' (0x41 - 0x5A)
|
static int |
VK_ACCEPT
Constant for the Accept or Commit function key.
|
static int |
VK_ADD
|
static int |
VK_AGAIN
|
static int |
VK_ALL_CANDIDATES
Constant for the All Candidates function key.
|
static int |
VK_ALPHANUMERIC
Constant for the Alphanumeric function key.
|
static int |
VK_ALT
|
static int |
VK_ALT_GRAPH
Constant for the AltGraph function key.
|
static int |
VK_AMPERSAND
|
static int |
VK_ASTERISK
|
static int |
VK_AT
Constant for the "@" key.
|
static int |
VK_B
|
static int |
VK_BACK_QUOTE
|
static int |
VK_BACK_SLASH
Constant for the back slash key, "\"
|
static int |
VK_BACK_SPACE
|
static int |
VK_BEGIN
Constant for the Begin key.
|
static int |
VK_BRACELEFT
|
static int |
VK_BRACERIGHT
|
static int |
VK_C
|
static int |
VK_CANCEL
|
static int |
VK_CAPS_LOCK
|
static int |
VK_CIRCUMFLEX
Constant for the "^" key.
|
static int |
VK_CLEAR
|
static int |
VK_CLOSE_BRACKET
Constant for the close bracket key, "]"
|
static int |
VK_CODE_INPUT
Constant for the Code Input function key.
|
static int |
VK_COLON
Constant for the ":" key.
|
static int |
VK_COMMA
Constant for the comma key, ","
|
static int |
VK_COMPOSE
Constant for the Compose function key.
|
static int |
VK_CONTEXT_MENU
Constant for the Microsoft Windows Context Menu key.
|
static int |
VK_CONTROL
|
static int |
VK_CONVERT
Constant for the Convert function key.
|
static int |
VK_COPY
|
static int |
VK_CUT
|
static int |
VK_D
|
static int |
VK_DEAD_ABOVEDOT
|
static int |
VK_DEAD_ABOVERING
|
static int |
VK_DEAD_ACUTE
|
static int |
VK_DEAD_BREVE
|
static int |
VK_DEAD_CARON
|
static int |
VK_DEAD_CEDILLA
|
static int |
VK_DEAD_CIRCUMFLEX
|
static int |
VK_DEAD_DIAERESIS
|
static int |
VK_DEAD_DOUBLEACUTE
|
static int |
VK_DEAD_GRAVE
|
static int |
VK_DEAD_IOTA
|
static int |
VK_DEAD_MACRON
|
static int |
VK_DEAD_OGONEK
|
static int |
VK_DEAD_SEMIVOICED_SOUND
|
static int |
VK_DEAD_TILDE
|
static int |
VK_DEAD_VOICED_SOUND
|
static int |
VK_DECIMAL
|
static int |
VK_DELETE
|
static int |
VK_DIVIDE
|
static int |
VK_DOLLAR
Constant for the "$" key.
|
static int |
VK_DOWN
Constant for the non-numpad down arrow key.
|
static int |
VK_E
|
static int |
VK_END
|
static int |
VK_ENTER
|
static int |
VK_EQUALS
Constant for the equals key, "="
|
static int |
VK_ESCAPE
|
static int |
VK_EURO_SIGN
Constant for the Euro currency sign key.
|
static int |
VK_EXCLAMATION_MARK
Constant for the "!" key.
|
static int |
VK_F
|
static int |
VK_F1
Constant for the F1 function key.
|
static int |
VK_F10
Constant for the F10 function key.
|
static int |
VK_F11
Constant for the F11 function key.
|
static int |
VK_F12
Constant for the F12 function key.
|
static int |
VK_F13
Constant for the F13 function key.
|
static int |
VK_F14
Constant for the F14 function key.
|
static int |
VK_F15
Constant for the F15 function key.
|
static int |
VK_F16
Constant for the F16 function key.
|
static int |
VK_F17
Constant for the F17 function key.
|
static int |
VK_F18
Constant for the F18 function key.
|
static int |
VK_F19
Constant for the F19 function key.
|
static int |
VK_F2
Constant for the F2 function key.
|
static int |
VK_F20
Constant for the F20 function key.
|
static int |
VK_F21
Constant for the F21 function key.
|
static int |
VK_F22
Constant for the F22 function key.
|
static int |
VK_F23
Constant for the F23 function key.
|
static int |
VK_F24
Constant for the F24 function key.
|
static int |
VK_F3
Constant for the F3 function key.
|
static int |
VK_F4
Constant for the F4 function key.
|
static int |
VK_F5
Constant for the F5 function key.
|
static int |
VK_F6
Constant for the F6 function key.
|
static int |
VK_F7
Constant for the F7 function key.
|
static int |
VK_F8
Constant for the F8 function key.
|
static int |
VK_F9
Constant for the F9 function key.
|
static int |
VK_FINAL
|
static int |
VK_FIND
|
static int |
VK_FULL_WIDTH
Constant for the Full-Width Characters function key.
|
static int |
VK_G
|
static int |
VK_GREATER
|
static int |
VK_H
|
static int |
VK_HALF_WIDTH
Constant for the Half-Width Characters function key.
|
static int |
VK_HELP
|
static int |
VK_HIRAGANA
Constant for the Hiragana function key.
|
static int |
VK_HOME
|
static int |
VK_I
|
static int |
VK_INPUT_METHOD_ON_OFF
Constant for the input method on/off key.
|
static int |
VK_INSERT
|
static int |
VK_INVERTED_EXCLAMATION_MARK
Constant for the inverted exclamation mark key.
|
static int |
VK_J
|
static int |
VK_JAPANESE_HIRAGANA
Constant for the Japanese-Hiragana function key.
|
static int |
VK_JAPANESE_KATAKANA
Constant for the Japanese-Katakana function key.
|
static int |
VK_JAPANESE_ROMAN
Constant for the Japanese-Roman function key.
|
static int |
VK_K
|
static int |
VK_KANA
|
static int |
VK_KANA_LOCK
Constant for the locking Kana function key.
|
static int |
VK_KANJI
|
static int |
VK_KATAKANA
Constant for the Katakana function key.
|
static int |
VK_KP_DOWN
Constant for the numeric keypad down arrow key.
|
static int |
VK_KP_LEFT
Constant for the numeric keypad left arrow key.
|
static int |
VK_KP_RIGHT
Constant for the numeric keypad right arrow key.
|
static int |
VK_KP_UP
Constant for the numeric keypad up arrow key.
|
static int |
VK_L
|
static int |
VK_LEFT
Constant for the non-numpad left arrow key.
|
static int |
VK_LEFT_PARENTHESIS
Constant for the "(" key.
|
static int |
VK_LESS
|
static int |
VK_M
|
static int |
VK_META
|
static int |
VK_MINUS
Constant for the minus key, "-"
|
static int |
VK_MODECHANGE
|
static int |
VK_MULTIPLY
|
static int |
VK_N
|
static int |
VK_NONCONVERT
Constant for the Don't Convert function key.
|
static int |
VK_NUM_LOCK
|
static int |
VK_NUMBER_SIGN
Constant for the "#" key.
|
static int |
VK_NUMPAD0
|
static int |
VK_NUMPAD1
|
static int |
VK_NUMPAD2
|
static int |
VK_NUMPAD3
|
static int |
VK_NUMPAD4
|
static int |
VK_NUMPAD5
|
static int |
VK_NUMPAD6
|
static int |
VK_NUMPAD7
|
static int |
VK_NUMPAD8
|
static int |
VK_NUMPAD9
|
static int |
VK_O
|
static int |
VK_OPEN_BRACKET
Constant for the open bracket key, "["
|
static int |
VK_P
|
static int |
VK_PAGE_DOWN
|
static int |
VK_PAGE_UP
|
static int |
VK_PASTE
|
static int |
VK_PAUSE
|
static int |
VK_PERIOD
Constant for the period key, "."
|
static int |
VK_PLUS
Constant for the "+" key.
|
static int |
VK_PREVIOUS_CANDIDATE
Constant for the Previous Candidate function key.
|
static int |
VK_PRINTSCREEN
|
static int |
VK_PROPS
|
static int |
VK_Q
|
static int |
VK_QUOTE
|
static int |
VK_QUOTEDBL
|
static int |
VK_R
|
static int |
VK_RIGHT
Constant for the non-numpad right arrow key.
|
static int |
VK_RIGHT_PARENTHESIS
Constant for the ")" key.
|
static int |
VK_ROMAN_CHARACTERS
Constant for the Roman Characters function key.
|
static int |
VK_S
|
static int |
VK_SCROLL_LOCK
|
static int |
VK_SEMICOLON
Constant for the semicolon key, ";"
|
static int |
VK_SEPARATER
This constant is obsolete, and is included only for backwards
compatibility.
|
static int |
VK_SEPARATOR
Constant for the Numpad Separator key.
|
static int |
VK_SHIFT
|
static int |
VK_SLASH
Constant for the forward slash key, "/"
|
static int |
VK_SPACE
|
static int |
VK_STOP
|
static int |
VK_SUBTRACT
|
static int |
VK_T
|
static int |
VK_TAB
|
static int |
VK_U
|
static int |
VK_UNDEFINED
This value is used to indicate that the keyCode is unknown.
|
static int |
VK_UNDERSCORE
Constant for the "_" key.
|
static int |
VK_UNDO
|
static int |
VK_UP
Constant for the non-numpad up arrow key.
|
static int |
VK_V
|
static int |
VK_W
|
static int |
VK_WINDOWS
Constant for the Microsoft Windows "Windows" key.
|
static int |
VK_X
|
static int |
VK_Y
|
static int |
VK_Z
|
ALT_DOWN_MASK, ALT_GRAPH_DOWN_MASK, ALT_GRAPH_MASK, ALT_MASK, BUTTON1_DOWN_MASK, BUTTON1_MASK, BUTTON2_DOWN_MASK, BUTTON2_MASK, BUTTON3_DOWN_MASK, BUTTON3_MASK, CTRL_DOWN_MASK, CTRL_MASK, META_DOWN_MASK, META_MASK, SHIFT_DOWN_MASK, SHIFT_MASK
COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN
ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, HIERARCHY_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, WINDOW_STATE_EVENT_MASK
Modifier and Type | Static Method and Description |
---|---|
static int |
getExtendedKeyCodeForChar(int c)
Returns an extended key code for a unicode character.
|
static java.lang.String |
getKeyModifiersText(int modifiers)
Returns a
String describing the modifier key(s),
such as "Shift", or "Ctrl+Shift". |
static java.lang.String |
getKeyText(int keyCode)
Returns a String describing the keyCode, such as "HOME", "F1" or "A".
|
getMaskForButton, getModifiersExText
Constructor and Description |
---|
KeyEvent(Component source,
int id,
long when,
int modifiers,
int keyCode)
Deprecated as of JDK1.1
|
KeyEvent(Component source,
int id,
long when,
int modifiers,
int keyCode,
char keyChar)
Constructs a
KeyEvent object. |
KeyEvent(Component source,
int id,
long when,
int modifiers,
int keyCode,
char keyChar,
int keyLocation)
Constructs a
KeyEvent object. |
Modifier and Type | Method and Description |
---|---|
int |
getExtendedKeyCode()
Returns an extended key code for the event.
|
char |
getKeyChar()
Returns the character associated with the key in this event.
|
int |
getKeyCode()
Returns the integer keyCode associated with the key in this event.
|
int |
getKeyLocation()
Returns the location of the key that originated this key event.
|
boolean |
isActionKey()
Returns whether the key in this event is an "action" key.
|
java.lang.String |
paramString()
Returns a parameter string identifying this event.
|
void |
setKeyChar(char keyChar)
Set the keyChar value to indicate a logical character.
|
void |
setKeyCode(int keyCode)
Set the keyCode value to indicate a physical key.
|
void |
setModifiers(int modifiers)
Deprecated as of JDK1.1.4
|
consume, getModifiers, getModifiersEx, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown
getComponent
VK_KP_LEFT
,
Constant Field ValuesVK_KP_UP
,
Constant Field ValuesVK_KP_RIGHT
,
Constant Field ValuesVK_KP_DOWN
,
Constant Field ValuesVK_SEPARATOR
,
Constant Field ValuesVK_UP
,
Constant Field ValuesVK_DOWN
,
Constant Field ValuesVK_LEFT
,
Constant Field ValuesVK_RIGHT
,
Constant Field ValuesgetKeyLocation()
,
Constant Field ValuesKEY_TYPED
events do not have a keyLocation; this value
is used instead.KeyEvent
object.
This method throws an
IllegalArgumentException
if source
is null
.
source
- The Component
that originated the eventid
- An integer indicating the type of event.
For information on allowable values, see
the class description for KeyEvent
when
- A long integer that specifies the time the event
occurred.
Passing negative or zero value
is not recommendedmodifiers
- The modifier keys down during event (shift, ctrl,
alt, meta).
Passing negative value
is not recommended.
Zero value means that no modifiers were passed.
Use either an extended _DOWN_MASK or old _MASK modifiers,
however do not mix models in the one event.
The extended modifiers are preferred for usingkeyCode
- 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
.java.lang.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.java.lang.IllegalArgumentException
- if source
is nullEventObject.getSource()
,
AWTEvent.getID()
,
InputEvent.getWhen()
,
InputEvent.getModifiers()
,
getKeyCode()
,
getKeyChar()
,
getKeyLocation()
KeyEvent
object.
This method throws an
IllegalArgumentException
if source
is null
.
source
- The Component
that originated the eventid
- An integer indicating the type of event.
For information on allowable values, see
the class description for KeyEvent
when
- A long integer that specifies the time the event
occurred.
Passing negative or zero value
is not recommendedmodifiers
- The modifier keys down during event (shift, ctrl,
alt, meta).
Passing negative value
is not recommended.
Zero value means that no modifiers were passed.
Use either an extended _DOWN_MASK or old _MASK modifiers,
however do not mix models in the one event.
The extended modifiers are preferred for usingkeyCode
- 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)java.lang.IllegalArgumentException
- if id
is
KEY_TYPED
and keyChar
is
CHAR_UNDEFINED
; or if id
is
KEY_TYPED
and keyCode
is not
VK_UNDEFINED
java.lang.IllegalArgumentException
- if source
is nullEventObject.getSource()
,
AWTEvent.getID()
,
InputEvent.getWhen()
,
InputEvent.getModifiers()
,
getKeyCode()
,
getKeyChar()
KEY_TYPED
events, the keyCode is
VK_UNDEFINED
.)keyCode
- an integer corresponding to an actual key on the keyboard.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.keyChar
- a char corresponding to to the combination of keystrokes
that make up this event.
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.InputEvent
KEY_LOCATION_UNKNOWN
for
KEY_TYPED
events.true
if the key is an "action" key,
false
otherwiseparamString
in class ComponentEvent
keyCode
. However, unlike keyCode
, this value depends on the
current keyboard layout. For instance, pressing the left topmost letter key
in a common English layout produces the same value as keyCode
, VK_Q
.
Pressing the same key in a regular Russian layout gives another code, unique for the
letter "Cyrillic I short".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.
InputEvent.getModifiersExText(int)
VK_
constant -- this
VK_
constant; for a character appearing on the primary
level of a known keyboard layout -- a unique integer.
If a character does not appear on the primary level of a known keyboard,
VK_UNDEFINED
is returned.