KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > swing > KeyStroke


1 /*
2  * @(#)KeyStroke.java 1.49 04/05/18
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7 package javax.swing;
8
9 import java.awt.AWTKeyStroke JavaDoc;
10 import java.awt.event.KeyEvent JavaDoc;
11
12 /**
13  * A KeyStroke represents a key action on the keyboard, or equivalent input
14  * device. KeyStrokes can correspond to only a press or release of a particular
15  * key, just as KEY_PRESSED and KEY_RELEASED KeyEvents do; alternately, they
16  * can correspond to typing a specific Java character, just as KEY_TYPED
17  * KeyEvents do. In all cases, KeyStrokes can specify modifiers (alt, shift,
18  * control, meta, or a combination thereof) which must be present during the
19  * action for an exact match.
20  * <p>
21  * KeyStrokes are used to define high-level (semantic) action events. Instead
22  * of trapping every keystroke and throwing away the ones you are not
23  * interested in, those keystrokes you care about automatically initiate
24  * actions on the Components with which they are registered.
25  * <p>
26  * KeyStrokes are immutable, and are intended to be unique. Client code cannot
27  * create a KeyStroke; a variant of <code>getKeyStroke</code> must be used
28  * instead. These factory methods allow the KeyStroke implementation to cache
29  * and share instances efficiently.
30  * <p>
31  * <strong>Warning:</strong>
32  * Serialized objects of this class will not be compatible with
33  * future Swing releases. The current serialization support is
34  * appropriate for short term storage or RMI between applications running
35  * the same version of Swing. As of 1.4, support for long term storage
36  * of all JavaBeans<sup><font size="-2">TM</font></sup>
37  * has been added to the <code>java.beans</code> package.
38  * Please see {@link java.beans.XMLEncoder}.
39  *
40  * @see javax.swing.text.Keymap
41  * @see #getKeyStroke
42  *
43  * @version 1.49, 05/18/04
44  * @author Arnaud Weber
45  * @author David Mendenhall
46  */

