Package org.jline.terminal.impl

Class KittyKeyboardSupport

java.lang.Object

org.jline.terminal.impl.KittyKeyboardSupport

public final class KittyKeyboardSupport
extends Object

Utility class for Kitty Keyboard Protocol support in terminals.

The Kitty Keyboard Protocol is a progressive enhancement to terminal keyboard handling that replaces legacy, ambiguous escape code encodings with unambiguous CSI … u sequences. It allows applications to reliably distinguish key combinations that were previously indistinguishable, such as Shift+Enter versus Enter, or Ctrl+I versus Tab.

The protocol uses a flags-based push/pop stack model. Applications push a set of enhancement flags when entering an interactive mode and pop them when leaving. Main and alternate screens maintain independent stacks.

Enhancement Flags

Flag	Value	Effect
Disambiguate	1	All keys get unambiguous CSI … u encoding
Report event types	2	Adds press/repeat/release distinction
Report alternate keys	4	Sends shifted + base-layout key codes
Report all keys	8	Even plain letters become CSI sequences
Report associated text	16	Adds generated text as codepoints

See Also:

• Kitty Keyboard Protocol

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DA1_QUERY	DA1 (Primary Device Attributes) query used as sentinel: CSI c
static final int	EVENT_PRESS
static final int	EVENT_RELEASE
static final int	EVENT_REPEAT
static final int	FLAG_DISAMBIGUATE	Disambiguate escape codes: all keys get unambiguous CSI encoding.
static final int	FLAG_REPORT_ALL_KEYS	Report all keys as escape codes, including plain text keys.
static final int	FLAG_REPORT_ALTERNATES	Report alternate keys: shifted and base-layout key codes.
static final int	FLAG_REPORT_EVENTS	Report event types: press, repeat, release.
static final int	FLAG_REPORT_TEXT	Report associated text as Unicode codepoints.
static final int	KEY_BACKSPACE
static final int	KEY_CAPS_LOCK
static final int	KEY_DELETE
static final int	KEY_DOWN
static final int	KEY_END
static final int	KEY_ENTER
static final int	KEY_ESCAPE
static final int	KEY_F13
static final int	KEY_HOME
static final int	KEY_INSERT
static final int	KEY_KP_0
static final int	KEY_KP_1
static final int	KEY_KP_2
static final int	KEY_KP_3
static final int	KEY_KP_4
static final int	KEY_KP_5
static final int	KEY_KP_6
static final int	KEY_KP_7
static final int	KEY_KP_8
static final int	KEY_KP_9
static final int	KEY_KP_ADD
static final int	KEY_KP_BEGIN
static final int	KEY_KP_DECIMAL
static final int	KEY_KP_DELETE
static final int	KEY_KP_DIVIDE
static final int	KEY_KP_DOWN
static final int	KEY_KP_END
static final int	KEY_KP_ENTER
static final int	KEY_KP_EQUAL
static final int	KEY_KP_HOME
static final int	KEY_KP_INSERT
static final int	KEY_KP_LEFT
static final int	KEY_KP_MULTIPLY
static final int	KEY_KP_PAGE_DOWN
static final int	KEY_KP_PAGE_UP
static final int	KEY_KP_RIGHT
static final int	KEY_KP_SEPARATOR
static final int	KEY_KP_SUBTRACT
static final int	KEY_KP_UP
static final int	KEY_LEFT
static final int	KEY_LEFT_ALT
static final int	KEY_LEFT_CONTROL
static final int	KEY_LEFT_HYPER
static final int	KEY_LEFT_META
static final int	KEY_LEFT_SHIFT
static final int	KEY_LEFT_SUPER
static final int	KEY_MEDIA_FAST_FORWARD
static final int	KEY_MEDIA_LOWER_VOLUME
static final int	KEY_MEDIA_MUTE_VOLUME
static final int	KEY_MEDIA_PAUSE
static final int	KEY_MEDIA_PLAY
static final int	KEY_MEDIA_PLAY_PAUSE
static final int	KEY_MEDIA_RAISE_VOLUME
static final int	KEY_MEDIA_RECORD
static final int	KEY_MEDIA_REVERSE
static final int	KEY_MEDIA_REWIND
static final int	KEY_MEDIA_STOP
static final int	KEY_MEDIA_TRACK_NEXT
static final int	KEY_MEDIA_TRACK_PREVIOUS
static final int	KEY_MENU
static final int	KEY_NUM_LOCK
static final int	KEY_PAGE_DOWN
static final int	KEY_PAGE_UP
static final int	KEY_PAUSE
static final int	KEY_PRINT_SCREEN
static final int	KEY_RIGHT
static final int	KEY_RIGHT_ALT
static final int	KEY_RIGHT_CONTROL
static final int	KEY_RIGHT_HYPER
static final int	KEY_RIGHT_META
static final int	KEY_RIGHT_SHIFT
static final int	KEY_RIGHT_SUPER
static final int	KEY_SCROLL_LOCK
static final int	KEY_TAB
static final int	KEY_UP
static final int	MOD_ALT
static final int	MOD_CAPS_LOCK
static final int	MOD_CTRL
static final int	MOD_HYPER
static final int	MOD_META
static final int	MOD_NUM_LOCK
static final int	MOD_SHIFT
static final int	MOD_SUPER
static final String	QUERY_FLAGS	Query the current enhancement flags: CSI ? u

