Module java.desktop
Package 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
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

Modifier and Type
Method
Description
`final 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(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(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(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`.
`final char`
`getKeyChar()`
Returns the character for this `AWTKeyStroke`.
`final int`
`getKeyCode()`
Returns the numeric key code for this `AWTKeyStroke`.
`final int`
`getKeyEventType()`
Returns the type of `KeyEvent` which corresponds to this `AWTKeyStroke`.
`final 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.
`final 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)`
Deprecated.
`String`
`toString()`
Returns a string that displays and identifies this object's properties.

### Methods declared in class java.lang.Object

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

## Constructor Details

### AWTKeyStroke

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

AWTKeyStroke default values
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 Details

### registerSubclass

@Deprecated protected static void registerSubclass(Class<?> subclass)
Deprecated.
The method has no effect and is only left present to avoid introducing a binary incompatibility.

Parameters:
  `subclass` - the new Class of which the factory methods should create instances

### 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` - if a serialization problem occurs