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

FlagValueEffect
Disambiguate1All keys get unambiguous CSI ? u encoding
Report event types2Adds press/repeat/release distinction
Report alternate keys4Sends shifted + base-layout key codes
Report all keys8Even plain letters become CSI sequences
Report associated text16Adds generated text as codepoints
See Also:
  • Field Details

  • 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