java.awt

## Class AWTKeyStroke

- java.lang.Object
- - java.awt.AWTKeyStroke

- All Implemented Interfaces:
    Serializable
  Direct Known Subclasses:
    KeyStroke

      public class AWTKeyStroke
      extends Object
      implements Serializable

  An `AWTKeyStroke` represents a key action on the keyboard, or equivalent input device. `AWTKeyStroke`s can correspond to only a press or release of a particular key, just as `KEY_PRESSED` and `KEY_RELEASED` `KeyEvent`s do; alternately, they can correspond to typing a specific Java character, just as `KEY_TYPED` `KeyEvent`s do. In all cases, `AWTKeyStroke`s can specify modifiers (alt, shift, control, meta, altGraph, or a combination thereof) which must be present during the action for an exact match.

  `AWTKeyStrokes` are immutable, and are intended to be unique. Client code should never create an `AWTKeyStroke` on its own, but should instead use a variant of `getAWTKeyStroke`. Client use of these factory methods allows the `AWTKeyStroke` implementation to cache and share instances efficiently.

  Since:
    1.4
  See Also:
    `getAWTKeyStroke(char)`, Serialized Form

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AWTKeyStroke()` Constructs an `AWTKeyStroke` with default values.
    `protected` | `AWTKeyStroke(char keyChar, int keyCode, int modifiers, boolean onKeyRelease)` Constructs an `AWTKeyStroke` with the specified values.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object anObject)` Returns true if this object is identical to the specified object.
    `static AWTKeyStroke` | `getAWTKeyStroke(char keyChar)` Returns a shared instance of an `AWTKeyStroke` that represents a `KEY_TYPED` event for the specified character.
    `static AWTKeyStroke` | `getAWTKeyStroke(Character keyChar, int modifiers)` Returns a shared instance of an `AWTKeyStroke` that represents a `KEY_TYPED` event for the specified Character object and a set of modifiers.
    `static AWTKeyStroke` | `getAWTKeyStroke(int keyCode, int modifiers)` Returns a shared instance of an `AWTKeyStroke`, given a numeric key code and a set of modifiers.
    `static AWTKeyStroke` | `getAWTKeyStroke(int keyCode, int modifiers, boolean onKeyRelease)` Returns a shared instance of an `AWTKeyStroke`, given a numeric key code and a set of modifiers, specifying whether the key is activated when it is pressed or released.
    `static AWTKeyStroke` | `getAWTKeyStroke(String s)` Parses a string and returns an `AWTKeyStroke`.
    `static AWTKeyStroke` | `getAWTKeyStrokeForEvent(KeyEvent anEvent)` Returns an `AWTKeyStroke` which represents the stroke which generated a given `KeyEvent`.
    `char` | `getKeyChar()` Returns the character for this `AWTKeyStroke`.
    `int` | `getKeyCode()` Returns the numeric key code for this `AWTKeyStroke`.
    `int` | `getKeyEventType()` Returns the type of `KeyEvent` which corresponds to this `AWTKeyStroke`.
    `int` | `getModifiers()` Returns the modifier keys for this `AWTKeyStroke`.
    `int` | `hashCode()` Returns a numeric value for this object that is likely to be unique, making it a good choice as the index value in a hash table.
    `boolean` | `isOnKeyRelease()` Returns whether this `AWTKeyStroke` represents a key release.
    `protected Object` | `readResolve()` Returns a cached instance of `AWTKeyStroke` (or a subclass of `AWTKeyStroke`) which is equal to this instance.
    `protected static void` | `registerSubclass(Class<?> subclass)` Registers a new class which the factory methods in `AWTKeyStroke` will use when generating new instances of `AWTKeyStroke`s.
    `String` | `toString()` Returns a string that displays and identifies this object's properties.

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### AWTKeyStroke

          protected AWTKeyStroke()

      Constructs an `AWTKeyStroke` with default values. The default values used are:

      Property | Default Value
      --- | ---
      Key Char | `KeyEvent.CHAR_UNDEFINED`
      Key Code | `KeyEvent.VK_UNDEFINED`
      Modifiers | none
      On key release? | `false`

      `AWTKeyStroke`s should not be constructed by client code. Use a variant of `getAWTKeyStroke` instead.
      See Also:
        `getAWTKeyStroke(char)`

    - #### AWTKeyStroke

          protected AWTKeyStroke(char keyChar,
                      int keyCode,
                      int modifiers,
                      boolean onKeyRelease)

      Constructs an `AWTKeyStroke` with the specified values. `AWTKeyStroke`s should not be constructed by client code. Use a variant of `getAWTKeyStroke` instead.
      Parameters:
        `keyChar` - the character value for a keyboard key
        `keyCode` - the key code for this `AWTKeyStroke`
        `modifiers` - a bitwise-ored combination of any modifiers
        `onKeyRelease` - `true` if this `AWTKeyStroke` corresponds to a key release; `false` otherwise
      See Also:
        `getAWTKeyStroke(char)`

  - ### Method Detail

    - #### registerSubclass

          protected static void registerSubclass(Class<?> subclass)

      Registers a new class which the factory methods in `AWTKeyStroke` will use when generating new instances of `AWTKeyStroke`s. After invoking this method, the factory methods will return instances of the specified Class. The specified Class must be either `AWTKeyStroke` or derived from `AWTKeyStroke`, and it must have a no-arg constructor. The constructor can be of any accessibility, including `private`. This operation flushes the current `AWTKeyStroke` cache.
      Parameters:
        `subclass` - the new Class of which the factory methods should create instances
      Throws:
        `IllegalArgumentException` - if subclass is `null`, or if subclass does not have a no-arg constructor
        `ClassCastException` - if subclass is not `AWTKeyStroke`, or a class derived from `AWTKeyStroke`

    - #### getAWTKeyStroke

          public static AWTKeyStroke getAWTKeyStroke(char keyChar)

      Returns a shared instance of an `AWTKeyStroke` that represents a `KEY_TYPED` event for the specified character.
      Parameters:
        `keyChar` - the character value for a keyboard key
      Returns:
        an `AWTKeyStroke` object for that key

    - #### getAWTKeyStroke

          public static AWTKeyStroke getAWTKeyStroke(Character keyChar,
                                     int modifiers)

      Returns a shared instance of an `AWTKeyStroke` that represents a `KEY_TYPED` event for the specified Character object and a set of modifiers. Note that the first parameter is of type Character rather than char. This is to avoid inadvertent clashes with calls to `getAWTKeyStroke(int keyCode, int modifiers)`. The modifiers consist of any combination of following:
      - java.awt.event.InputEvent.SHIFT_DOWN_MASK
      - java.awt.event.InputEvent.CTRL_DOWN_MASK
      - java.awt.event.InputEvent.META_DOWN_MASK
      - java.awt.event.InputEvent.ALT_DOWN_MASK
      - java.awt.event.InputEvent.ALT_GRAPH_DOWN_MASK
      The old modifiers listed below also can be used, but they are mapped to _DOWN_ modifiers.
      - java.awt.event.InputEvent.SHIFT_MASK
      - java.awt.event.InputEvent.CTRL_MASK
      - java.awt.event.InputEvent.META_MASK
      - java.awt.event.InputEvent.ALT_MASK
      - java.awt.event.InputEvent.ALT_GRAPH_MASK
      also can be used, but they are mapped to _DOWN_ modifiers. Since these numbers are all different powers of two, any combination of them is an integer in which each bit represents a different modifier key. Use 0 to specify no modifiers.
      Parameters:
        `keyChar` - the Character object for a keyboard character
        `modifiers` - a bitwise-ored combination of any modifiers
      Returns:
        an `AWTKeyStroke` object for that key
      Throws:
        `IllegalArgumentException` - if `keyChar` is `null`
      See Also:
        `InputEvent`

    - #### getAWTKeyStroke

          public static AWTKeyStroke getAWTKeyStroke(int keyCode,
                                     int modifiers,
                                     boolean onKeyRelease)

      Returns a shared instance of an `AWTKeyStroke`, given a numeric key code and a set of modifiers, specifying whether the key is activated when it is pressed or released.

      The "virtual key" constants defined in `java.awt.event.KeyEvent` can be used to specify the key code. For example:

      - `java.awt.event.KeyEvent.VK_ENTER`
      - `java.awt.event.KeyEvent.VK_TAB`
      - `java.awt.event.KeyEvent.VK_SPACE`
      Alternatively, the key code may be obtained by calling `java.awt.event.KeyEvent.getExtendedKeyCodeForChar`. The modifiers consist of any combination of:
      - java.awt.event.InputEvent.SHIFT_DOWN_MASK
      - java.awt.event.InputEvent.CTRL_DOWN_MASK
      - java.awt.event.InputEvent.META_DOWN_MASK
      - java.awt.event.InputEvent.ALT_DOWN_MASK
      - java.awt.event.InputEvent.ALT_GRAPH_DOWN_MASK
      The old modifiers
      - java.awt.event.InputEvent.SHIFT_MASK
      - java.awt.event.InputEvent.CTRL_MASK
      - java.awt.event.InputEvent.META_MASK
      - java.awt.event.InputEvent.ALT_MASK
      - java.awt.event.InputEvent.ALT_GRAPH_MASK
      also can be used, but they are mapped to _DOWN_ modifiers. Since these numbers are all different powers of two, any combination of them is an integer in which each bit represents a different modifier key. Use 0 to specify no modifiers.
      Parameters:
        `keyCode` - an int specifying the numeric code for a keyboard key
        `modifiers` - a bitwise-ored combination of any modifiers
        `onKeyRelease` - `true` if the `AWTKeyStroke` should represent a key release; `false` otherwise
      Returns:
        an AWTKeyStroke object for that key
      See Also:
        `KeyEvent`, `InputEvent`

    - #### getAWTKeyStroke

          public static AWTKeyStroke getAWTKeyStroke(int keyCode,
                                     int modifiers)

      Returns a shared instance of an `AWTKeyStroke`, given a numeric key code and a set of modifiers. The returned `AWTKeyStroke` will correspond to a key press.

      The "virtual key" constants defined in `java.awt.event.KeyEvent` can be used to specify the key code. For example:

      - `java.awt.event.KeyEvent.VK_ENTER`
      - `java.awt.event.KeyEvent.VK_TAB`
      - `java.awt.event.KeyEvent.VK_SPACE`
      The modifiers consist of any combination of:
      - java.awt.event.InputEvent.SHIFT_DOWN_MASK
      - java.awt.event.InputEvent.CTRL_DOWN_MASK
      - java.awt.event.InputEvent.META_DOWN_MASK
      - java.awt.event.InputEvent.ALT_DOWN_MASK
      - java.awt.event.InputEvent.ALT_GRAPH_DOWN_MASK
      The old modifiers
      - java.awt.event.InputEvent.SHIFT_MASK
      - java.awt.event.InputEvent.CTRL_MASK
      - java.awt.event.InputEvent.META_MASK
      - java.awt.event.InputEvent.ALT_MASK
      - java.awt.event.InputEvent.ALT_GRAPH_MASK
      also can be used, but they are mapped to _DOWN_ modifiers. Since these numbers are all different powers of two, any combination of them is an integer in which each bit represents a different modifier key. Use 0 to specify no modifiers.
      Parameters:
        `keyCode` - an int specifying the numeric code for a keyboard key
        `modifiers` - a bitwise-ored combination of any modifiers
      Returns:
        an `AWTKeyStroke` object for that key
      See Also:
        `KeyEvent`, `InputEvent`

    - #### getAWTKeyStrokeForEvent

          public static AWTKeyStroke getAWTKeyStrokeForEvent(KeyEvent anEvent)

      Returns an `AWTKeyStroke` which represents the stroke which generated a given `KeyEvent`.

      This method obtains the keyChar from a `KeyTyped` event, and the keyCode from a `KeyPressed` or `KeyReleased` event. The `KeyEvent` modifiers are obtained for all three types of `KeyEvent`.

      Parameters:
        `anEvent` - the `KeyEvent` from which to obtain the `AWTKeyStroke`
      Returns:
        the `AWTKeyStroke` that precipitated the event
      Throws:
        `NullPointerException` - if `anEvent` is null

    - #### getAWTKeyStroke

          public static AWTKeyStroke getAWTKeyStroke(String s)

      Parses a string and returns an `AWTKeyStroke`. The string must have the following syntax:

              <modifiers>* (<typedID> | <pressedReleasedID>)

              modifiers := shift | control | ctrl | meta | alt | altGraph
              typedID := typed <typedKey>
              typedKey := string of length 1 giving Unicode character.
              pressedReleasedID := (pressed | released) key
              key := KeyEvent key code name, i.e. the name following "VK_".

      If typed, pressed or released is not specified, pressed is assumed. Here are some examples:

               "INSERT" => getAWTKeyStroke(KeyEvent.VK_INSERT, 0);
               "control DELETE" => getAWTKeyStroke(KeyEvent.VK_DELETE, InputEvent.CTRL_MASK);
               "alt shift X" => getAWTKeyStroke(KeyEvent.VK_X, InputEvent.ALT_MASK | InputEvent.SHIFT_MASK);
               "alt shift released X" => getAWTKeyStroke(KeyEvent.VK_X, InputEvent.ALT_MASK | InputEvent.SHIFT_MASK, true);
               "typed a" => getAWTKeyStroke('a');

      Parameters:
        `s` - a String formatted as described above
      Returns:
        an `AWTKeyStroke` object for that String
      Throws:
        `IllegalArgumentException` - if `s` is `null`, or is formatted incorrectly

    - #### getKeyChar

          public final char getKeyChar()

      Returns the character for this `AWTKeyStroke`.
      Returns:
        a char value
      See Also:
        `getAWTKeyStroke(char)`, `KeyEvent.getKeyChar()`

    - #### getKeyCode

          public final int getKeyCode()

      Returns the numeric key code for this `AWTKeyStroke`.
      Returns:
        an int containing the key code value
      See Also:
        `getAWTKeyStroke(int,int)`, `KeyEvent.getKeyCode()`

    - #### getModifiers

          public final int getModifiers()

      Returns the modifier keys for this `AWTKeyStroke`.
      Returns:
        an int containing the modifiers
      See Also:
        `getAWTKeyStroke(int,int)`

    - #### isOnKeyRelease

          public final boolean isOnKeyRelease()

      Returns whether this `AWTKeyStroke` represents a key release.
      Returns:
        `true` if this `AWTKeyStroke` represents a key release; `false` otherwise
      See Also:
        `getAWTKeyStroke(int,int,boolean)`

    - #### getKeyEventType

          public final int getKeyEventType()

      Returns the type of `KeyEvent` which corresponds to this `AWTKeyStroke`.
      Returns:
        `KeyEvent.KEY_PRESSED`, `KeyEvent.KEY_TYPED`, or `KeyEvent.KEY_RELEASED`
      See Also:
        `KeyEvent`

    - #### hashCode

          public int hashCode()

      Returns a numeric value for this object that is likely to be unique, making it a good choice as the index value in a hash table.
      Overrides:
        `hashCode` in class `Object`
      Returns:
        an int that represents this object
      See Also:
        `Object.equals(java.lang.Object)`, `System.identityHashCode(java.lang.Object)`

    - #### equals

          public final boolean equals(Object anObject)

      Returns true if this object is identical to the specified object.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `anObject` - the Object to compare this object to
      Returns:
        true if the objects are identical
      See Also:
        `Object.hashCode()`, `HashMap`

    - #### toString

          public String toString()

      Returns a string that displays and identifies this object's properties. The `String` returned by this method can be passed as a parameter to `getAWTKeyStroke(String)` to produce a key stroke equal to this key stroke.
      Overrides:
        `toString` in class `Object`
      Returns:
        a String representation of this object
      See Also:
        `getAWTKeyStroke(String)`

    - #### readResolve

          protected Object readResolve()
                                throws ObjectStreamException

      Returns a cached instance of `AWTKeyStroke` (or a subclass of `AWTKeyStroke`) which is equal to this instance.
      Returns:
        a cached instance which is equal to this instance
      Throws:
        `ObjectStreamException`

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.