KeySequence


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.ui.keys;
13  
14  import java.util.ArrayList  ;
15  import java.util.Arrays  ;
16  import java.util.Collections  ;
17  import java.util.List  ;
18  import java.util.StringTokenizer  ;
19  
20  import org.eclipse.ui.internal.util.Util;
21  
22  /**
23   * <p>
24   * A <code>KeySequence</code> is defined as a list of zero or more
25   * <code>KeyStrokes</code>, with the stipulation that all
26   * <code>KeyStroke</code> objects must be complete, save for the last one,
27   * whose completeness is optional. A <code>KeySequence</code> is said to be
28   * complete if all of its <code>KeyStroke</code> objects are complete.
29   * </p>
30   * <p>
31   * All <code>KeySequence</code> objects have a formal string representation
32   * available via the <code>toString()</code> method. There are a number of
33   * methods to get instances of <code>KeySequence</code> objects, including one
34   * which can parse this formal string representation.
35   * </p>
36   * <p>
37   * All <code>KeySequence</code> objects, via the <code>format()</code>
38   * method, provide a version of their formal string representation translated by
39   * platform and locale, suitable for display to a user.
40   * </p>
41   * <p>
42   * <code>KeySequence</code> objects are immutable. Clients are not permitted
43   * to extend this class.
44   * </p>
45   * 
46   * @deprecated Please use org.eclipse.jface.bindings.keys.KeySequence
47   * @since 3.0
48   */
49  public final class KeySequence implements Comparable   {
50  
51      /**
52       * The delimiter between multiple key strokes in a single key sequence --
53       * expressed in the formal key stroke grammar. This is not to be displayed
54       * to the user. It is only intended as an internal representation.
55       */
56      public final static String   KEY_STROKE_DELIMITER = "\u0020"; //$NON-NLS-1$
57  
58      /**
59       * An empty key sequence instance for use by everyone.
60       */
61      private final static KeySequence EMPTY_KEY_SEQUENCE = new KeySequence(
62              Collections.EMPTY_LIST);
63  
64      /**
65       * An internal constant used only in this object's hash code algorithm.
66       */
67      private final static int HASH_FACTOR = 89;
68  
69      /**
70       * An internal constant used only in this object's hash code algorithm.
71       */
72      private final static int HASH_INITIAL = KeySequence.class.getName()
73              .hashCode();
74  
75      /**
76       * The set of delimiters for <code>KeyStroke</code> objects allowed
77       * during parsing of the formal string representation.
78       */
79      public final static String   KEY_STROKE_DELIMITERS = KEY_STROKE_DELIMITER
80              + "\b\r\u007F\u001B\f\n\0\t\u000B"; //$NON-NLS-1$
81  
82      /**
83       * Gets an instance of <code>KeySequence</code>.
84       * 
85       * @return a key sequence. This key sequence will have no key strokes.
86       *         Guaranteed not to be <code>null</code>.
87       */
88      public static KeySequence getInstance() {
89          return EMPTY_KEY_SEQUENCE;
90      }
91  
92      /**
93       * Gets an instance of <code>KeySequence</code> given a key sequence and
94       * a key stroke.
95       * 
96       * @param keySequence
97       *            a key sequence. Must not be <code>null</code>.
98       * @param keyStroke
99       *            a key stroke. Must not be <code>null</code>.
100      * @return a key sequence that is equal to the given key sequence with the
101      *         given key stroke appended to the end. Guaranteed not to be
102      *         <code>null</code>.
103      */
104     public static KeySequence getInstance(KeySequence keySequence,
105             KeyStroke keyStroke) {
106         if (keySequence == null || keyStroke == null) {
107             throw new NullPointerException  ();
108         }
109 
110         List   keyStrokes = new ArrayList  (keySequence.getKeyStrokes());
111         keyStrokes.add(keyStroke);
112         return new KeySequence(keyStrokes);
113     }
114 
115     /**
116      * Gets an instance of <code>KeySequence</code> given a single key
117      * stroke.
118      * 
119      * @param keyStroke
120      *            a single key stroke. Must not be <code>null</code>.
121      * @return a key sequence. Guaranteed not to be <code>null</code>.
122      */
123     public static KeySequence getInstance(KeyStroke keyStroke) {
124         return new KeySequence(Collections.singletonList(keyStroke));
125     }
126 
127     /**
128      * Gets an instance of <code>KeySequence</code> given an array of key
129      * strokes.
130      * 
131      * @param keyStrokes
132      *            the array of key strokes. This array may be empty, but it
133      *            must not be <code>null</code>. This array must not contain
134      *            <code>null</code> elements.
135      * @return a key sequence. Guaranteed not to be <code>null</code>.
136      */
137     public static KeySequence getInstance(KeyStroke[] keyStrokes) {
138         return new KeySequence(Arrays.asList(keyStrokes));
139     }
140 
141     /**
142      * Gets an instance of <code>KeySequence</code> given a list of key
143      * strokes.
144      * 
145      * @param keyStrokes
146      *            the list of key strokes. This list may be empty, but it must
147      *            not be <code>null</code>. If this list is not empty, it
148      *            must only contain instances of <code>KeyStroke</code>.
149      * @return a key sequence. Guaranteed not to be <code>null</code>.
150      */
151     public static KeySequence getInstance(List   keyStrokes) {
152         return new KeySequence(keyStrokes);
153     }
154     
155     /**
156      * Gets an instance of <code>KeySequence</code> given a new-style key
157      * sequence.
158      * 
159      * @param newKeySequence
160      *            The new-style key sequence to convert into a legacy key
161      *            sequence; must not be <code>null</code>.
162      * @return a key sequence; never <code>null</code>.
163      */
164     public static final KeySequence getInstance(
165             final org.eclipse.jface.bindings.keys.KeySequence newKeySequence) {
166         final org.eclipse.jface.bindings.keys.KeyStroke[] newKeyStrokes = newKeySequence
167                 .getKeyStrokes();
168         final int newKeyStrokesCount = newKeyStrokes.length;
169         final List   legacyKeyStrokes = new ArrayList  (newKeyStrokesCount);
170 
171         for (int i = 0; i < newKeyStrokesCount; i++) {
172             final org.eclipse.jface.bindings.keys.KeyStroke newKeyStroke = newKeyStrokes[i];
173             legacyKeyStrokes.add(SWTKeySupport
174                     .convertAcceleratorToKeyStroke(newKeyStroke
175                             .getModifierKeys()
176                             | newKeyStroke.getNaturalKey()));
177         }
178         
179         return new KeySequence(legacyKeyStrokes);
180     }
181 
182     /**
183      * Gets an instance of <code>KeySequence</code> by parsing a given a
184      * formal string representation.
185      * 
186      * @param string
187      *            the formal string representation to parse.
188      * @return a key sequence. Guaranteed not to be <code>null</code>.
189      * @throws ParseException
190      *             if the given formal string representation could not be
191      *             parsed to a valid key sequence.
192      */
193     public static KeySequence getInstance(String   string) throws ParseException {
194         if (string == null) {
195             throw new NullPointerException  ();
196         }
197 
198         List   keyStrokes = new ArrayList  ();
199         StringTokenizer   stringTokenizer = new StringTokenizer  (string,
200                 KEY_STROKE_DELIMITERS);
201 
202         while (stringTokenizer.hasMoreTokens()) {
203             keyStrokes.add(KeyStroke.getInstance(stringTokenizer.nextToken()));
204         }
205 
206         try {
207             return new KeySequence(keyStrokes);
208         } catch (Throwable   t) {
209             throw new ParseException(
210                     "Could not construct key sequence with these key strokes: " //$NON-NLS-1$
211                             + keyStrokes);
212         }
213     }
214 
215     /**
216      * The cached hash code for this object. Because <code>KeySequence</code>
217      * objects are immutable, their hash codes need only to be computed once.
218      * After the first call to <code>hashCode()</code>, the computed value
219      * is cached here for all subsequent calls.
220      */
221     private transient int hashCode;
222 
223     /**
224      * A flag to determine if the <code>hashCode</code> field has already
225      * been computed.
226      */
227     private transient boolean hashCodeComputed;
228 
229     /**
230      * The list of key strokes for this key sequence.
231      */
232     private List   keyStrokes;
233 
234     /**
235      * Constructs an instance of <code>KeySequence</code> given a list of key
236      * strokes.
237      * 
238      * @param keyStrokes
239      *            the list of key strokes. This list may be empty, but it must
240      *            not be <code>null</code>. If this list is not empty, it
241      *            must only contain instances of <code>KeyStroke</code>.
242      */
243     private KeySequence(List   keyStrokes) {
244         this.keyStrokes = Util.safeCopy(keyStrokes, KeyStroke.class);
245 
246         for (int i = 0; i < this.keyStrokes.size() - 1; i++) {
247             KeyStroke keyStroke = (KeyStroke) this.keyStrokes.get(i);
248 
249             if (!keyStroke.isComplete()) {
250                 throw new IllegalArgumentException  ();
251             }
252         }
253     }
254 
255     /**
256      * @see java.lang.Object#equals(java.lang.Object)
257      */
258     public int compareTo(Object   object) {
259         KeySequence castedObject = (KeySequence) object;
260         int compareTo = Util.compare(keyStrokes, castedObject.keyStrokes);
261         return compareTo;
262     }
263 
264     /**
265      * Returns whether or not this key sequence ends with the given key
266      * sequence.
267      * 
268      * @param keySequence
269      *            a key sequence. Must not be <code>null</code>.
270      * @param equals
271      *            whether or not an identical key sequence should be considered
272      *            as a possible match.
273      * @return <code>true</code>, iff the given key sequence ends with this
274      *         key sequence.
275      */
276     public boolean endsWith(KeySequence keySequence, boolean equals) {
277         if (keySequence == null) {
278             throw new NullPointerException  ();
279         }
280 
281         return Util.endsWith(keyStrokes, keySequence.keyStrokes, equals);
282     }
283 
284     /**
285      * @see java.lang.Object#equals(java.lang.Object)
286      */
287     public boolean equals(Object   object) {
288         if (!(object instanceof KeySequence)) {
289             return false;
290         }
291 
292         return keyStrokes.equals(((KeySequence) object).keyStrokes);
293     }
294 
295     /**
296      * Formats this key sequence into the current default look.
297      * 
298      * @return A string representation for this key sequence using the default
299      *         look; never <code>null</code>.
300      */
301     public String   format() {
302         return KeyFormatterFactory.getDefault().format(this);
303     }
304 
305     /**
306      * Returns the list of key strokes for this key sequence.
307      * 
308      * @return the list of key strokes keys. This list may be empty, but is
309      *         guaranteed not to be <code>null</code>. If this list is not
310      *         empty, it is guaranteed to only contain instances of <code>KeyStroke</code>.
311      */
312     public List   getKeyStrokes() {
313         return keyStrokes;
314     }
315 
316     /**
317      * @see java.lang.Object#hashCode()
318      */
319     public int hashCode() {
320         if (!hashCodeComputed) {
321             hashCode = HASH_INITIAL;
322             hashCode = hashCode * HASH_FACTOR + keyStrokes.hashCode();
323             hashCodeComputed = true;
324         }
325 
326         return hashCode;
327     }
328 
329     /**
330      * Returns whether or not this key sequence is complete. Key sequences are
331      * complete iff all of their key strokes are complete.
332      * 
333      * @return <code>true</code>, iff the key sequence is complete.
334      */
335     public boolean isComplete() {
336         return keyStrokes.isEmpty()
337                 || ((KeyStroke) keyStrokes.get(keyStrokes.size() - 1))
338                         .isComplete();
339     }
340 
341     /**
342      * Returns whether or not this key sequence is empty. Key sequences are
343      * complete iff they have no key strokes.
344      * 
345      * @return <code>true</code>, iff the key sequence is empty.
346      */
347     public boolean isEmpty() {
348         return keyStrokes.isEmpty();
349     }
350 
351     /**
352      * Returns whether or not this key sequence starts with the given key
353      * sequence.
354      * 
355      * @param keySequence
356      *            a key sequence. Must not be <code>null</code>.
357      * @param equals
358      *            whether or not an identical key sequence should be considered
359      *            as a possible match.
360      * @return <code>true</code>, iff the given key sequence starts with
361      *         this key sequence.
362      */
363     public boolean startsWith(KeySequence keySequence, boolean equals) {
364         if (keySequence == null) {
365             throw new NullPointerException  ();
366         }
367 
368         return Util.startsWith(keyStrokes, keySequence.keyStrokes, equals);
369     }
370 
371     /**
372      * Returns the formal string representation for this key sequence.
373      * 
374      * @return The formal string representation for this key sequence.
375      *         Guaranteed not to be <code>null</code>.
376      * @see java.lang.Object#toString()
377      */
378     public String   toString() {
379         return KeyFormatterFactory.getFormalKeyFormatter().format(this);
380     }
381 }
382
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags