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 anActionData
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 ofActionManager
. A concreteActionManager
implementation is responsible for converting a genericAccelerator
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 aCharacter
. - 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 theKeyEvent
class). If such a code is set, it can be queried using thegetKeyCode()
method. Note that this variant is not portable.
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
- If it is a "normal" (i.e. printable) character, it can be queried using
the
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
equals(Object obj)
Compares this object with another one.static Accelerator
getInstance(Character key, Set<Modifiers> modifiers)
Returns anAccelerator
for the specified printable key and the (optional) modifiers.static Accelerator
getInstance(Integer keyCode, Set<Modifiers> modifiers)
Returns anAccelerator
for the specified platform-specific key code and the (optional) modifiers.static Accelerator
getInstance(Keys key, Set<Modifiers> modifiers)
Returns anAccelerator
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 anAccelerator
instance from the specified string representation.String
toString()
Returns a string representation of this object.
-
-
-
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
method, i.e. they can be used for creatingparse(String)
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.
- Modifiers are listed in their natural order (this is the order in
which the
-
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.
-
hashCode
public int hashCode()
Returns a hash code for this object.
-
getInstance
public static Accelerator getInstance(Keys key, Set<Modifiers> modifiers)
Returns anAccelerator
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 anAccelerator
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 anAccelerator
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 anAccelerator
instance as it is returned by thetoString()
method. Otherwise anIllegalArgumentException
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 theModifiers
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
-
-