Java Doc for KeyEvent.java in  » 6.0-JDK-Modules » j2me » java » awt » event » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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. 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:

• Key combinations which do not result in Unicode characters, such as action keys like F1 and the HELP key, do not generate KEY_TYPED events.
• Not all keyboards or systems are capable of generating all virtual key codes. No attempt is made in Java to artificially generate these keys.
• Virtual key codes do not identify a physical key, they depend on the platform and keyboard layout. For example, the key that on a Windows U.S. keyboard layout generates VK_Q, generates VK_A on a Windows French keyboard layout.
• In order to support the platform-independent handling of action keys, the Java platform uses a few additional virtual key constants for functions that would otherwise have to be recognized by interpreting virtual key codes and modifiers. For example, for Japanese Windows keyboards, VK_ALL_CANDIDATES is returned instead of VK_CONVERT with the ALT modifier.

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.
author:
   Carl Quinn
author:
   Amy Fowler
author:
   Norbert Lindenberg
version:
   1.57 09/21/01
See Also:   KeyAdapter
See Also:   KeyListener
See Also:    Tutorial: Writing a Key Listener
See Also:    Reference: The Java Class Libraries (update file)
since:
   1.1

Note that passing in an invalid id results in unspecified behavior.
Parameters:
  source - the Component that originated the event
Parameters:
  id - an integer identifying the type of event
Parameters:
  when - a long integer that specifies the time the eventoccurred
Parameters:
  modifiers - the modifier keys down during event (shift, ctrl,alt, meta)Either extended _DOWN_MASK or old _MASK modifiersshould be used, but both models should not be mixedin one event.

Note that passing in an invalid id results in unspecified behavior.
Parameters:
  source - the Component that originated the event
Parameters:
  id - an integer identifying the type of event
Parameters:
  when - a long integer that specifies the time the eventoccurred
Parameters:
  modifiers - the modifier keys down during event (shift, ctrl,alt, meta)Either extended _DOWN_MASK or old _MASK modifiersshould be used, but both models should not be mixedin one event.

Note that passing in an invalid id results in unspecified behavior.
Parameters:
  source - the Component that originated the event
Parameters:
  id - an integer identifying the type of event
Parameters:
  when - a long integer that specifies the time the eventoccurred
Parameters:
  modifiers - the modifier keys down during event (shift, ctrl,alt, meta)Either extended _DOWN_MASK or old _MASK modifiersshould be used, but both models should not be mixedin one event. Use of the extended modifiers ispreferred.
Parameters:
  keyCode - the integer code for an actual key, or VK_UNDEFINED(for a key-typed event)
Parameters:
  keyChar - the Unicode character generated by this event, orCHAR_UNDEFINED (for key-pressed and key-releasedevents which do not map to a valid Unicode character)
Parameters:
  keyLocation - identifies the key location. The only legalvalues are KEY_LOCATION_UNKNOWN,KEY_LOCATION_STANDARD, KEY_LOCATION_LEFT,KEY_LOCATION_RIGHT, and KEY_LOCATION_NUMPAD.
exception:
  IllegalArgumentException - if id is KEY_TYPED andkeyChar is CHAR_UNDEFINED;or if id is KEY_TYPED andkeyCode is not VK_UNDEFINED;or if id is KEY_TYPED andkeyLocation is not KEY_LOCATION_UNKNOWN;or if keyLocation is not one of the legalvalues enumerated above.
since:
   1.4

Note that passing in an invalid id results in unspecified behavior.
Parameters:
  source - the Component that originated the event
Parameters:
  id - an integer identifying the type of event
Parameters:
  when - a long integer that specifies the time the eventoccurred
Parameters:
  modifiers - the modifier keys down during event (shift, ctrl,alt, meta)Either extended _DOWN_MASK or old _MASK modifiersshould be used, but both models should not be mixedin one event. Use of the extended modifiers ispreferred.
Parameters:
  keyCode - the integer code for an actual key, or VK_UNDEFINED(for a key-typed event)
Parameters:
  keyChar - the Unicode character generated by this event, orCHAR_UNDEFINED (for key-pressed and key-releasedevents which do not map to a valid Unicode character)
exception:
  IllegalArgumentException - if id isKEY_TYPED and keyChar isCHAR_UNDEFINED; or if id isKEY_TYPED and keyCode is notVK_UNDEFINED

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.
Parameters:
  modifiers - an integer combination of the modifier constants.
See Also:   InputEvent
See Also:    as of JDK1.1.4