KeySequence


1   /*******************************************************************************
2    * Copyright (c) 2004, 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.jface.bindings.keys;
13  
14  import java.util.ArrayList  ;
15  import java.util.List  ;
16  import java.util.StringTokenizer  ;
17  
18  import org.eclipse.jface.bindings.TriggerSequence;
19  import org.eclipse.jface.bindings.keys.formatting.KeyFormatterFactory;
20  import org.eclipse.jface.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   * @since 3.1
47   */
48  public final class KeySequence extends TriggerSequence implements Comparable   {
49  
50      /**
51       * An empty key sequence instance for use by everyone.
52       */
53      private final static KeySequence EMPTY_KEY_SEQUENCE = new KeySequence(
54              new KeyStroke[0]);
55  
56      /**
57       * The delimiter between multiple key strokes in a single key sequence --
58       * expressed in the formal key stroke grammar. This is not to be displayed
59       * to the user. It is only intended as an internal representation.
60       */
61      public final static String   KEY_STROKE_DELIMITER = "\u0020"; //$NON-NLS-1$
62  
63      /**
64       * The set of delimiters for <code>KeyStroke</code> objects allowed during
65       * parsing of the formal string representation.
66       */
67      public final static String   KEY_STROKE_DELIMITERS = KEY_STROKE_DELIMITER
68              + "\b\r\u007F\u001B\f\n\0\t\u000B"; //$NON-NLS-1$
69  
70      /**
71       * Gets an instance of <code>KeySequence</code>.
72       * 
73       * @return a key sequence. This key sequence will have no key strokes.
74       *         Guaranteed not to be <code>null</code>.
75       */
76      public static final KeySequence getInstance() {
77          return EMPTY_KEY_SEQUENCE;
78      }
79  
80      /**
81       * Creates an instance of <code>KeySequence</code> given a key sequence
82       * and a key stroke.
83       * 
84       * @param keySequence
85       *            a key sequence. Must not be <code>null</code>.
86       * @param keyStroke
87       *            a key stroke. Must not be <code>null</code>.
88       * @return a key sequence that is equal to the given key sequence with the
89       *         given key stroke appended to the end. Guaranteed not to be
90       *         <code>null</code>.
91       */
92      public static final KeySequence getInstance(final KeySequence keySequence,
93              final KeyStroke keyStroke) {
94          if (keySequence == null || keyStroke == null) {
95              throw new NullPointerException  ();
96          }
97  
98          final KeyStroke[] oldKeyStrokes = keySequence.getKeyStrokes();
99          final int oldKeyStrokeLength = oldKeyStrokes.length;
100         final KeyStroke[] newKeyStrokes = new KeyStroke[oldKeyStrokeLength + 1];
101         System
102                 .arraycopy(oldKeyStrokes, 0, newKeyStrokes, 0,
103                         oldKeyStrokeLength);
104         newKeyStrokes[oldKeyStrokeLength] = keyStroke;
105         return new KeySequence(newKeyStrokes);
106     }
107 
108     /**
109      * Creates an instance of <code>KeySequence</code> given a single key
110      * stroke.
111      * 
112      * @param keyStroke
113      *            a single key stroke. Must not be <code>null</code>.
114      * @return a key sequence. Guaranteed not to be <code>null</code>.
115      */
116     public static final KeySequence getInstance(final KeyStroke keyStroke) {
117         return new KeySequence(new KeyStroke[] { keyStroke });
118     }
119 
120     /**
121      * Creates an instance of <code>KeySequence</code> given an array of key
122      * strokes.
123      * 
124      * @param keyStrokes
125      *            the array of key strokes. This array may be empty, but it must
126      *            not be <code>null</code>. This array must not contain
127      *            <code>null</code> elements.
128      * @return a key sequence. Guaranteed not to be <code>null</code>.
129      */
130     public static final KeySequence getInstance(final KeyStroke[] keyStrokes) {
131         return new KeySequence(keyStrokes);
132     }
133 
134     /**
135      * Creates an instance of <code>KeySequence</code> given a list of key
136      * strokes.
137      * 
138      * @param keyStrokes
139      *            the list of key strokes. This list may be empty, but it must
140      *            not be <code>null</code>. If this list is not empty, it
141      *            must only contain instances of <code>KeyStroke</code>.
142      * @return a key sequence. Guaranteed not to be <code>null</code>.
143      */
144     public static final KeySequence getInstance(final List   keyStrokes) {
145         return new KeySequence((KeyStroke[]) keyStrokes
146                 .toArray(new KeyStroke[keyStrokes.size()]));
147     }
148 
149     /**
150      * Creates an instance of <code>KeySequence</code> by parsing a given
151      * formal string representation.
152      * 
153      * @param string
154      *            the formal string representation to parse.
155      * @return a key sequence. Guaranteed not to be <code>null</code>.
156      * @throws ParseException
157      *             if the given formal string representation could not be parsed
158      *             to a valid key sequence.
159      */
160     public static final KeySequence getInstance(final String   string)
161             throws ParseException {
162         if (string == null) {
163             throw new NullPointerException  ();
164         }
165 
166         final List   keyStrokes = new ArrayList  ();
167         final StringTokenizer   stringTokenizer = new StringTokenizer  (string,
168                 KEY_STROKE_DELIMITERS);
169 
170         try {
171             while (stringTokenizer.hasMoreTokens()) {
172                 keyStrokes.add(KeyStroke.getInstance(stringTokenizer
173                         .nextToken()));
174             }
175 
176             final KeyStroke[] keyStrokeArray = (KeyStroke[]) keyStrokes
177                     .toArray(new KeyStroke[keyStrokes.size()]);
178             return new KeySequence(keyStrokeArray);
179         } catch (final IllegalArgumentException   e) {
180             throw new ParseException(
181                     "Could not construct key sequence with these key strokes: " //$NON-NLS-1$
182                             + keyStrokes);
183         } catch (final NullPointerException   e) {
184             throw new ParseException(
185                     "Could not construct key sequence with these key strokes: " //$NON-NLS-1$
186                             + keyStrokes);
187         }
188     }
189 
190     /**
191      * Constructs an instance of <code>KeySequence</code> given a list of key
192      * strokes.
193      * 
194      * @param keyStrokes
195      *            the list of key strokes. This list may be empty, but it must
196      *            not be <code>null</code>. If this list is not empty, it
197      *            must only contain instances of <code>KeyStroke</code>.
198      */
199     protected KeySequence(final KeyStroke[] keyStrokes) {
200         super(keyStrokes);
201 
202         for (int i = 0; i < triggers.length - 1; i++) {
203             KeyStroke keyStroke = (KeyStroke) triggers[i];
204 
205             if (!keyStroke.isComplete()) {
206                 throw new IllegalArgumentException  ();
207             }
208         }
209     }
210 
211     /*
212      * (non-Javadoc)
213      * 
214      * @see java.lang.Object#compareTo(java.lang.Object)
215      */
216     public final int compareTo(final Object   object) {
217         final KeySequence castedObject = (KeySequence) object;
218         return Util.compare(triggers, castedObject.triggers);
219     }
220 
221     /**
222      * Formats this key sequence into the current default look.
223      * 
224      * @return A string representation for this key sequence using the default
225      *         look; never <code>null</code>.
226      */
227     public final String   format() {
228         return KeyFormatterFactory.getDefault().format(this);
229     }
230 
231     /**
232      * Returns the list of key strokes for this key sequence.
233      * 
234      * @return the list of key strokes keys. This list may be empty, but is
235      *         guaranteed not to be <code>null</code>. If this list is not
236      *         empty, it is guaranteed to only contain instances of
237      *         <code>KeyStroke</code>.
238      */
239     public final KeyStroke[] getKeyStrokes() {
240         final int triggerLength = triggers.length;
241         final KeyStroke[] keyStrokes = new KeyStroke[triggerLength];
242         System.arraycopy(triggers, 0, keyStrokes, 0, triggerLength);
243         return keyStrokes;
244     }
245 
246     /*
247      * (non-Javadoc)
248      * 
249      * @see org.eclipse.jface.bindings.TriggerSequence#getPrefixes()
250      */
251     public final TriggerSequence[] getPrefixes() {
252         final int numberOfPrefixes = triggers.length;
253         final TriggerSequence[] prefixes = new TriggerSequence[numberOfPrefixes];
254         prefixes[0] = KeySequence.getInstance();
255         for (int i = 0; i < numberOfPrefixes - 1; i++) {
256             final KeyStroke[] prefixKeyStrokes = new KeyStroke[i + 1];
257             System.arraycopy(triggers, 0, prefixKeyStrokes, 0, i + 1);
258             prefixes[i + 1] = KeySequence.getInstance(prefixKeyStrokes);
259         }
260 
261         return prefixes;
262     }
263 
264     /**
265      * Returns whether or not this key sequence is complete. Key sequences are
266      * complete iff all of their key strokes are complete.
267      * 
268      * @return <code>true</code>, iff the key sequence is complete.
269      */
270     public final boolean isComplete() {
271         final int triggersLength = triggers.length;
272         for (int i = 0; i < triggersLength; i++) {
273             if (!((KeyStroke) triggers[i]).isComplete()) {
274                 return false;
275             }
276         }
277 
278         return true;
279     }
280 
281     /**
282      * Returns the formal string representation for this key sequence.
283      * 
284      * @return The formal string representation for this key sequence.
285      *         Guaranteed not to be <code>null</code>.
286      * @see java.lang.Object#toString()
287      */
288     public final String   toString() {
289         return KeyFormatterFactory.getFormalKeyFormatter().format(this);
290     }
291 }
292
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags