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  ;
10  import java.awt.event.KeyEvent  ;
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   {
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   getKeyStroke(char keyChar) {
70          synchronized (AWTKeyStroke  .class) {
71          registerSubclass(KeyStroke  .class);
72          return (KeyStroke  )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  
89      public static KeyStroke   getKeyStroke(char keyChar, boolean onKeyRelease) {
90          return new KeyStroke  (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   getKeyStroke(Character   keyChar, int modifiers) {
118         synchronized (AWTKeyStroke  .class) {
119         registerSubclass(KeyStroke  .class);
120         return (KeyStroke  )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   getKeyStroke(int keyCode, int modifiers,
155                      boolean onKeyRelease) {
156         synchronized (AWTKeyStroke  .class) {
157         registerSubclass(KeyStroke  .class);
158         return (KeyStroke  )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   getKeyStroke(int keyCode, int modifiers) {
191         synchronized (AWTKeyStroke  .class) {
192         registerSubclass(KeyStroke  .class);
193         return (KeyStroke  )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   getKeyStrokeForEvent(KeyEvent   anEvent) {
210         synchronized (AWTKeyStroke  .class) {
211         registerSubclass(KeyStroke  .class);
212         return (KeyStroke  )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   getKeyStroke(String   s) {
246     if (s == null || s.length() == 0) {
247         return null;
248     }
249         synchronized (AWTKeyStroke  .class) {
250         registerSubclass(KeyStroke  .class);
251         try {
252             return (KeyStroke  )getAWTKeyStroke(s);
253         } catch (IllegalArgumentException   e) {
254             return null;
255         }
256     }
257     }
258 }
259
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags