Class KittyKeyboardSupport


  • public final class KittyKeyboardSupport
    extends java.lang.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:
    Kitty Keyboard Protocol
    • Method Detail

      • toFlags

        public static int toFlags​(java.util.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 java.lang.String pushFlags​(java.util.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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​(java.lang.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​(java.lang.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