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
`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
`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`

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)`, `Hashtable`

#### 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()`, `Hashtable`

#### 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`

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.