Skip to content

Commit

Permalink
Clarify the behavior of functional keys with no legacy encoding
Browse files Browse the repository at this point in the history
See #7037
  • Loading branch information
kovidgoyal committed Jan 22, 2024
1 parent 38393b5 commit a9c7a85
Showing 1 changed file with 7 additions and 3 deletions.
10 changes: 7 additions & 3 deletions docs/keyboard-protocol.rst
Original file line number Diff line number Diff line change
Expand Up @@ -105,9 +105,7 @@ do not. When a key event produces text, the text is sent directly as UTF-8
encoded bytes. This is safe as UTF-8 contains no C0 control codes.
When the key event does not have text, the key event is encoded as an escape code. In
legacy compatibility mode (the default) this uses legacy escape codes, so old terminal
applications continue to work. Key events that could not be represented in
legacy mode are encoded using a ``CSI u`` escape code, that most terminal
programs should just ignore. For more advanced features, such as release/repeat
applications continue to work. For more advanced features, such as release/repeat
reporting etc., applications can tell the terminal they want this information by
sending an escape code to :ref:`progressively enhance <progressive_enhancement>` the data reported for
key events.
Expand Down Expand Up @@ -482,6 +480,12 @@ must correspond to the :kbd:`Backspace` key.
All keypad keys are reported as their equivalent non-keypad keys. To
distinguish these, use the :ref:`disambiguate <disambiguate>` flag.

Terminals may choose what they want to do about functional keys that have no
legacy encoding. kitty chooses to encode these using ``CSI u`` encoding even in
legacy mode, so that they become usable even in programs that do not
understand the full kitty keyboard protocol. However, terminals may instead choose to
ignore such keys in legacy mode instead, or have an option to control this behavior.

.. _legacy_text:

Legacy text keys
Expand Down

0 comments on commit a9c7a85

Please sign in to comment.