Method Summary

Modifier and Type	Method	Description
static String	altKey(char letter)	Builds a kitty keyboard escape sequence for Alt+letter.
static String	ctrlAltKey(char letter)	Builds a kitty keyboard escape sequence for Ctrl+Alt+letter.
static String	ctrlKey(char letter)	Builds a kitty keyboard escape sequence for Ctrl+letter.
static boolean	isFlagsResponse(String sequence)	Checks whether a raw sequence looks like a kitty keyboard flags query response.
static String	keySequence(int keyCode, int modifiers)	Builds a kitty keyboard escape sequence string for a key with modifiers.
static String	modifiedKey(int keyCode, boolean shift, boolean alt, boolean ctrl)	Builds a kitty keyboard escape sequence for a special key with modifiers.
static int	parseFlagsResponse(String sequence)	Parses the flags value from a kitty keyboard query response.
static String	popFlags()	Returns the escape sequence to pop a single entry from the stack.
static String	popFlags(int count)	Returns the escape sequence to pop enhancement flags from the stack.
static String	pushFlags(int flags)	Returns the escape sequence to push enhancement flags onto the stack.
static String	pushFlags(EnumSet<Terminal.KittyKeyboardMode> modes)	Returns the escape sequence to push enhancement modes onto the stack.
static int	toFlags(EnumSet<Terminal.KittyKeyboardMode> modes)	Converts a set of Terminal.KittyKeyboardMode values to the protocol bitmask.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

FLAG_DISAMBIGUATE

public static final int FLAG_DISAMBIGUATE

Disambiguate escape codes: all keys get unambiguous CSI encoding.

See Also:

• Constant Field Values

FLAG_REPORT_EVENTS

public static final int FLAG_REPORT_EVENTS

Report event types: press, repeat, release.

See Also:

• Constant Field Values

FLAG_REPORT_ALTERNATES

public static final int FLAG_REPORT_ALTERNATES

Report alternate keys: shifted and base-layout key codes.

See Also:

• Constant Field Values

FLAG_REPORT_ALL_KEYS

public static final int FLAG_REPORT_ALL_KEYS

Report all keys as escape codes, including plain text keys.

See Also:

• Constant Field Values

FLAG_REPORT_TEXT

public static final int FLAG_REPORT_TEXT

Report associated text as Unicode codepoints.

See Also:

• Constant Field Values

QUERY_FLAGS

public static final String QUERY_FLAGS

Query the current enhancement flags: CSI ? u

See Also:

• Constant Field Values

DA1_QUERY

public static final String DA1_QUERY

DA1 (Primary Device Attributes) query used as sentinel: CSI c

See Also:

• Constant Field Values

MOD_SHIFT

public static final int MOD_SHIFT

See Also:

• Constant Field Values

MOD_ALT

public static final int MOD_ALT

See Also:

• Constant Field Values

MOD_CTRL

public static final int MOD_CTRL

See Also:

• Constant Field Values

MOD_SUPER

public static final int MOD_SUPER

See Also:

• Constant Field Values

MOD_HYPER

public static final int MOD_HYPER

See Also:

• Constant Field Values

MOD_META

public static final int MOD_META

See Also:

• Constant Field Values

MOD_CAPS_LOCK

public static final int MOD_CAPS_LOCK

See Also:

• Constant Field Values

MOD_NUM_LOCK

public static final int MOD_NUM_LOCK

See Also:

• Constant Field Values

EVENT_PRESS

public static final int EVENT_PRESS

See Also:

• Constant Field Values

EVENT_REPEAT

public static final int EVENT_REPEAT

See Also:

• Constant Field Values

EVENT_RELEASE

public static final int EVENT_RELEASE

See Also:

• Constant Field Values

KEY_ESCAPE

public static final int KEY_ESCAPE

See Also:

• Constant Field Values

KEY_ENTER

public static final int KEY_ENTER

See Also:

• Constant Field Values

KEY_TAB

public static final int KEY_TAB

See Also:

• Constant Field Values

KEY_BACKSPACE

public static final int KEY_BACKSPACE

See Also:

• Constant Field Values

KEY_INSERT

public static final int KEY_INSERT

See Also:

• Constant Field Values

KEY_DELETE

public static final int KEY_DELETE

See Also:

• Constant Field Values

KEY_LEFT

public static final int KEY_LEFT

See Also:

• Constant Field Values

KEY_RIGHT

public static final int KEY_RIGHT

See Also:

• Constant Field Values

KEY_UP

public static final int KEY_UP

See Also:

• Constant Field Values

KEY_DOWN

public static final int KEY_DOWN

See Also:

• Constant Field Values

KEY_PAGE_UP

public static final int KEY_PAGE_UP

See Also:

• Constant Field Values

KEY_PAGE_DOWN

public static final int KEY_PAGE_DOWN

See Also:

• Constant Field Values

KEY_HOME

public static final int KEY_HOME

See Also:

• Constant Field Values

KEY_END

public static final int KEY_END

See Also:

• Constant Field Values

KEY_CAPS_LOCK

public static final int KEY_CAPS_LOCK

See Also:

• Constant Field Values

KEY_SCROLL_LOCK

public static final int KEY_SCROLL_LOCK

See Also:

• Constant Field Values

KEY_NUM_LOCK

public static final int KEY_NUM_LOCK

See Also:

• Constant Field Values

KEY_PRINT_SCREEN

public static final int KEY_PRINT_SCREEN

See Also:

• Constant Field Values

KEY_PAUSE

public static final int KEY_PAUSE

See Also:

• Constant Field Values

KEY_MENU

public static final int KEY_MENU

See Also:

• Constant Field Values

KEY_F13

public static final int KEY_F13

See Also:

• Constant Field Values

KEY_KP_0

public static final int KEY_KP_0

See Also:

• Constant Field Values

KEY_KP_1

public static final int KEY_KP_1

See Also:

• Constant Field Values

KEY_KP_2

public static final int KEY_KP_2

See Also:

• Constant Field Values

KEY_KP_3

public static final int KEY_KP_3

See Also:

• Constant Field Values

KEY_KP_4

public static final int KEY_KP_4

See Also:

• Constant Field Values

KEY_KP_5

public static final int KEY_KP_5

See Also:

• Constant Field Values

KEY_KP_6

public static final int KEY_KP_6

See Also:

• Constant Field Values

KEY_KP_7

public static final int KEY_KP_7

See Also:

• Constant Field Values

KEY_KP_8

public static final int KEY_KP_8

See Also:

• Constant Field Values

KEY_KP_9

public static final int KEY_KP_9

See Also:

• Constant Field Values

KEY_KP_DECIMAL

public static final int KEY_KP_DECIMAL

See Also:

• Constant Field Values

KEY_KP_DIVIDE

public static final int KEY_KP_DIVIDE

See Also:

• Constant Field Values

KEY_KP_MULTIPLY

public static final int KEY_KP_MULTIPLY

See Also:

• Constant Field Values

KEY_KP_SUBTRACT

public static final int KEY_KP_SUBTRACT

See Also:

• Constant Field Values

KEY_KP_ADD

public static final int KEY_KP_ADD

See Also:

• Constant Field Values

KEY_KP_ENTER

public static final int KEY_KP_ENTER

See Also:

• Constant Field Values

KEY_KP_EQUAL

public static final int KEY_KP_EQUAL

See Also:

• Constant Field Values

KEY_KP_SEPARATOR

public static final int KEY_KP_SEPARATOR

See Also:

• Constant Field Values

KEY_KP_LEFT

public static final int KEY_KP_LEFT

See Also:

• Constant Field Values

KEY_KP_RIGHT

public static final int KEY_KP_RIGHT

See Also:

• Constant Field Values

KEY_KP_UP

public static final int KEY_KP_UP

See Also:

• Constant Field Values

KEY_KP_DOWN

public static final int KEY_KP_DOWN

See Also:

• Constant Field Values

KEY_KP_PAGE_UP

public static final int KEY_KP_PAGE_UP

See Also:

• Constant Field Values

KEY_KP_PAGE_DOWN

public static final int KEY_KP_PAGE_DOWN

See Also:

• Constant Field Values

KEY_KP_HOME

public static final int KEY_KP_HOME

See Also:

• Constant Field Values

KEY_KP_END

public static final int KEY_KP_END

See Also:

• Constant Field Values

KEY_KP_INSERT

public static final int KEY_KP_INSERT

See Also:

• Constant Field Values

KEY_KP_DELETE

public static final int KEY_KP_DELETE

See Also:

• Constant Field Values

KEY_KP_BEGIN

public static final int KEY_KP_BEGIN

See Also:

• Constant Field Values

KEY_MEDIA_PLAY

public static final int KEY_MEDIA_PLAY

See Also:

• Constant Field Values

KEY_MEDIA_PAUSE

public static final int KEY_MEDIA_PAUSE

See Also:

• Constant Field Values

KEY_MEDIA_PLAY_PAUSE

public static final int KEY_MEDIA_PLAY_PAUSE

See Also:

• Constant Field Values

KEY_MEDIA_REVERSE

public static final int KEY_MEDIA_REVERSE

See Also:

• Constant Field Values

KEY_MEDIA_STOP

public static final int KEY_MEDIA_STOP

See Also:

• Constant Field Values

KEY_MEDIA_FAST_FORWARD

public static final int KEY_MEDIA_FAST_FORWARD

See Also:

• Constant Field Values

KEY_MEDIA_REWIND

public static final int KEY_MEDIA_REWIND

See Also:

• Constant Field Values

KEY_MEDIA_TRACK_NEXT

public static final int KEY_MEDIA_TRACK_NEXT

See Also:

• Constant Field Values

KEY_MEDIA_TRACK_PREVIOUS

public static final int KEY_MEDIA_TRACK_PREVIOUS

See Also:

• Constant Field Values

KEY_MEDIA_RECORD

public static final int KEY_MEDIA_RECORD

See Also:

• Constant Field Values

KEY_MEDIA_LOWER_VOLUME

public static final int KEY_MEDIA_LOWER_VOLUME

See Also:

• Constant Field Values

KEY_MEDIA_RAISE_VOLUME

public static final int KEY_MEDIA_RAISE_VOLUME

See Also:

• Constant Field Values

KEY_MEDIA_MUTE_VOLUME

public static final int KEY_MEDIA_MUTE_VOLUME

See Also:

• Constant Field Values

KEY_LEFT_SHIFT

public static final int KEY_LEFT_SHIFT

See Also:

• Constant Field Values

KEY_LEFT_CONTROL

public static final int KEY_LEFT_CONTROL

See Also:

• Constant Field Values

KEY_LEFT_ALT

public static final int KEY_LEFT_ALT

See Also:

• Constant Field Values

KEY_LEFT_SUPER

public static final int KEY_LEFT_SUPER

See Also:

• Constant Field Values

KEY_LEFT_HYPER

public static final int KEY_LEFT_HYPER

See Also:

• Constant Field Values

KEY_LEFT_META

public static final int KEY_LEFT_META

See Also:

• Constant Field Values

KEY_RIGHT_SHIFT

public static final int KEY_RIGHT_SHIFT

See Also:

• Constant Field Values

KEY_RIGHT_CONTROL

public static final int KEY_RIGHT_CONTROL

See Also:

• Constant Field Values

KEY_RIGHT_ALT

public static final int KEY_RIGHT_ALT

See Also:

• Constant Field Values

KEY_RIGHT_SUPER

public static final int KEY_RIGHT_SUPER

See Also:

• Constant Field Values

KEY_RIGHT_HYPER

public static final int KEY_RIGHT_HYPER

See Also:

• Constant Field Values

KEY_RIGHT_META

public static final int KEY_RIGHT_META

See Also:

• Constant Field Values

Method Details

toFlags

public static int toFlags(EnumSet<Terminal.KittyKeyboardMode> modes)

Converts a set of Terminal.KittyKeyboardMode values to the protocol bitmask.

Parameters:

modes - the enhancement modes

Returns:

the bitmask value used in the protocol escape sequences

pushFlags

public static String pushFlags(EnumSet<Terminal.KittyKeyboardMode> modes)

Returns the escape sequence to push enhancement modes onto the stack.

Parameters:

modes - the enhancement modes to enable

Returns:

the push escape sequence CSI > flags u

pushFlags

public static String pushFlags(int flags)

Returns the escape sequence to push enhancement flags onto the stack.

Parameters:

flags - the enhancement flags (bitmask of FLAG_* constants)

Returns:

the push escape sequence CSI > flags u

popFlags

public static String popFlags(int count)

Returns the escape sequence to pop enhancement flags from the stack.

Parameters:

count - the number of entries to pop (default 1)

Returns:

the pop escape sequence CSI < count u

popFlags

public static String popFlags()

Returns the escape sequence to pop a single entry from the stack.

Returns:

the pop escape sequence CSI < 1 u

keySequence

public static String keySequence(int keyCode,
 int modifiers)

Builds a kitty keyboard escape sequence string for a key with modifiers. Used for registering key bindings in KeyMap.

Parameters:

keyCode - the Unicode key code

modifiers - the modifier value (1 + bitmask), or 0 for no modifiers

Returns:

the escape sequence string

ctrlKey

public static String ctrlKey(char letter)

Builds a kitty keyboard escape sequence for Ctrl+letter. With the kitty protocol, Ctrl+A sends CSI 97;5u instead of 0x01.

Parameters:

letter - the lowercase letter ('a' through 'z')

Returns:

the kitty escape sequence for Ctrl+letter

altKey

public static String altKey(char letter)

Builds a kitty keyboard escape sequence for Alt+letter. With the kitty protocol, Alt+A sends CSI 97;3u instead of ESC followed by 'a'.

Parameters:

letter - the lowercase letter ('a' through 'z')

Returns:

the kitty escape sequence for Alt+letter

ctrlAltKey

public static String ctrlAltKey(char letter)

Builds a kitty keyboard escape sequence for Ctrl+Alt+letter.

Parameters:

letter - the lowercase letter ('a' through 'z')

Returns:

the kitty escape sequence for Ctrl+Alt+letter

modifiedKey

public static String modifiedKey(int keyCode,
 boolean shift,
 boolean alt,
 boolean ctrl)

Builds a kitty keyboard escape sequence for a special key with modifiers.

Parameters:

keyCode - the special key code (e.g., KEY_ENTER, KEY_TAB)

shift - whether shift is held

alt - whether alt is held

ctrl - whether ctrl is held

Returns:

the kitty escape sequence

isFlagsResponse

public static boolean isFlagsResponse(String sequence)

Checks whether a raw sequence looks like a kitty keyboard flags query response. The response format is CSI ? flags u.

Parameters:

sequence - the sequence to check

Returns:

true if it matches the response pattern

parseFlagsResponse

public static int parseFlagsResponse(String sequence)

Parses the flags value from a kitty keyboard query response.

Parameters:

sequence - the response sequence CSI ? flags u

Returns:

the flags value, or -1 if the sequence is not a valid response