net.sf.jguiraffe.gui.builder.action

Class Accelerator

java.lang.Object

net.sf.jguiraffe.gui.builder.action.Accelerator

public final class Accelerator
extends Object

A class that represents an accelerator for invoking an action.

An accelerator is a key (or a combination of keys, typically associated with some modifier keys like SHIFT or ALT) that triggers an action when pressed. Thus it is a keyboard short cut that has the same effect as clicking a tool bar button or selecting a menu element. When a FormAction is created (defined by an ActionData object) an accelerator can be specified. This can have effect on GUI elements associated with this action. For instance, menus will typically display the keyboard combinations that correspond to the menu elements.

This class has the same purpose as javax.swing.KeyStroke: serving as an abstract description of a combination of key presses. However, it is more tailored towards the builder approach followed by this library. This means that the main use case of this class is being created indirectly in a builder script (mostly using a text representation) and then being passed to an implementation of ActionManager. A concrete ActionManager implementation is responsible for converting a generic Accelerator object into a platform-specific representation of a key stroke.

Instances of this class store a set of modifiers (like SHIFT or CONTROL) that must be pressed together with the key. The actual key can be specified in the following different ways:

• If it is a "normal" (i.e. printable) character, it can be queried using the getKey() method, which returns a Character.
• For special keys like the function keys, Escape, or Enter enumeration literals are defined. If such a key is used for the accelerator, the getSpecialKey() method will return a non-null value.
• It is also possible to use a key code specific to a concrete GUI library, e.g. a virtual key code used within Swing (the VK_XXX constants of the KeyEvent class). If such a code is set, it can be queried using the getKeyCode() method. Note that this variant is not portable.

Exactly one of the methods listed above will return a non-null value.

Implementation note: Instances of this class are immutable and can be shared among multiple threads.

Version:

$Id: Accelerator.java 205 2012-01-29 18:29:57Z oheger $

Author:

Oliver Heger

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object obj) Compares this object with another one.
static Accelerator	getInstance(Character key, Set<Modifiers> modifiers) Returns an Accelerator for the specified printable key and the (optional) modifiers.
static Accelerator	getInstance(Integer keyCode, Set<Modifiers> modifiers) Returns an Accelerator for the specified platform-specific key code and the (optional) modifiers.
static Accelerator	getInstance(Keys key, Set<Modifiers> modifiers) Returns an Accelerator for the specified special key and the (optional) modifiers.
Character	getKey() Returns the character.
Integer	getKeyCode() Returns the key code.
Set<Modifiers>	getModifiers() Returns a set with the modifiers set for this accelerator.
Keys	getSpecialKey() Returns the special key.
int	hashCode() Returns a hash code for this object.
static Accelerator	parse(String s) Returns an Accelerator instance from the specified string representation.
String	toString() Returns a string representation of this object.

Methods inherited from class java.lang.Object

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

Method Detail

getModifiers

public Set<Modifiers> getModifiers()

Returns a set with the modifiers set for this accelerator. These are special mode keys (like SHIFT or CONTROL) that must be pressed together with the actual key for triggering this accelerator.

Returns:

a set with the modifiers (this set cannot be modified)

getSpecialKey

public Keys getSpecialKey()

Returns the special key. If this accelerator is represented by a special key (for which a constant is available), this key is returned by this method. Otherwise null is returned.

Returns:

the special key representing this accelerator or null

getKey

public Character getKey()

Returns the character. If the key of this accelerator is a printable character, it is returned by this method. Otherwise result is null.

Returns:

the character of this accelerator or null

getKeyCode

public Integer getKeyCode()

Returns the key code. If this accelerator is represented by a (platform-specific) key code, this code is returned here. Otherwise result is null.

Returns:

the key code representing this accelerator or null

toString

public String toString()

Returns a string representation of this object. Strings returned by this method are compatible with the parse(String) method, i.e. they can be used for creating Accelerator instances. They are normalized in the following way:

• Modifiers are listed in their natural order (this is the order in which the enum constants are declared and happens to be alphabetic order).
• For each component of the string a single space is used as separator.
• All constants are written in capital letters.

Overrides:

toString in class Object

Returns:

a string for this object

equals

public boolean equals(Object obj)

Compares this object with another one. Two objects are equal if and only if they use the same way of describing the key and have the same modifiers.

Overrides:

equals in class Object

Parameters:

obj - the object to compare

Returns:

a flag whether these objects are equal

hashCode

public int hashCode()

Returns a hash code for this object.

Overrides:

hashCode in class Object

Returns:

a hash code

getInstance

public static Accelerator getInstance(Keys key,
                                      Set<Modifiers> modifiers)

Returns an Accelerator for the specified special key and the (optional) modifiers.

Parameters:

key - the special key for this accelerator (must not be null)

modifiers - a set with modifiers (can be null)

Returns:

the Accelerator instance

Throws:

IllegalArgumentException - if the key is undefined

getInstance

public static Accelerator getInstance(Character key,
                                      Set<Modifiers> modifiers)

Returns an Accelerator for the specified printable key and the (optional) modifiers.

Parameters:

key - the character for this accelerator (must not be null)

modifiers - a set with modifiers (can be null)

Returns:

the Accelerator instance

Throws:

IllegalArgumentException - if the key is undefined

getInstance

public static Accelerator getInstance(Integer keyCode,
                                      Set<Modifiers> modifiers)

Returns an Accelerator for the specified platform-specific key code and the (optional) modifiers.

Parameters:

keyCode - the special key code for this accelerator (must not be null)

modifiers - a set with modifiers (can be null)

Returns:

the Accelerator instance

Throws:

IllegalArgumentException - if the key is undefined

parse

public static Accelerator parse(String s)

Returns an Accelerator instance from the specified string representation. The string must be a valid representation of an Accelerator instance as it is returned by the toString() method. Otherwise an IllegalArgumentException exception will be thrown.

Valid strings have the following form:

 acceleratorString ::= (<modifier>)* keySpec
 keySpec           ::= <character> | <specialKey> | <keyCode>
 

With other words: The string can contain multiple components all separated by whitespace. The last component defines the actual keys, all others are interpreted as modifiers. They must conform to literals of the Modifiers enumeration (case does not matter). For the last component, there are the following possibilities:

• If it is a string of length 1, it is interpreted as a printable character.
• If it is a literal defined in the Keys enumeration, the corresponding special key is set (the comparison is not case sensitive).
• If it is a number, it is parsed to an integer and interpreted as key code. Note that there is an ambiguity for key codes consisting of a single digit (0-9). Because they are represented by a string with the length 1 they are interpreted as characters (see above). To avoid this, add a leading 0, e.g. "05".

Here are some examples:

"A"

This is simply the letter A without any modifiers.

control A

The letter A with the CONTROL modifier.

Shift CONTROL A

The letter A with both the SHIFT and the CONTROL modifier. Note that case of the modifiers does not matter. The same is true for the order in which they are given.

Alt Backspace

The backspace key plus the ALT modifier (as is often used as undo command). For special keys case does not matter either.

F1

The F1 function key, as is often used for the help command.

42

A special key code with the numeric value of 42.

CONTROL 5

The character '5' plus the CONTROL modifier.

CONTROL 05

The numeric key code 5 (whatever this means) plus the CONTROL modifier. Note that here a leading 0 must be used, otherwise the number will be interpreted as character.

If the whole string is null or empty, null is returned.

Parameters:

s - the string to be parsed (can be null)

Returns:

the corresponding Accelerator instance

Throws:

IllegalArgumentException - if the string cannot be parsed