Module javafx.graphics
Package javafx.scene.input

# Class KeyEvent

java.lang.Object
java.util.EventObject
javafx.event.Event
javafx.scene.input.InputEvent
javafx.scene.input.KeyEvent

All Implemented Interfaces:
  `Serializable`, `Cloneable`

    public final class KeyEvent
    extends InputEvent

An event which indicates that a keystroke occurred in a `Node`.

This event is generated when a key is pressed, released, or typed. Depending on the type of the event it is passed to `onKeyPressed`, `onKeyTyped` or `onKeyReleased` function.

"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 `character` variable always contains a valid Unicode character(s) 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 `character` variable is guaranteed to be meaningful only for key typed events.

For key pressed and key released events, the `code` variable contains the event's key code. For key typed events, the `code` variable always contains `KeyCode.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 code variable, which contains a virtual key code.

For triggering context menus see the `ContextMenuEvent`.

Since:
  JavaFX 2.0
See Also:
  Serialized Form

- ## Field Summary

  Fields
  Modifier and Type | Field | Description
  --- | --- | ---
  `static EventType<KeyEvent>` | `ANY` | Common supertype for all key event types.
  `static String` | `CHAR_UNDEFINED` | KEY_PRESSED and KEY_RELEASED events which do not map to a valid Unicode character use this for the keyChar value.
  `static EventType<KeyEvent>` | `KEY_PRESSED` | This event occurs when a key has been pressed.
  `static EventType<KeyEvent>` | `KEY_RELEASED` | This event occurs when a key has been released.
  `static EventType<KeyEvent>` | `KEY_TYPED` | This event occurs when a character-generating key was typed (pressed and released).

  ### Fields inherited from class javafx.event.Event

  `consumed, eventType, NULL_SOURCE_TARGET, target`

  ### Fields inherited from class java.util.EventObject

  `source`

- ## Constructor Summary

  Constructors
  Constructor | Description
  --- | ---
  `KeyEvent​(Object source, EventTarget target, EventType<KeyEvent> eventType, String character, String text, KeyCode code, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown)` | Constructs a new `KeyEvent` event from the specified parameters.
  `KeyEvent​(EventType<KeyEvent> eventType, String character, String text, KeyCode code, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown)` | Constructs a new `KeyEvent` event from the specified parameters, with a `null` source and target.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `KeyEvent` | `copyFor​(Object newSource, EventTarget newTarget)` | Creates and returns a copy of this event with the specified event source and target.
  `KeyEvent` | `copyFor​(Object source, EventTarget target, EventType<KeyEvent> type)` | Creates a copy of the given event with the given fields substituted.
  `String` | `getCharacter()` | The Unicode character or sequence of characters associated with the key typed event.
  `KeyCode` | `getCode()` | The key code associated with the key in this key pressed or key released event.
  `EventType<KeyEvent>` | `getEventType()` | Gets the event type of this event.
  `String` | `getText()` | A String describing the key code, such as "HOME", "F1" or "A", for key pressed and key released events.
  `boolean` | `isAltDown()` | Returns whether or not the Alt modifier is down on this event.
  `boolean` | `isControlDown()` | Returns whether or not the Control modifier is down on this event.
  `boolean` | `isMetaDown()` | Returns whether or not the Meta modifier is down on this event.
  `boolean` | `isShiftDown()` | Returns whether or not the Shift modifier is down on this event.
  `boolean` | `isShortcutDown()` | Returns whether or not the host platform common shortcut modifier is down on this event.
  `String` | `toString()` | Returns a string representation of this `KeyEvent` object.

  ### Methods inherited from class javafx.event.Event

  `clone, consume, fireEvent, getTarget, isConsumed`

  ### Methods inherited from class java.util.EventObject

  `getSource`

  ### Methods inherited from class java.lang.Object

  `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### ANY

    public static final EventType<KeyEvent> ANY
    Common supertype for all key event types.

  - ### KEY_PRESSED

    public static final EventType<KeyEvent> KEY_PRESSED
    This event occurs when a key has been pressed.

  - ### KEY_RELEASED

    public static final EventType<KeyEvent> KEY_RELEASED
    This event occurs when a key has been released.

  - ### KEY_TYPED

    public static final EventType<KeyEvent> KEY_TYPED
    This event occurs when a character-generating key was typed (pressed and released). The event contains the `character` field containing the typed string, the `code` and `text` fields are not used.

  - ### CHAR_UNDEFINED

    public static final String CHAR_UNDEFINED
    KEY_PRESSED and KEY_RELEASED events which do not map to a valid Unicode character use this for the keyChar value.

- ## Constructor Details

  - ### KeyEvent

    public KeyEvent​(Object source, EventTarget target, EventType<KeyEvent> eventType, String character, String text, KeyCode code, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown)
    Constructs a new `KeyEvent` event from the specified parameters.
    Parameters:
      `source` - the source of the event. Can be null.
      `target` - the target of the event. Can be null.
      `eventType` - The type of the event.
      `character` - The character or sequence of characters associated with the event
      `text` - A String describing the key code
      `code` - The integer key code
      `shiftDown` - true if shift modifier was pressed.
      `controlDown` - true if control modifier was pressed.
      `altDown` - true if alt modifier was pressed.
      `metaDown` - true if meta modifier was pressed.
    Since:
      JavaFX 8.0

  - ### KeyEvent

    public KeyEvent​(EventType<KeyEvent> eventType, String character, String text, KeyCode code, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown)
    Constructs a new `KeyEvent` event from the specified parameters, with a `null` source and target.
    Parameters:
      `eventType` - The type of the event.
      `character` - The character or sequence of characters associated with the event
      `text` - A String describing the key code
      `code` - The integer key code
      `shiftDown` - true if shift modifier was pressed.
      `controlDown` - true if control modifier was pressed.
      `altDown` - true if alt modifier was pressed.
      `metaDown` - true if meta modifier was pressed.
    Since:
      JavaFX 8.0

- ## Method Details

  - ### getCharacter

    public final String getCharacter()
    The Unicode character or sequence of characters associated with the key typed event. Contains multiple elements if the key produced a single Unicode character from outside of the Basic Multilingual Plane which needs to be encoded by the corresponding surrogate pair in Java or if the key produced multiple Unicode characters itself.

    For example, `character` will have the value "A" for a key typed event generated by pressing SHIFT + 'a'. For key pressed and key released events, `character` is always `CHAR_UNDEFINED`.

    Returns:
      The Unicode character(s) associated with the key typed event

  - ### getText

    public final String getText()
    A String describing the key code, such as "HOME", "F1" or "A", for key pressed and key released events. For key typed events, `text` is always the empty string.
    Returns:
      A String describing the key code

  - ### getCode

    public final KeyCode getCode()
    The key code associated with the key in this key pressed or key released event. For key typed events, `code` is always `KeyCode.UNDEFINED`.
    Returns:
      The key code associated with the key in this event, `KeyCode.UNDEFINED` for key typed event

  - ### isShiftDown

    public final boolean isShiftDown()
    Returns whether or not the Shift modifier is down on this event.
    Returns:
      whether or not the Shift modifier is down on this event.

  - ### isControlDown

    public final boolean isControlDown()
    Returns whether or not the Control modifier is down on this event.
    Returns:
      whether or not the Control modifier is down on this event.

  - ### isAltDown

    public final boolean isAltDown()
    Returns whether or not the Alt modifier is down on this event.
    Returns:
      whether or not the Alt modifier is down on this event.

  - ### isMetaDown

    public final boolean isMetaDown()
    Returns whether or not the Meta modifier is down on this event.
    Returns:
      whether or not the Meta modifier is down on this event.

  - ### isShortcutDown

    public final boolean isShortcutDown()
    Returns whether or not the host platform common shortcut modifier is down on this event. This common shortcut modifier is a modifier key which is used commonly in shortcuts on the host platform. It is for example `control` on Windows and `meta` (command key) on Mac.
    Returns:
      `true` if the shortcut modifier is down, `false` otherwise

  - ### toString

    public String toString()
    Returns a string representation of this `KeyEvent` object.
    Overrides:
      `toString` in class `EventObject`
    Returns:
      a string representation of this `KeyEvent` object.

  - ### copyFor

    public KeyEvent copyFor​(Object newSource, EventTarget newTarget)
    Description copied from class: `Event`
    Creates and returns a copy of this event with the specified event source and target. If the source or target is set to `null`, it is replaced by the `NULL_SOURCE_TARGET` value.
    Overrides:
      `copyFor` in class `Event`
    Parameters:
      `newSource` - the new source of the copied event
      `newTarget` - the new target of the copied event
    Returns:
      the event copy with the new source and target

  - ### copyFor

    public KeyEvent copyFor​(Object source, EventTarget target, EventType<KeyEvent> type)
    Creates a copy of the given event with the given fields substituted.
    Parameters:
      `source` - the new source of the copied event
      `target` - the new target of the copied event
      `type` - the new event type.
    Returns:
      the event copy with the fields substituted
    Since:
      JavaFX 8.0

  - ### getEventType

    public EventType<KeyEvent> getEventType()
    Description copied from class: `Event`
    Gets the event type of this event. Objects of the same `Event` class can have different event types. These event types further specify what kind of event occurred.
    Overrides:
      `getEventType` in class `InputEvent`
    Returns:
      the event type