| /******************************************************************************* |
| * Copyright (c) 2000, 2006 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| |
| package org.eclipse.ui.keys; |
| |
| import java.util.ArrayList; |
| import java.util.Arrays; |
| import java.util.Collections; |
| import java.util.List; |
| import java.util.StringTokenizer; |
| |
| import org.eclipse.ui.internal.util.Util; |
| |
| /** |
| * <p> |
| * A <code>KeySequence</code> is defined as a list of zero or more |
| * <code>KeyStrokes</code>, with the stipulation that all |
| * <code>KeyStroke</code> objects must be complete, save for the last one, |
| * whose completeness is optional. A <code>KeySequence</code> is said to be |
| * complete if all of its <code>KeyStroke</code> objects are complete. |
| * </p> |
| * <p> |
| * All <code>KeySequence</code> objects have a formal string representation |
| * available via the <code>toString()</code> method. There are a number of |
| * methods to get instances of <code>KeySequence</code> objects, including one |
| * which can parse this formal string representation. |
| * </p> |
| * <p> |
| * All <code>KeySequence</code> objects, via the <code>format()</code> |
| * method, provide a version of their formal string representation translated by |
| * platform and locale, suitable for display to a user. |
| * </p> |
| * <p> |
| * <code>KeySequence</code> objects are immutable. Clients are not permitted |
| * to extend this class. |
| * </p> |
| * |
| * @deprecated Please use org.eclipse.jface.bindings.keys.KeySequence |
| * @since 3.0 |
| */ |
| public final class KeySequence implements Comparable { |
| |
| /** |
| * The delimiter between multiple key strokes in a single key sequence -- |
| * expressed in the formal key stroke grammar. This is not to be displayed |
| * to the user. It is only intended as an internal representation. |
| */ |
| public final static String KEY_STROKE_DELIMITER = "\u0020"; //$NON-NLS-1$ |
| |
| /** |
| * An empty key sequence instance for use by everyone. |
| */ |
| private final static KeySequence EMPTY_KEY_SEQUENCE = new KeySequence( |
| Collections.EMPTY_LIST); |
| |
| /** |
| * An internal constant used only in this object's hash code algorithm. |
| */ |
| private final static int HASH_FACTOR = 89; |
| |
| /** |
| * An internal constant used only in this object's hash code algorithm. |
| */ |
| private final static int HASH_INITIAL = KeySequence.class.getName() |
| .hashCode(); |
| |
| /** |
| * The set of delimiters for <code>KeyStroke</code> objects allowed |
| * during parsing of the formal string representation. |
| */ |
| public final static String KEY_STROKE_DELIMITERS = KEY_STROKE_DELIMITER |
| + "\b\r\u007F\u001B\f\n\0\t\u000B"; //$NON-NLS-1$ |
| |
| /** |
| * Gets an instance of <code>KeySequence</code>. |
| * |
| * @return a key sequence. This key sequence will have no key strokes. |
| * Guaranteed not to be <code>null</code>. |
| */ |
| public static KeySequence getInstance() { |
| return EMPTY_KEY_SEQUENCE; |
| } |
| |
| /** |
| * Gets an instance of <code>KeySequence</code> given a key sequence and |
| * a key stroke. |
| * |
| * @param keySequence |
| * a key sequence. Must not be <code>null</code>. |
| * @param keyStroke |
| * a key stroke. Must not be <code>null</code>. |
| * @return a key sequence that is equal to the given key sequence with the |
| * given key stroke appended to the end. Guaranteed not to be |
| * <code>null</code>. |
| */ |
| public static KeySequence getInstance(KeySequence keySequence, |
| KeyStroke keyStroke) { |
| if (keySequence == null || keyStroke == null) { |
| throw new NullPointerException(); |
| } |
| |
| List keyStrokes = new ArrayList(keySequence.getKeyStrokes()); |
| keyStrokes.add(keyStroke); |
| return new KeySequence(keyStrokes); |
| } |
| |
| /** |
| * Gets an instance of <code>KeySequence</code> given a single key |
| * stroke. |
| * |
| * @param keyStroke |
| * a single key stroke. Must not be <code>null</code>. |
| * @return a key sequence. Guaranteed not to be <code>null</code>. |
| */ |
| public static KeySequence getInstance(KeyStroke keyStroke) { |
| return new KeySequence(Collections.singletonList(keyStroke)); |
| } |
| |
| /** |
| * Gets an instance of <code>KeySequence</code> given an array of key |
| * strokes. |
| * |
| * @param keyStrokes |
| * the array of key strokes. This array may be empty, but it |
| * must not be <code>null</code>. This array must not contain |
| * <code>null</code> elements. |
| * @return a key sequence. Guaranteed not to be <code>null</code>. |
| */ |
| public static KeySequence getInstance(KeyStroke[] keyStrokes) { |
| return new KeySequence(Arrays.asList(keyStrokes)); |
| } |
| |
| /** |
| * Gets an instance of <code>KeySequence</code> given a list of key |
| * strokes. |
| * |
| * @param keyStrokes |
| * the list of key strokes. This list may be empty, but it must |
| * not be <code>null</code>. If this list is not empty, it |
| * must only contain instances of <code>KeyStroke</code>. |
| * @return a key sequence. Guaranteed not to be <code>null</code>. |
| */ |
| public static KeySequence getInstance(List keyStrokes) { |
| return new KeySequence(keyStrokes); |
| } |
| |
| /** |
| * Gets an instance of <code>KeySequence</code> given a new-style key |
| * sequence. |
| * |
| * @param newKeySequence |
| * The new-style key sequence to convert into a legacy key |
| * sequence; must not be <code>null</code>. |
| * @return a key sequence; never <code>null</code>. |
| */ |
| public static final KeySequence getInstance( |
| final org.eclipse.jface.bindings.keys.KeySequence newKeySequence) { |
| final org.eclipse.jface.bindings.keys.KeyStroke[] newKeyStrokes = newKeySequence |
| .getKeyStrokes(); |
| final int newKeyStrokesCount = newKeyStrokes.length; |
| final List legacyKeyStrokes = new ArrayList(newKeyStrokesCount); |
| |
| for (int i = 0; i < newKeyStrokesCount; i++) { |
| final org.eclipse.jface.bindings.keys.KeyStroke newKeyStroke = newKeyStrokes[i]; |
| legacyKeyStrokes.add(SWTKeySupport |
| .convertAcceleratorToKeyStroke(newKeyStroke |
| .getModifierKeys() |
| | newKeyStroke.getNaturalKey())); |
| } |
| |
| return new KeySequence(legacyKeyStrokes); |
| } |
| |
| /** |
| * Gets an instance of <code>KeySequence</code> by parsing a given a |
| * formal string representation. |
| * |
| * @param string |
| * the formal string representation to parse. |
| * @return a key sequence. Guaranteed not to be <code>null</code>. |
| * @throws ParseException |
| * if the given formal string representation could not be |
| * parsed to a valid key sequence. |
| */ |
| public static KeySequence getInstance(String string) throws ParseException { |
| if (string == null) { |
| throw new NullPointerException(); |
| } |
| |
| List keyStrokes = new ArrayList(); |
| StringTokenizer stringTokenizer = new StringTokenizer(string, |
| KEY_STROKE_DELIMITERS); |
| |
| while (stringTokenizer.hasMoreTokens()) { |
| keyStrokes.add(KeyStroke.getInstance(stringTokenizer.nextToken())); |
| } |
| |
| try { |
| return new KeySequence(keyStrokes); |
| } catch (Throwable t) { |
| throw new ParseException( |
| "Could not construct key sequence with these key strokes: " //$NON-NLS-1$ |
| + keyStrokes); |
| } |
| } |
| |
| /** |
| * The cached hash code for this object. Because <code>KeySequence</code> |
| * objects are immutable, their hash codes need only to be computed once. |
| * After the first call to <code>hashCode()</code>, the computed value |
| * is cached here for all subsequent calls. |
| */ |
| private transient int hashCode; |
| |
| /** |
| * A flag to determine if the <code>hashCode</code> field has already |
| * been computed. |
| */ |
| private transient boolean hashCodeComputed; |
| |
| /** |
| * The list of key strokes for this key sequence. |
| */ |
| private List keyStrokes; |
| |
| /** |
| * Constructs an instance of <code>KeySequence</code> given a list of key |
| * strokes. |
| * |
| * @param keyStrokes |
| * the list of key strokes. This list may be empty, but it must |
| * not be <code>null</code>. If this list is not empty, it |
| * must only contain instances of <code>KeyStroke</code>. |
| */ |
| private KeySequence(List keyStrokes) { |
| this.keyStrokes = Util.safeCopy(keyStrokes, KeyStroke.class); |
| |
| for (int i = 0; i < this.keyStrokes.size() - 1; i++) { |
| KeyStroke keyStroke = (KeyStroke) this.keyStrokes.get(i); |
| |
| if (!keyStroke.isComplete()) { |
| throw new IllegalArgumentException(); |
| } |
| } |
| } |
| |
| /** |
| * @see java.lang.Object#equals(java.lang.Object) |
| */ |
| public int compareTo(Object object) { |
| KeySequence castedObject = (KeySequence) object; |
| int compareTo = Util.compare(keyStrokes, castedObject.keyStrokes); |
| return compareTo; |
| } |
| |
| /** |
| * Returns whether or not this key sequence ends with the given key |
| * sequence. |
| * |
| * @param keySequence |
| * a key sequence. Must not be <code>null</code>. |
| * @param equals |
| * whether or not an identical key sequence should be considered |
| * as a possible match. |
| * @return <code>true</code>, iff the given key sequence ends with this |
| * key sequence. |
| */ |
| public boolean endsWith(KeySequence keySequence, boolean equals) { |
| if (keySequence == null) { |
| throw new NullPointerException(); |
| } |
| |
| return Util.endsWith(keyStrokes, keySequence.keyStrokes, equals); |
| } |
| |
| /** |
| * @see java.lang.Object#equals(java.lang.Object) |
| */ |
| public boolean equals(Object object) { |
| if (!(object instanceof KeySequence)) { |
| return false; |
| } |
| |
| return keyStrokes.equals(((KeySequence) object).keyStrokes); |
| } |
| |
| /** |
| * Formats this key sequence into the current default look. |
| * |
| * @return A string representation for this key sequence using the default |
| * look; never <code>null</code>. |
| */ |
| public String format() { |
| return KeyFormatterFactory.getDefault().format(this); |
| } |
| |
| /** |
| * Returns the list of key strokes for this key sequence. |
| * |
| * @return the list of key strokes keys. This list may be empty, but is |
| * guaranteed not to be <code>null</code>. If this list is not |
| * empty, it is guaranteed to only contain instances of <code>KeyStroke</code>. |
| */ |
| public List getKeyStrokes() { |
| return keyStrokes; |
| } |
| |
| /** |
| * @see java.lang.Object#hashCode() |
| */ |
| public int hashCode() { |
| if (!hashCodeComputed) { |
| hashCode = HASH_INITIAL; |
| hashCode = hashCode * HASH_FACTOR + keyStrokes.hashCode(); |
| hashCodeComputed = true; |
| } |
| |
| return hashCode; |
| } |
| |
| /** |
| * Returns whether or not this key sequence is complete. Key sequences are |
| * complete iff all of their key strokes are complete. |
| * |
| * @return <code>true</code>, iff the key sequence is complete. |
| */ |
| public boolean isComplete() { |
| return keyStrokes.isEmpty() |
| || ((KeyStroke) keyStrokes.get(keyStrokes.size() - 1)) |
| .isComplete(); |
| } |
| |
| /** |
| * Returns whether or not this key sequence is empty. Key sequences are |
| * complete iff they have no key strokes. |
| * |
| * @return <code>true</code>, iff the key sequence is empty. |
| */ |
| public boolean isEmpty() { |
| return keyStrokes.isEmpty(); |
| } |
| |
| /** |
| * Returns whether or not this key sequence starts with the given key |
| * sequence. |
| * |
| * @param keySequence |
| * a key sequence. Must not be <code>null</code>. |
| * @param equals |
| * whether or not an identical key sequence should be considered |
| * as a possible match. |
| * @return <code>true</code>, iff the given key sequence starts with |
| * this key sequence. |
| */ |
| public boolean startsWith(KeySequence keySequence, boolean equals) { |
| if (keySequence == null) { |
| throw new NullPointerException(); |
| } |
| |
| return Util.startsWith(keyStrokes, keySequence.keyStrokes, equals); |
| } |
| |
| /** |
| * Returns the formal string representation for this key sequence. |
| * |
| * @return The formal string representation for this key sequence. |
| * Guaranteed not to be <code>null</code>. |
| * @see java.lang.Object#toString() |
| */ |
| public String toString() { |
| return KeyFormatterFactory.getFormalKeyFormatter().format(this); |
| } |
| } |