47 public class KeyStroke extends AWTKeyStroke JavaDoc {
48
49     /**
50      * Serial Version ID.
51      */

52     private static final long serialVersionUID = -9060180771037902530L;
53
54     private KeyStroke() {
55     }
56     private KeyStroke(char keyChar, int keyCode, int modifiers,
57               boolean onKeyRelease) {
58         super(keyChar, keyCode, modifiers, onKeyRelease);
59     }
60
61     /**
62      * Returns a shared instance of a <code>KeyStroke</code>
63      * that represents a <code>KEY_TYPED</code> event for the
64      * specified character.
65      *
66      * @param keyChar the character value for a keyboard key
67      * @return a KeyStroke object for that key
68      */

69     public static KeyStroke JavaDoc getKeyStroke(char keyChar) {
70         synchronized (AWTKeyStroke JavaDoc.class) {
71         registerSubclass(KeyStroke JavaDoc.class);
72         return (KeyStroke JavaDoc)getAWTKeyStroke(keyChar);
73     }
74     }
75
76     /**
77      * Returns an instance of a KeyStroke, specifying whether the key is
78      * considered to be activated when it is pressed or released. Unlike all
79      * other factory methods in this class, the instances returned by this
80      * method are not necessarily cached or shared.
81      *
82      * @param keyChar the character value for a keyboard key
83      * @param onKeyRelease <code>true</code> if this KeyStroke corresponds to a
84      * key release; <code>false</code> otherwise.
85      * @return a KeyStroke object for that key
86      * @deprecated use getKeyStroke(char)
87      */

88     @Deprecated JavaDoc
89     public static KeyStroke JavaDoc getKeyStroke(char keyChar, boolean onKeyRelease) {
90         return new KeyStroke JavaDoc(keyChar, KeyEvent.VK_UNDEFINED, 0, onKeyRelease);
91     }
92
93     /**
94      * Returns a shared instance of a KeyStroke, given a Character object and a
95      * set of modifiers. Note that the first parameter is of type Character
96      * rather than char. This is to avoid inadvertent clashes with calls to
97      * <code>getKeyStroke(int keyCode, int modifiers)</code>.
98      *
99      * The modifiers consist of any combination of:<ul>
100      * <li>java.awt.event.InputEvent.SHIFT_MASK (1)
101      * <li>java.awt.event.InputEvent.CTRL_MASK (2)
102      * <li>java.awt.event.InputEvent.META_MASK (4)
103      * <li>java.awt.event.InputEvent.ALT_MASK (8)
104      * </ul>
105      * Since these numbers are all different powers of two, any combination of
106      * them is an integer in which each bit represents a different modifier
107      * key. Use 0 to specify no modifiers.
108      *
109      * @param keyChar the Character object for a keyboard character
110      * @param modifiers a bitwise-ored combination of any modifiers
111      * @return an KeyStroke object for that key
112      * @throws IllegalArgumentException if keyChar is null
113      *
114      * @see java.awt.event.InputEvent
115      * @since 1.3
116      */

117     public static KeyStroke JavaDoc getKeyStroke(Character JavaDoc keyChar, int modifiers) {
118         synchronized (AWTKeyStroke JavaDoc.class) {
119         registerSubclass(KeyStroke JavaDoc.class);
120         return (KeyStroke JavaDoc)getAWTKeyStroke(keyChar, modifiers);
121     }
122     }
123
124     /**
125      * Returns a shared instance of a KeyStroke, given a numeric key code and a
126      * set of modifiers, specifying whether the key is activated when it is
127      * pressed or released.
128      * <p>
129      * The "virtual key" constants defined in java.awt.event.KeyEvent can be
130      * used to specify the key code. For example:<ul>
131      * <li>java.awt.event.KeyEvent.VK_ENTER
132      * <li>java.awt.event.KeyEvent.VK_TAB
133      * <li>java.awt.event.KeyEvent.VK_SPACE
134      * </ul>
135      * The modifiers consist of any combination of:<ul>
136      * <li>java.awt.event.InputEvent.SHIFT_MASK (1)
137      * <li>java.awt.event.InputEvent.CTRL_MASK (2)
138      * <li>java.awt.event.InputEvent.META_MASK (4)
139      * <li>java.awt.event.InputEvent.ALT_MASK (8)
140      * </ul>
141      * Since these numbers are all different powers of two, any combination of
142      * them is an integer in which each bit represents a different modifier
143      * key. Use 0 to specify no modifiers.
144      *
145      * @param keyCode an int specifying the numeric code for a keyboard key
146      * @param modifiers a bitwise-ored combination of any modifiers
147      * @param onKeyRelease <code>true</code> if the KeyStroke should represent
148      * a key release; <code>false</code> otherwise.
149      * @return a KeyStroke object for that key
150      *
151      * @see java.awt.event.KeyEvent
152      * @see java.awt.event.InputEvent
153      */

154     public static KeyStroke JavaDoc getKeyStroke(int keyCode, int modifiers,
155                      boolean onKeyRelease) {
156         synchronized (AWTKeyStroke JavaDoc.class) {
157         registerSubclass(KeyStroke JavaDoc.class);
158         return (KeyStroke JavaDoc)getAWTKeyStroke(keyCode, modifiers,
159                           onKeyRelease);
160     }
161     }
162
163     /**
164      * Returns a shared instance of a KeyStroke, given a numeric key code and a
165      * set of modifiers. The returned KeyStroke will correspond to a key press.
166      * <p>
167      * The "virtual key" constants defined in java.awt.event.KeyEvent can be
168      * used to specify the key code. For example:<ul>
169      * <li>java.awt.event.KeyEvent.VK_ENTER
170      * <li>java.awt.event.KeyEvent.VK_TAB
171      * <li>java.awt.event.KeyEvent.VK_SPACE
172      * </ul>
173      * The modifiers consist of any combination of:<ul>
174      * <li>java.awt.event.InputEvent.SHIFT_MASK (1)
175      * <li>java.awt.event.InputEvent.CTRL_MASK (2)
176      * <li>java.awt.event.InputEvent.META_MASK (4)
177      * <li>java.awt.event.InputEvent.ALT_MASK (8)
178      * </ul>
179      * Since these numbers are all different powers of two, any combination of
180      * them is an integer in which each bit represents a different modifier
181      * key. Use 0 to specify no modifiers.
182      *
183      * @param keyCode an int specifying the numeric code for a keyboard key
184      * @param modifiers a bitwise-ored combination of any modifiers
185      * @return a KeyStroke object for that key
186      *
187      * @see java.awt.event.KeyEvent
188      * @see java.awt.event.InputEvent
189      */

190     public static KeyStroke JavaDoc getKeyStroke(int keyCode, int modifiers) {
191         synchronized (AWTKeyStroke JavaDoc.class) {
192         registerSubclass(KeyStroke JavaDoc.class);
193         return (KeyStroke JavaDoc)getAWTKeyStroke(keyCode, modifiers);
194     }
195     }
196
197     /**
198      * Returns a KeyStroke which represents the stroke which generated a given
199      * KeyEvent.
200      * <p>
201      * This method obtains the keyChar from a KeyTyped event, and the keyCode
202      * from a KeyPressed or KeyReleased event. The KeyEvent modifiers are
203      * obtained for all three types of KeyEvent.
204      *
205      * @param anEvent the KeyEvent from which to obtain the KeyStroke
206      * @throws NullPointerException if <code>anEvent</code> is null
207      * @return the KeyStroke that precipitated the event
208      */

209     public static KeyStroke JavaDoc getKeyStrokeForEvent(KeyEvent JavaDoc anEvent) {
210         synchronized (AWTKeyStroke JavaDoc.class) {
211         registerSubclass(KeyStroke JavaDoc.class);
212         return (KeyStroke JavaDoc)getAWTKeyStrokeForEvent(anEvent);
213     }
214     }
215
216     /**
217      * Parses a string and returns a <code>KeyStroke</code>.
218      * The string must have the following syntax:
219      * <pre>
220      * &lt;modifiers&gt;* (&lt;typedID&gt; | &lt;pressedReleasedID&gt;)
221      *
222      * modifiers := shift | control | ctrl | meta | alt | altGraph
223      * typedID := typed &lt;typedKey&gt;
224      * typedKey := string of length 1 giving Unicode character.
225      * pressedReleasedID := (pressed | released) key
226      * key := KeyEvent key code name, i.e. the name following "VK_".
227      * </pre>
228      * If typed, pressed or released is not specified, pressed is assumed. Here
229      * are some examples:
230      * <pre>
231      * "INSERT" => getKeyStroke(KeyEvent.VK_INSERT, 0);
232      * "control DELETE" => getKeyStroke(KeyEvent.VK_DELETE, InputEvent.CTRL_MASK);
233      * "alt shift X" => getKeyStroke(KeyEvent.VK_X, InputEvent.ALT_MASK | InputEvent.SHIFT_MASK);
234      * "alt shift released X" => getKeyStroke(KeyEvent.VK_X, InputEvent.ALT_MASK | InputEvent.SHIFT_MASK, true);
235      * "typed a" => getKeyStroke('a');
236      * </pre>
237      *
238      * In order to maintain backward-compatibility, specifying a null String,
239      * or a String which is formatted incorrectly, returns null.
240      *
241      * @param s a String formatted as described above
242      * @return a KeyStroke object for that String, or null if the specified
243      * String is null, or is formatted incorrectly
244      */

245     public static KeyStroke JavaDoc getKeyStroke(String JavaDoc s) {
246     if (s == null || s.length() == 0) {
247         return null;
248     }
249         synchronized (AWTKeyStroke JavaDoc.class) {
250         registerSubclass(KeyStroke JavaDoc.class);
251         try {
252             return (KeyStroke JavaDoc)getAWTKeyStroke(s);
253         } catch (IllegalArgumentException JavaDoc e) {
254             return null;
255         }
256     }
257     }
258 }
259
Popular Tags