org.eclipse.ui.keys.KeySequence Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of workbench Show documentation
Show all versions of workbench Show documentation
This plug-in contains the bulk of the Workbench implementation, and depends on JFace, SWT, and Core Runtime. It cannot be used independently from org.eclipse.ui. Workbench client plug-ins should not depend directly on this plug-in.
The newest version!
/*******************************************************************************
* 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;
/**
*
* A KeySequence is defined as a list of zero or more
* KeyStrokes, with the stipulation that all
* KeyStroke objects must be complete, save for the last one,
* whose completeness is optional. A KeySequence is said to be
* complete if all of its KeyStroke objects are complete.
*
*
* All KeySequence objects have a formal string representation
* available via the toString() method. There are a number of
* methods to get instances of KeySequence objects, including one
* which can parse this formal string representation.
*
*
* All KeySequence objects, via the format()
* method, provide a version of their formal string representation translated by
* platform and locale, suitable for display to a user.
*
*
* KeySequence objects are immutable. Clients are not permitted
* to extend this class.
*
*
* @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 KeyStroke 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 KeySequence.
*
* @return a key sequence. This key sequence will have no key strokes.
* Guaranteed not to be null.
*/
public static KeySequence getInstance() {
return EMPTY_KEY_SEQUENCE;
}
/**
* Gets an instance of KeySequence given a key sequence and
* a key stroke.
*
* @param keySequence
* a key sequence. Must not be null.
* @param keyStroke
* a key stroke. Must not be null.
* @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
* null.
*/
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 KeySequence given a single key
* stroke.
*
* @param keyStroke
* a single key stroke. Must not be null.
* @return a key sequence. Guaranteed not to be null.
*/
public static KeySequence getInstance(KeyStroke keyStroke) {
return new KeySequence(Collections.singletonList(keyStroke));
}
/**
* Gets an instance of KeySequence given an array of key
* strokes.
*
* @param keyStrokes
* the array of key strokes. This array may be empty, but it
* must not be null. This array must not contain
* null elements.
* @return a key sequence. Guaranteed not to be null.
*/
public static KeySequence getInstance(KeyStroke[] keyStrokes) {
return new KeySequence(Arrays.asList(keyStrokes));
}
/**
* Gets an instance of KeySequence given a list of key
* strokes.
*
* @param keyStrokes
* the list of key strokes. This list may be empty, but it must
* not be null. If this list is not empty, it
* must only contain instances of KeyStroke.
* @return a key sequence. Guaranteed not to be null.
*/
public static KeySequence getInstance(List keyStrokes) {
return new KeySequence(keyStrokes);
}
/**
* Gets an instance of KeySequence given a new-style key
* sequence.
*
* @param newKeySequence
* The new-style key sequence to convert into a legacy key
* sequence; must not be null.
* @return a key sequence; never null.
*/
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 KeySequence by parsing a given a
* formal string representation.
*
* @param string
* the formal string representation to parse.
* @return a key sequence. Guaranteed not to be null.
* @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 KeySequence
* objects are immutable, their hash codes need only to be computed once.
* After the first call to hashCode(), the computed value
* is cached here for all subsequent calls.
*/
private transient int hashCode;
/**
* A flag to determine if the hashCode 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 KeySequence given a list of key
* strokes.
*
* @param keyStrokes
* the list of key strokes. This list may be empty, but it must
* not be null. If this list is not empty, it
* must only contain instances of KeyStroke.
*/
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 null.
* @param equals
* whether or not an identical key sequence should be considered
* as a possible match.
* @return true, 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 null.
*/
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 null. If this list is not
* empty, it is guaranteed to only contain instances of KeyStroke.
*/
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 true, 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 true, 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 null.
* @param equals
* whether or not an identical key sequence should be considered
* as a possible match.
* @return true, 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 null.
* @see java.lang.Object#toString()
*/
public String toString() {
return KeyFormatterFactory.getFormalKeyFormatter().format(this);
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy