javax.swing
Class KeyStroke

java.lang.Object
  |
  +--javax.swing.KeyStroke

All Implemented Interfaces:

Serializable

public class KeyStroke

extends Object

implements Serializable

A KeyStroke instance represents a key being typed on the keyboard -- it contains both a char code for the key and a modifier (alt, shift, ctrl, meta, or a combination).

KeyStroke objects are used to define high-level (semantic) action events. Instead of trapping every keystroke and throwing away the ones you are not interested in, those keystrokes you care about automatically initiate actions on the components they are registered with.

KeyStroke objects handle both character-code generating keystrokes you would trap with a KeyTyped event handler and key-code generating keystrokes (like Enter or F1) that you would trap with a KeyPressed event handler.

KeyStroke objects are immutable and unique.

All KeyStroke objects are cached. To get one, use getKeyStroke.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. A future release of Swing will provide support for long term persistence.

See Also:

Keymap, getKeyStroke(char), Serialized Form

Method Summary

boolean	equals(Object anObject) Returns true if this object is identical to the specified object.
char	getKeyChar() Returns the character defined by this KeyStroke object.
int	getKeyCode() Returns the numeric keycode defined by this KeyStroke object.
static KeyStroke	getKeyStroke(char keyChar) Return a shared instance of a key stroke that is activated when the key is pressed (that is, a KeyStroke for the KEY_TYPED event).
static KeyStroke	getKeyStroke(Character keyChar, int modifiers) Return a shared instance of a key stroke, given a character object and a set of modifiers.
static KeyStroke	getKeyStroke(char keyChar, boolean onKeyRelease) Deprecated. use getKeyStroke(char)
static KeyStroke	getKeyStroke(int keyCode, int modifiers) Return a shared instance of a key stroke given a char code and a set of modifiers -- the key is activated when it is pressed.
static KeyStroke	getKeyStroke(int keyCode, int modifiers, boolean onKeyRelease) Return a shared instance of a key stroke given a numeric keycode and a set of modifiers, specifying whether the key is activated when it is pressed or released.
static KeyStroke	getKeyStroke(String s) Parse a string and return a KeyStroke.
static KeyStroke	getKeyStrokeForEvent(KeyEvent anEvent) Return a keystroke from an event.
int	getModifiers() Returns the modifier keys defined by this KeyStroke object.
int	hashCode() Returns a numeric value for this object that is likely to be reasonably unique, so it can be used as the index value in a Hashtable.
boolean	isOnKeyRelease() Returns true if this keystroke is active on key release.
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

Method Detail

getKeyStroke

public static KeyStroke getKeyStroke(char keyChar)

Return a shared instance of a key stroke that is activated when the key is pressed (that is, a KeyStroke for the KEY_TYPED event).

Parameters:

keyChar - the character value for a keyboard key

Returns:

a KeyStroke object for that key

getKeyStroke

public static KeyStroke getKeyStroke(char keyChar,
                                     boolean onKeyRelease)

Deprecated. use getKeyStroke(char)

Return a shared instance of a key stroke, specifying whether the key is considered to be activated when it is pressed or when it is released.

Parameters:

keyChar - the character value for a keyboard key

onKeyRelease - a boolean value. When true, specifies that the key is active when it is released.

Returns:

a KeyStroke object for that key

getKeyStroke

public static KeyStroke getKeyStroke(Character keyChar,
                                     int modifiers)

Return a shared instance of a key stroke, given a character object and a set of modifiers. Note that the first parameter is of type Character rather than char. This is to avoid clashes with code that existed prior to the introduction of this method, which may have been calling getKeyStroke(int keyCode, int modifiers) with quoted characters and relying on their automatic conversion to type int. The modifiers consist of any combination of:

• java.awt.Event.SHIFT_MASK (1)
• java.awt.Event.CTRL_MASK (2)
• java.awt.Event.META_MASK (4)
• java.awt.Event.ALT_MASK (8)

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.

Parameters:

keyChar - the character object for a keyboard character.

modifiers - an int specifying any combination of the key modifiers.

Returns:

a KeyStroke object for that key

Since:

1.3

getKeyStroke

public static KeyStroke getKeyStroke(int keyCode,
                                     int modifiers,
                                     boolean onKeyRelease)

Return a shared instance of a key stroke given a numeric keycode 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.SHIFT_MASK (1)
• java.awt.Event.CTRL_MASK (2)
• java.awt.Event.META_MASK (4)
• java.awt.Event.ALT_MASK (8)

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.

Parameters:

keyCode - an int specifying the numeric code for a keyboard key

modifiers - an int specifying any combination of the key modifiers.

onKeyRelease - a boolean value. When true, specifies that the key is active when it is released.

Returns:

a KeyStroke object for that key

See Also:

KeyEvent, Event

getKeyStroke

public static KeyStroke getKeyStroke(int keyCode,
                                     int modifiers)

Return a shared instance of a key stroke given a char code and a set of modifiers -- the key is activated when it is pressed.

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.SHIFT_MASK (1)
• java.awt.Event.CTRL_MASK (2)
• java.awt.Event.META_MASK (4)
• java.awt.Event.ALT_MASK (8)

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.

Parameters:

keyCode - an int specifying the numeric code for a keyboard key

modifiers - an int specifying any combination of the key modifiers.

Returns:

a KeyStroke object for that key

See Also:

KeyEvent

getKeyStrokeForEvent

public static KeyStroke getKeyStrokeForEvent(KeyEvent anEvent)

Return a keystroke from an event.

This method obtains the keyChar from a KeyTyped event, and the keyCode from a KeyPressed or KeyReleased event, so you the type of event doesn't matter.

Parameters:

anEvent - the KeyEvent to obtain the KeyStroke from

Returns:

the KeyStroke that precipitated the event

getKeyStroke

public static KeyStroke getKeyStroke(String s)

Parse a string and return a KeyStroke. The string has the following syntax:

    <modifiers>* (<typedID> | <pressedReleasedID>)
    modifiers := shift | control | meta | alt | button1 | button2 | button3
    typedID := typed <typedKey>
    typedKey := string of length 1 giving unicode character.
    pressedReleasedID := (pressed | released)? key
 key := KeyEvent keycode name, i.e. the name following "VK_".
 

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

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

For backward compatability, this will return null if s is not in the above format.

getKeyChar

public char getKeyChar()

Returns the character defined by this KeyStroke object.

Returns:

a char value

See Also:

getKeyStroke(char)

getKeyCode

public int getKeyCode()

Returns the numeric keycode defined by this KeyStroke object.

Returns:

an int containing the keycode value

See Also:

getKeyStroke(int,int)

getModifiers

public int getModifiers()

Returns the modifier keys defined by this KeyStroke object.

Returns:

an int containing the modifiers

See Also:

getKeyStroke(int,int)

isOnKeyRelease

public boolean isOnKeyRelease()

Returns true if this keystroke is active on key release.

Returns:

true if active on key release, false if active on key press

See Also:

getKeyStroke(int,int,boolean)

hashCode

public int hashCode()

Returns a numeric value for this object that is likely to be reasonably unique, so it can be used as the index value in a Hashtable.

Overrides:

hashCode in class Object

Returns:

an int that "represents" this object

See Also:

Hashtable

equals

public 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

toString

public String toString()

Returns a string that displays and identifies this object's properties.

Overrides:

toString in class Object

Returns:

a String representation of this object