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
FormActionis created (defined by anActionDataobject) 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 concreteActionManagerimplementation is responsible for converting a genericAcceleratorobject 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_XXXconstants of theKeyEventclass). 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 booleanequals(Object obj)Compares this object with another one.static AcceleratorgetInstance(Character key, Set<Modifiers> modifiers)Returns anAcceleratorfor the specified printable key and the (optional) modifiers.static AcceleratorgetInstance(Integer keyCode, Set<Modifiers> modifiers)Returns anAcceleratorfor the specified platform-specific key code and the (optional) modifiers.static AcceleratorgetInstance(Keys key, Set<Modifiers> modifiers)Returns anAcceleratorfor the specified special key and the (optional) modifiers.CharactergetKey()Returns the character.IntegergetKeyCode()Returns the key code.Set<Modifiers>getModifiers()Returns a set with the modifiers set for this accelerator.KeysgetSpecialKey()Returns the special key.inthashCode()Returns a hash code for this object.static Acceleratorparse(String s)Returns anAcceleratorinstance from the specified string representation.StringtoString()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 themethod, i.e. they can be used for creatingparse(String)Acceleratorinstances. They are normalized in the following way:- Modifiers are listed in their natural order (this is the order in
which the
enumconstants 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 anAcceleratorfor 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
Acceleratorinstance - Throws:
IllegalArgumentException- if the key is undefined
-
getInstance
public static Accelerator getInstance(Character key, Set<Modifiers> modifiers)
Returns anAcceleratorfor 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
Acceleratorinstance - Throws:
IllegalArgumentException- if the key is undefined
-
getInstance
public static Accelerator getInstance(Integer keyCode, Set<Modifiers> modifiers)
Returns anAcceleratorfor 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
Acceleratorinstance - Throws:
IllegalArgumentException- if the key is undefined
-
parse
public static Accelerator parse(String s)
Returns an
Acceleratorinstance from the specified string representation. The string must be a valid representation of anAcceleratorinstance as it is returned by thetoString()method. Otherwise anIllegalArgumentExceptionexception 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 theModifiersenumeration (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
Keysenumeration, 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
Acceleratorinstance - Throws:
IllegalArgumentException- if the string cannot be parsed
-
-