001 /*
002 * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package javax.swing;
026
027 import java.awt.AWTKeyStroke;
028 import java.awt.event.KeyEvent;
029
030 /**
031 * A KeyStroke represents a key action on the keyboard, or equivalent input
032 * device. KeyStrokes can correspond to only a press or release of a particular
033 * key, just as KEY_PRESSED and KEY_RELEASED KeyEvents do; alternately, they
034 * can correspond to typing a specific Java character, just as KEY_TYPED
035 * KeyEvents do. In all cases, KeyStrokes can specify modifiers (alt, shift,
036 * control, meta, altGraph, or a combination thereof) which must be present during the
037 * action for an exact match.
038 * <p>
039 * KeyStrokes are used to define high-level (semantic) action events. Instead
040 * of trapping every keystroke and throwing away the ones you are not
041 * interested in, those keystrokes you care about automatically initiate
042 * actions on the Components with which they are registered.
043 * <p>
044 * KeyStrokes are immutable, and are intended to be unique. Client code cannot
045 * create a KeyStroke; a variant of <code>getKeyStroke</code> must be used
046 * instead. These factory methods allow the KeyStroke implementation to cache
047 * and share instances efficiently.
048 * <p>
049 * <strong>Warning:</strong>
050 * Serialized objects of this class will not be compatible with
051 * future Swing releases. The current serialization support is
052 * appropriate for short term storage or RMI between applications running
053 * the same version of Swing. As of 1.4, support for long term storage
054 * of all JavaBeans<sup><font size="-2">TM</font></sup>
055 * has been added to the <code>java.beans</code> package.
056 * Please see {@link java.beans.XMLEncoder}.
057 *
058 * @see javax.swing.text.Keymap
059 * @see #getKeyStroke
060 *
061 * @version 1.57, 05/05/07
062 * @author Arnaud Weber
063 * @author David Mendenhall
064 */
065 public class KeyStroke extends AWTKeyStroke {
066
067 /**
068 * Serial Version ID.
069 */
070 private static final long serialVersionUID = -9060180771037902530L;
071
072 private KeyStroke() {
073 }
074
075 private KeyStroke(char keyChar, int keyCode, int modifiers,
076 boolean onKeyRelease) {
077 super (keyChar, keyCode, modifiers, onKeyRelease);
078 }
079
080 /**
081 * Returns a shared instance of a <code>KeyStroke</code>
082 * that represents a <code>KEY_TYPED</code> event for the
083 * specified character.
084 *
085 * @param keyChar the character value for a keyboard key
086 * @return a KeyStroke object for that key
087 */
088 public static KeyStroke getKeyStroke(char keyChar) {
089 synchronized (AWTKeyStroke.class) {
090 registerSubclass(KeyStroke.class);
091 return (KeyStroke) getAWTKeyStroke(keyChar);
092 }
093 }
094
095 /**
096 * Returns an instance of a KeyStroke, specifying whether the key is
097 * considered to be activated when it is pressed or released. Unlike all
098 * other factory methods in this class, the instances returned by this
099 * method are not necessarily cached or shared.
100 *
101 * @param keyChar the character value for a keyboard key
102 * @param onKeyRelease <code>true</code> if this KeyStroke corresponds to a
103 * key release; <code>false</code> otherwise.
104 * @return a KeyStroke object for that key
105 * @deprecated use getKeyStroke(char)
106 */
107 @Deprecated
108 public static KeyStroke getKeyStroke(char keyChar,
109 boolean onKeyRelease) {
110 return new KeyStroke(keyChar, KeyEvent.VK_UNDEFINED, 0,
111 onKeyRelease);
112 }
113
114 /**
115 * Returns a shared instance of a {@code KeyStroke}
116 * that represents a {@code KEY_TYPED} event for the
117 * specified Character object and a
118 * set of modifiers. Note that the first parameter is of type Character
119 * rather than char. This is to avoid inadvertent clashes with calls to
120 * <code>getKeyStroke(int keyCode, int modifiers)</code>.
121 *
122 * The modifiers consist of any combination of following:<ul>
123 * <li>java.awt.event.InputEvent.SHIFT_DOWN_MASK
124 * <li>java.awt.event.InputEvent.CTRL_DOWN_MASK
125 * <li>java.awt.event.InputEvent.META_DOWN_MASK
126 * <li>java.awt.event.InputEvent.ALT_DOWN_MASK
127 * <li>java.awt.event.InputEvent.ALT_GRAPH_DOWN_MASK
128 * </ul>
129 * The old modifiers listed below also can be used, but they are
130 * mapped to _DOWN_ modifiers. <ul>
131 * <li>java.awt.event.InputEvent.SHIFT_MASK
132 * <li>java.awt.event.InputEvent.CTRL_MASK
133 * <li>java.awt.event.InputEvent.META_MASK
134 * <li>java.awt.event.InputEvent.ALT_MASK
135 * <li>java.awt.event.InputEvent.ALT_GRAPH_MASK
136 * </ul>
137 * also can be used, but they are mapped to _DOWN_ modifiers.
138 *
139 * Since these numbers are all different powers of two, any combination of
140 * them is an integer in which each bit represents a different modifier
141 * key. Use 0 to specify no modifiers.
142 *
143 * @param keyChar the Character object for a keyboard character
144 * @param modifiers a bitwise-ored combination of any modifiers
145 * @return an KeyStroke object for that key
146 * @throws IllegalArgumentException if keyChar is null
147 *
148 * @see java.awt.event.InputEvent
149 * @since 1.3
150 */
151 public static KeyStroke getKeyStroke(Character keyChar,
152 int modifiers) {
153 synchronized (AWTKeyStroke.class) {
154 registerSubclass(KeyStroke.class);
155 return (KeyStroke) getAWTKeyStroke(keyChar, modifiers);
156 }
157 }
158
159 /**
160 * Returns a shared instance of a KeyStroke, given a numeric key code and a
161 * set of modifiers, specifying whether the key is activated when it is
162 * pressed or released.
163 * <p>
164 * The "virtual key" constants defined in java.awt.event.KeyEvent can be
165 * used to specify the key code. For example:<ul>
166 * <li>java.awt.event.KeyEvent.VK_ENTER
167 * <li>java.awt.event.KeyEvent.VK_TAB
168 * <li>java.awt.event.KeyEvent.VK_SPACE
169 * </ul>
170 * The modifiers consist of any combination of:<ul>
171 * <li>java.awt.event.InputEvent.SHIFT_DOWN_MASK
172 * <li>java.awt.event.InputEvent.CTRL_DOWN_MASK
173 * <li>java.awt.event.InputEvent.META_DOWN_MASK
174 * <li>java.awt.event.InputEvent.ALT_DOWN_MASK
175 * <li>java.awt.event.InputEvent.ALT_GRAPH_DOWN_MASK
176 * </ul>
177 * The old modifiers <ul>
178 * <li>java.awt.event.InputEvent.SHIFT_MASK
179 * <li>java.awt.event.InputEvent.CTRL_MASK
180 * <li>java.awt.event.InputEvent.META_MASK
181 * <li>java.awt.event.InputEvent.ALT_MASK
182 * <li>java.awt.event.InputEvent.ALT_GRAPH_MASK
183 * </ul>
184 * also can be used, but they are mapped to _DOWN_ modifiers.
185 *
186 * Since these numbers are all different powers of two, any combination of
187 * them is an integer in which each bit represents a different modifier
188 * key. Use 0 to specify no modifiers.
189 *
190 * @param keyCode an int specifying the numeric code for a keyboard key
191 * @param modifiers a bitwise-ored combination of any modifiers
192 * @param onKeyRelease <code>true</code> if the KeyStroke should represent
193 * a key release; <code>false</code> otherwise.
194 * @return a KeyStroke object for that key
195 *
196 * @see java.awt.event.KeyEvent
197 * @see java.awt.event.InputEvent
198 */
199 public static KeyStroke getKeyStroke(int keyCode, int modifiers,
200 boolean onKeyRelease) {
201 synchronized (AWTKeyStroke.class) {
202 registerSubclass(KeyStroke.class);
203 return (KeyStroke) getAWTKeyStroke(keyCode, modifiers,
204 onKeyRelease);
205 }
206 }
207
208 /**
209 * Returns a shared instance of a KeyStroke, given a numeric key code and a
210 * set of modifiers. The returned KeyStroke will correspond to a key press.
211 * <p>
212 * The "virtual key" constants defined in java.awt.event.KeyEvent can be
213 * used to specify the key code. For example:<ul>
214 * <li>java.awt.event.KeyEvent.VK_ENTER
215 * <li>java.awt.event.KeyEvent.VK_TAB
216 * <li>java.awt.event.KeyEvent.VK_SPACE
217 * </ul>
218 * The modifiers consist of any combination of:<ul>
219 * <li>java.awt.event.InputEvent.SHIFT_DOWN_MASK
220 * <li>java.awt.event.InputEvent.CTRL_DOWN_MASK
221 * <li>java.awt.event.InputEvent.META_DOWN_MASK
222 * <li>java.awt.event.InputEvent.ALT_DOWN_MASK
223 * <li>java.awt.event.InputEvent.ALT_GRAPH_DOWN_MASK
224 * </ul>
225 * The old modifiers <ul>
226 * <li>java.awt.event.InputEvent.SHIFT_MASK
227 * <li>java.awt.event.InputEvent.CTRL_MASK
228 * <li>java.awt.event.InputEvent.META_MASK
229 * <li>java.awt.event.InputEvent.ALT_MASK
230 * <li>java.awt.event.InputEvent.ALT_GRAPH_MASK
231 * </ul>
232 * also can be used, but they are mapped to _DOWN_ modifiers.
233 *
234 * Since these numbers are all different powers of two, any combination of
235 * them is an integer in which each bit represents a different modifier
236 * key. Use 0 to specify no modifiers.
237 *
238 * @param keyCode an int specifying the numeric code for a keyboard key
239 * @param modifiers a bitwise-ored combination of any modifiers
240 * @return a KeyStroke object for that key
241 *
242 * @see java.awt.event.KeyEvent
243 * @see java.awt.event.InputEvent
244 */
245 public static KeyStroke getKeyStroke(int keyCode, int modifiers) {
246 synchronized (AWTKeyStroke.class) {
247 registerSubclass(KeyStroke.class);
248 return (KeyStroke) getAWTKeyStroke(keyCode, modifiers);
249 }
250 }
251
252 /**
253 * Returns a KeyStroke which represents the stroke which generated a given
254 * KeyEvent.
255 * <p>
256 * This method obtains the keyChar from a KeyTyped event, and the keyCode
257 * from a KeyPressed or KeyReleased event. The KeyEvent modifiers are
258 * obtained for all three types of KeyEvent.
259 *
260 * @param anEvent the KeyEvent from which to obtain the KeyStroke
261 * @throws NullPointerException if <code>anEvent</code> is null
262 * @return the KeyStroke that precipitated the event
263 */
264 public static KeyStroke getKeyStrokeForEvent(KeyEvent anEvent) {
265 synchronized (AWTKeyStroke.class) {
266 registerSubclass(KeyStroke.class);
267 return (KeyStroke) getAWTKeyStrokeForEvent(anEvent);
268 }
269 }
270
271 /**
272 * Parses a string and returns a <code>KeyStroke</code>.
273 * The string must have the following syntax:
274 * <pre>
275 * <modifiers>* (<typedID> | <pressedReleasedID>)
276 *
277 * modifiers := shift | control | ctrl | meta | alt | altGraph
278 * typedID := typed <typedKey>
279 * typedKey := string of length 1 giving Unicode character.
280 * pressedReleasedID := (pressed | released) key
281 * key := KeyEvent key code name, i.e. the name following "VK_".
282 * </pre>
283 * If typed, pressed or released is not specified, pressed is assumed. Here
284 * are some examples:
285 * <pre>
286 * "INSERT" => getKeyStroke(KeyEvent.VK_INSERT, 0);
287 * "control DELETE" => getKeyStroke(KeyEvent.VK_DELETE, InputEvent.CTRL_MASK);
288 * "alt shift X" => getKeyStroke(KeyEvent.VK_X, InputEvent.ALT_MASK | InputEvent.SHIFT_MASK);
289 * "alt shift released X" => getKeyStroke(KeyEvent.VK_X, InputEvent.ALT_MASK | InputEvent.SHIFT_MASK, true);
290 * "typed a" => getKeyStroke('a');
291 * </pre>
292 *
293 * In order to maintain backward-compatibility, specifying a null String,
294 * or a String which is formatted incorrectly, returns null.
295 *
296 * @param s a String formatted as described above
297 * @return a KeyStroke object for that String, or null if the specified
298 * String is null, or is formatted incorrectly
299 *
300 * @see java.awt.event.KeyEvent
301 */
302 public static KeyStroke getKeyStroke(String s) {
303 if (s == null || s.length() == 0) {
304 return null;
305 }
306 synchronized (AWTKeyStroke.class) {
307 registerSubclass(KeyStroke.class);
308 try {
309 return (KeyStroke) getAWTKeyStroke(s);
310 } catch (IllegalArgumentException e) {
311 return null;
312 }
313 }
314 }
315 }
|