Class KeySequence

  • All Implemented Interfaces:
    Comparable

    public final class KeySequence
    extends TriggerSequence
    implements Comparable

    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.

    Since:
    3.1
    • Field Detail

      • KEY_STROKE_DELIMITER

        public static final String KEY_STROKE_DELIMITER
        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.
        See Also:
        Constant Field Values
      • KEY_STROKE_DELIMITERS

        public static final String KEY_STROKE_DELIMITERS
        The set of delimiters for KeyStroke objects allowed during parsing of the formal string representation.
        See Also:
        Constant Field Values
    • Constructor Detail

      • KeySequence

        protected KeySequence​(KeyStroke[] keyStrokes)
        Constructs an instance of KeySequence given a list of key strokes.
        Parameters:
        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.
    • Method Detail

      • getInstance

        public static final KeySequence getInstance()
        Gets an instance of KeySequence.
        Returns:
        a key sequence. This key sequence will have no key strokes. Guaranteed not to be null.
      • getInstance

        public static final KeySequence getInstance​(KeySequence keySequence,
                                                    KeyStroke keyStroke)
        Creates an instance of KeySequence given a key sequence and a key stroke.
        Parameters:
        keySequence - a key sequence. Must not be null.
        keyStroke - a key stroke. Must not be null.
        Returns:
        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.
      • getInstance

        public static final KeySequence getInstance​(KeyStroke keyStroke)
        Creates an instance of KeySequence given a single key stroke.
        Parameters:
        keyStroke - a single key stroke. Must not be null.
        Returns:
        a key sequence. Guaranteed not to be null.
      • getInstance

        public static final KeySequence getInstance​(KeyStroke[] keyStrokes)
        Creates an instance of KeySequence given an array of key strokes.
        Parameters:
        keyStrokes - the array of key strokes. This array may be empty, but it must not be null. This array must not contain null elements.
        Returns:
        a key sequence. Guaranteed not to be null.
      • getInstance

        public static final KeySequence getInstance​(List<KeyStroke> keyStrokes)
        Creates an instance of KeySequence given a list of key strokes.
        Parameters:
        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.
        Returns:
        a key sequence. Guaranteed not to be null.
      • getInstance

        public static final KeySequence getInstance​(String string)
                                             throws ParseException
        Creates an instance of KeySequence by parsing a given formal string representation.
        Parameters:
        string - the formal string representation to parse.
        Returns:
        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.
      • format

        public final String format()
        Formats this key sequence into the current default look.
        Specified by:
        format in class TriggerSequence
        Returns:
        A string representation for this key sequence using the default look; never null.
      • getKeyStrokes

        public final KeyStroke[] getKeyStrokes()
        Returns the list of key strokes for this key sequence.
        Returns:
        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.
      • getPrefixes

        public final TriggerSequence[] getPrefixes()
        Description copied from class: TriggerSequence

        Returns a list of prefixes for the current sequence. A prefix is any leading subsequence in a TriggerSequence. A prefix is also an instance of TriggerSequence.

        For example, consider a trigger sequence that consists of four triggers: A, B, C and D. The prefixes would be "", "A", "A B", and "A B C". The list of prefixes must always be the same as the size of the trigger list.

        Specified by:
        getPrefixes in class TriggerSequence
        Returns:
        The array of possible prefixes for this sequence. This array must not be null, but may be empty. It must only contains instances of TriggerSequence.
      • isComplete

        public final boolean isComplete()
        Returns whether or not this key sequence is complete. Key sequences are complete iff all of their key strokes are complete.
        Returns:
        true, iff the key sequence is complete.
      • toString

        public final String toString()
        Returns the formal string representation for this key sequence.
        Overrides:
        toString in class Object
        Returns:
        The formal string representation for this key sequence. Guaranteed not to be null.