Class KeyMap<T>
- Type Parameters:
T
- the type of objects to which key sequences are bound
KeyMap is a core component of JLine's input handling system, providing the ability to bind specific key sequences (like Ctrl+A, Alt+F, or multi-key sequences) to arbitrary operations represented by objects of type T.
Key features include:
- Support for single-key and multi-key sequences
- Special handling for Unicode characters not explicitly bound
- Timeout handling for ambiguous bindings (e.g., Escape key vs. Alt combinations)
- Utility methods for creating common key sequences (Ctrl, Alt, etc.)
This class is used extensively by the LineReader
to implement
customizable key bindings for line editing operations.
- Since:
- 2.6
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final long
Default timeout in milliseconds for ambiguous bindings.static final int
The size of the direct mapping array for ASCII characters.static final Comparator
<String> Comparator for sorting key sequences. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic String
alt
(char c) Creates an Alt+key sequence for a single character.static String
Creates an Alt+key sequence for a string.void
bind
(T function, CharSequence keySeq) Binds a function to a key sequence.void
bind
(T function, CharSequence... keySeqs) Binds a function to multiple key sequences.void
bind
(T function, Iterable<? extends CharSequence> keySeqs) Binds a function to multiple key sequences.void
bindIfNotBound
(T function, CharSequence keySeq) Binds a function to a key sequence only if the key sequence is not already bound.static String
ctrl
(char key) Creates a Ctrl+key sequence for a character.static String
del()
Returns the delete character as a string.static String
Converts a key sequence to a displayable string representation.static String
esc()
Returns the escape character as a string.long
Gets the timeout for ambiguous key bindings in milliseconds.Gets the binding for the "another key" action.getBound
(CharSequence keySeq) Gets the binding for a key sequence.getBound
(CharSequence keySeq, int[] remaining) Gets the binding for a key sequence, with information about remaining characters.Returns a map of all bound key sequences and their associated bindings.Gets the binding for input sequences that don't match any known binding.Gets the binding for Unicode characters that don't have explicit bindings.static String
key
(Terminal terminal, InfoCmp.Capability capability) Returns the escape sequence for a terminal capability.static Collection
<String> Generates a collection of key sequences from a range specification.void
setAmbiguousTimeout
(long ambiguousTimeout) Sets the timeout for ambiguous key bindings in milliseconds.void
setNomatch
(T nomatch) Sets the binding for input sequences that don't match any known binding.void
setUnicode
(T unicode) Sets the binding for Unicode characters that don't have explicit bindings.static String
Translates a string containing special escape sequences into the actual key sequence.void
unbind
(CharSequence keySeq) Unbinds a key sequence.void
unbind
(CharSequence... keySeqs)
-
Field Details
-
KEYMAP_LENGTH
public static final int KEYMAP_LENGTHThe size of the direct mapping array for ASCII characters. Characters with code points below this value are mapped directly.- See Also:
-
DEFAULT_AMBIGUOUS_TIMEOUT
public static final long DEFAULT_AMBIGUOUS_TIMEOUTDefault timeout in milliseconds for ambiguous bindings.This is used when a prefix of a multi-character binding is also bound to an action. For example, if both Escape and Escape+[A are bound, the reader will wait this amount of time after receiving Escape to determine if it's a standalone Escape or the beginning of the Escape+[A sequence.
- See Also:
-
KEYSEQ_COMPARATOR
Comparator for sorting key sequences.This comparator sorts key sequences first by length, then lexicographically. It's useful for ensuring that longer key sequences are checked before their prefixes.
-
-
Constructor Details
-
KeyMap
public KeyMap()
-
-
Method Details
-
display
Converts a key sequence to a displayable string representation.This method formats control characters, escape sequences, and other special characters in a readable way, similar to how they might be represented in configuration files.
- Parameters:
key
- the key sequence to display- Returns:
- a readable string representation of the key sequence
-
translate
Translates a string containing special escape sequences into the actual key sequence.This method handles escape sequences like ^A (Ctrl+A), \e (Escape), \C-a (Ctrl+A), \M-a (Alt+A), etc., converting them to the actual character sequences they represent.
- Parameters:
str
- the string with escape sequences to translate- Returns:
- the translated key sequence
-
range
Generates a collection of key sequences from a range specification.This method takes a range specification like "a-z" or "\C-a-\C-z" and returns a collection of all key sequences in that range.
- Parameters:
range
- the range specification- Returns:
- a collection of key sequences in the specified range, or null if the range is invalid
-
esc
Returns the escape character as a string.- Returns:
- the escape character ("\033")
-
alt
Creates an Alt+key sequence for a single character.This is equivalent to pressing the Alt key and a character key simultaneously. Internally, this is represented as the escape character followed by the character.
- Parameters:
c
- the character to combine with Alt- Returns:
- the Alt+character key sequence
-
alt
Creates an Alt+key sequence for a string.This is equivalent to pressing the Alt key and typing a sequence of characters. Internally, this is represented as the escape character followed by the string.
- Parameters:
c
- the string to combine with Alt- Returns:
- the Alt+string key sequence
-
del
Returns the delete character as a string.- Returns:
- the delete character ("\177")
-
ctrl
Creates a Ctrl+key sequence for a character.This is equivalent to pressing the Ctrl key and a character key simultaneously. For example, Ctrl+A is represented as the character with code point 1.
- Parameters:
key
- the character to combine with Ctrl- Returns:
- the Ctrl+key sequence
-
key
Returns the escape sequence for a terminal capability.This method retrieves the escape sequence for special keys like arrow keys, function keys, etc., based on the terminal's capabilities.
- Parameters:
terminal
- the terminal to querycapability
- the capability to retrieve- Returns:
- the escape sequence for the specified capability
-
getUnicode
Gets the binding for Unicode characters that don't have explicit bindings.This is used as a fallback for characters that don't have specific bindings in the keymap. Typically, this might be set to a function that inserts the character into the line buffer.
- Returns:
- the binding for Unicode characters
-
setUnicode
Sets the binding for Unicode characters that don't have explicit bindings.- Parameters:
unicode
- the binding for Unicode characters
-
getNomatch
Gets the binding for input sequences that don't match any known binding.This is used as a fallback when an input sequence doesn't match any binding in the keymap.
- Returns:
- the binding for non-matching sequences
-
setNomatch
Sets the binding for input sequences that don't match any known binding.- Parameters:
nomatch
- the binding for non-matching sequences
-
getAmbiguousTimeout
public long getAmbiguousTimeout()Gets the timeout for ambiguous key bindings in milliseconds.This timeout is used when a prefix of a multi-character binding is also bound to an action. The reader will wait this amount of time after receiving the prefix to determine if more characters are coming.
- Returns:
- the ambiguous binding timeout in milliseconds
-
setAmbiguousTimeout
public void setAmbiguousTimeout(long ambiguousTimeout) Sets the timeout for ambiguous key bindings in milliseconds.- Parameters:
ambiguousTimeout
- the ambiguous binding timeout in milliseconds
-
getAnotherKey
Gets the binding for the "another key" action.This binding is returned when a key sequence doesn't match any binding but is a prefix of a longer binding. It's typically used to implement incremental search or other features that need to process each character as it's typed.
- Returns:
- the "another key" binding
-
getBoundKeys
Returns a map of all bound key sequences and their associated bindings.The map is sorted by key sequence using the
KEYSEQ_COMPARATOR
.- Returns:
- a map of bound key sequences to their bindings
-
getBound
Gets the binding for a key sequence, with information about remaining characters.This method returns the binding for the given key sequence, if one exists. It also provides information about how much of the key sequence was consumed in the
remaining
parameter:- If remaining[0] is -1, the entire sequence was consumed
- If remaining[0] is positive, that many characters at the end were not consumed
- If remaining[0] is 0, the sequence was consumed but no binding was found
- Parameters:
keySeq
- the key sequence to look upremaining
- array of length at least 1 to receive information about remaining characters- Returns:
- the binding for the key sequence, or null if no binding was found
-
getBound
Gets the binding for a key sequence.This method returns the binding for the given key sequence only if the entire sequence is consumed. If the sequence is a prefix of a longer binding or doesn't match any binding, null is returned.
- Parameters:
keySeq
- the key sequence to look up- Returns:
- the binding for the key sequence, or null if no binding was found or the sequence is a prefix
-
bindIfNotBound
Binds a function to a key sequence only if the key sequence is not already bound.This method is useful for setting up default bindings that should not override user-defined bindings.
- Parameters:
function
- the function to bindkeySeq
- the key sequence to bind to
-
bind
Binds a function to multiple key sequences.This is a convenience method that calls
bind(Object, CharSequence)
for each key sequence.- Parameters:
function
- the function to bindkeySeqs
- the key sequences to bind to
-
bind
Binds a function to multiple key sequences.This is a convenience method that calls
bind(Object, CharSequence)
for each key sequence in the iterable.- Parameters:
function
- the function to bindkeySeqs
- the key sequences to bind to
-
bind
Binds a function to a key sequence.If the function is null, the key sequence is unbound.
- Parameters:
function
- the function to bind, or null to unbindkeySeq
- the key sequence to bind to
-
unbind
-
unbind
Unbinds a key sequence.This removes any binding associated with the given key sequence.
- Parameters:
keySeq
- the key sequence to unbind
-