java.awt

Class AWTKeyStroke

public class AWTKeyStroke extends Object implements Serializable

This class mirrors KeyEvents, representing both low-level key presses and key releases, and high level key typed inputs. However, this class forms immutable strokes, and can be efficiently reused via the factory methods for creating them.

For backwards compatibility with Swing, this supports a way to build instances of a subclass, using reflection, provided the subclass has a no-arg constructor (of any accessibility).

Since: 1.4

See Also: AWTKeyStroke

UNKNOWN: updated to 1.4

Constructor Summary
protected	AWTKeyStroke() Construct a keystroke with default values: it will be interpreted as a key typed event with an invalid character and no modifiers.
protected	AWTKeyStroke(char keyChar, int keyCode, int modifiers, boolean onKeyRelease) Construct a keystroke with the given values.

Method Summary
boolean	equals(Object o) Tests two keystrokes for equality.
static AWTKeyStroke	getAWTKeyStroke(char keyChar) Returns a keystroke representing a typed character.
static AWTKeyStroke	getAWTKeyStroke(Character keyChar, int modifiers) Returns a keystroke representing a typed character with the given modifiers.
static AWTKeyStroke	getAWTKeyStroke(int keyCode, int modifiers, boolean release) Returns a keystroke representing a pressed or released key event, with the given modifiers.
static AWTKeyStroke	getAWTKeyStroke(int keyCode, int modifiers) Returns a keystroke representing a pressed key event, with the given modifiers.
static AWTKeyStroke	getAWTKeyStroke(String s) Parses a string and returns the keystroke that it represents.
static AWTKeyStroke	getAWTKeyStrokeForEvent(KeyEvent event) Returns a keystroke representing what caused the key event.
char	getKeyChar() Returns the character of this keystroke, if it was typed.
int	getKeyCode() Returns the virtual key code of this keystroke, if it was pressed or released.
int	getKeyEventType() Returns the AWT event type of this keystroke.
int	getModifiers() Returns the modifiers for this keystroke.
int	hashCode() Returns a hashcode for this key event.
boolean	isOnKeyRelease() Tests if this keystroke is a key release.
protected Object	readResolve() Returns a cached version of the deserialized keystroke, if available.
protected static void	registerSubclass(Class<?> subclass) Registers a new subclass as being the type of keystrokes to generate in the factory methods.
String	toString() Returns a string representation of this keystroke.

Constructor Detail

AWTKeyStroke

protected AWTKeyStroke()

Construct a keystroke with default values: it will be interpreted as a key typed event with an invalid character and no modifiers. Client code should use the factory methods instead.

AWTKeyStroke

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

Construct a keystroke with the given values. Client code should use the factory methods instead.

Parameters: keyChar the character entered, if this is a key typed keyCode the key pressed or released, or VK_UNDEFINED for key typed modifiers the modifier keys for the keystroke, in old or new style onKeyRelease true if this is a key release instead of a press

Method Detail

equals

public final boolean equals(Object o)

Tests two keystrokes for equality.

Parameters: o the object to test

Returns: true if it is equal

getAWTKeyStroke

public static AWTKeyStroke getAWTKeyStroke(char keyChar)

Returns a keystroke representing a typed character.

Parameters: keyChar the typed character

Returns: the specified keystroke

getAWTKeyStroke

public static AWTKeyStroke getAWTKeyStroke(Character keyChar, int modifiers)

Returns a keystroke representing a typed character with the given modifiers. Note that keyChar is a Character instead of a char to avoid accidental ambiguity with getAWTKeyStroke(int, int). The modifiers are the bitwise or of the masks found in {@link InputEvent}; the new style (*_DOWN_MASK) is preferred, but the old style will work.

Parameters: keyChar the typed character modifiers the modifiers, or 0

Returns: the specified keystroke

Throws: IllegalArgumentException if keyChar is null

getAWTKeyStroke

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

Returns a keystroke representing a pressed or released key event, with the given modifiers. The "virtual key" should be one of the VK_* constants in {@link KeyEvent}. The modifiers are the bitwise or of the masks found in {@link InputEvent}; the new style (*_DOWN_MASK) is preferred, but the old style will work.

Parameters: keyCode the virtual key modifiers the modifiers, or 0 release true if this is a key release instead of a key press

Returns: the specified keystroke

getAWTKeyStroke

public static AWTKeyStroke getAWTKeyStroke(int keyCode, int modifiers)

Returns a keystroke representing a pressed key event, with the given modifiers. The "virtual key" should be one of the VK_* constants in {@link KeyEvent}. The modifiers are the bitwise or of the masks found in {@link InputEvent}; the new style (*_DOWN_MASK) is preferred, but the old style will work.

Parameters: keyCode the virtual key modifiers the modifiers, or 0

Returns: the specified keystroke

getAWTKeyStroke

public static AWTKeyStroke getAWTKeyStroke(String s)

Parses a string and returns the keystroke that it represents. The syntax for keystrokes is listed below, with tokens separated by an arbitrary number of spaces:

 keyStroke := <modifiers>* ( <typedID> | <codeID> )
 modifiers := ( shift | control | ctrl | meta | alt
                | button1 | button2 | button3 )
 typedID := typed <single Unicode character>
 codeID := ( pressed | released )? <name>
 name := <the KeyEvent field name less the leading "VK_">

Note that the grammar is rather weak, and not all valid keystrokes can be generated in this manner (for example, a typed space, or anything with the alt-graph modifier!). The output of AWTKeyStroke.toString() will not meet the grammar. If pressed or released is not specified, pressed is assumed. 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 the string to parse

Returns: the specified keystroke

Throws: IllegalArgumentException if s is null or cannot be parsed

getAWTKeyStrokeForEvent

public static AWTKeyStroke getAWTKeyStrokeForEvent(KeyEvent event)

Returns a keystroke representing what caused the key event.

Parameters: event the key event to convert

Returns: the specified keystroke, or null if the event is invalid

Throws: NullPointerException if event is null

getKeyChar

public final char getKeyChar()

Returns the character of this keystroke, if it was typed.

Returns: the character value, or CHAR_UNDEFINED

See Also: AWTKeyStroke

getKeyCode

public final int getKeyCode()

Returns the virtual key code of this keystroke, if it was pressed or released. This will be a VK_* constant from KeyEvent.

Returns: the virtual key code value, or VK_UNDEFINED

See Also: AWTKeyStroke

getKeyEventType

public final int getKeyEventType()

Returns the AWT event type of this keystroke. This is one of {@link KeyEvent#KEY_TYPED}, {@link KeyEvent#KEY_PRESSED}, or {@link KeyEvent#KEY_RELEASED}.

Returns: the key event type

getModifiers

public final int getModifiers()

Returns the modifiers for this keystroke. This will be a bitwise or of constants from InputEvent; it includes the old style masks for shift, control, alt, meta, and alt-graph (but not button1); as well as the new style of extended modifiers for all modifiers.

Returns: the modifiers

hashCode

public int hashCode()

Returns a hashcode for this key event. It is not documented, but appears to be:

(getKeyChar() + 1) * (getKeyCode() + 1)
 * (getModifiers() + 1) * 2 + (isOnKeyRelease() ? 1 : 2)

Returns: the hashcode

isOnKeyRelease

public final boolean isOnKeyRelease()

Tests if this keystroke is a key release.

Returns: true if this is a key release

See Also: AWTKeyStroke

readResolve

protected Object readResolve()

Returns a cached version of the deserialized keystroke, if available.

Returns: a cached replacement

Throws: ObjectStreamException if something goes wrong

registerSubclass

protected static void registerSubclass(Class<?> subclass)

Registers a new subclass as being the type of keystrokes to generate in the factory methods. This operation flushes the cache of stored keystrokes if the class differs from the current one. The new class must be AWTKeyStroke or a subclass, and must have a no-arg constructor (which may be private).

Parameters: subclass the new runtime type of generated keystrokes

Throws: IllegalArgumentException subclass doesn't have no-arg constructor ClassCastException subclass doesn't extend AWTKeyStroke

toString

public String toString()

Returns a string representation of this keystroke. For typed keystrokes, this is

"keyChar " + KeyEvent.getKeyModifiersText(getModifiers())
   + getKeyChar()

; for pressed and released keystrokes, this is

"keyCode " + KeyEvent.getKeyModifiersText(getModifiers())
 + KeyEvent.getKeyText(getKeyCode())
 + (isOnKeyRelease() ? "-R" : "-P")

Returns: a string representation