KittyPatch/kitty
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Rationalize usage of :kbd:

Browse Source
This commit is contained in:
Kovid Goyal 2021-11-25 10:34:25 +05:30
parent fd331480fc
commit e68914f46b
No known key found for this signature in database
GPG Key ID: 06BC317B515ACE7C
5 changed files with 31 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/changelog.rst
View File

@ -112,7 +112,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
- Fix soft hyphens not being preserved when round tripping text through the - Fix soft hyphens not being preserved when round tripping text through the
terminal terminal
- macOS: Fix :kbd:`ctrl+shift` with :kbd:`Esc or Function keys` not working - macOS: Fix :kbd:`ctrl+shift` with :kbd:`Esc` or :kbd:`F1` - :kbd:`F12` not working
(:iss:`4109`) (:iss:`4109`)
- macOS: Fix :opt:`resize_in_steps` not working correctly on high DPI screens - macOS: Fix :opt:`resize_in_steps` not working correctly on high DPI screens

42
docs/keyboard-protocol.rst
View File

@ -66,10 +66,11 @@ key, such as ``97`` for the :kbd:`a` key, or one of the numbers from the
modifiers pressed for the key event. The encoding is described in the modifiers pressed for the key event. The encoding is described in the
:ref:`modifiers` section. :ref:`modifiers` section.
The second form is used for a few functional keys, such as the :kbd:`Home, End, The second form is used for a few functional keys, such as the :kbd:`Home`,
Arrow keys and F1-F4`, they are enumerated in the :ref:`functional` table below. :kbd:`End`, :kbd:`Arrow` keys and :kbd:`F1`...:kbd:`F4`, they are enumerated in
Note that if no modifiers are present the parameters are omitted entirely the :ref:`functional` table below. Note that if no modifiers are present the
giving an escape code of the form ``CSI [ABCDEFHPQRS]``. parameters are omitted entirely giving an escape code of the form ``CSI
[ABCDEFHPQRS]``.
If you want support for more advanced features such as repeat and release If you want support for more advanced features such as repeat and release
events, alternate keys for shortcut matching et cetera, these can be turned on events, alternate keys for shortcut matching et cetera, these can be turned on
@ -142,12 +143,13 @@ sub-field for the shifted key, like this::
Modifiers Modifiers
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
This protocol supports six modifier keys, :kbd:`shift, alt, ctrl, super, hyper This protocol supports six modifier keys, :kbd:`shift`, :kbd:`alt`,
and meta` as well as :kbd:`num_lock and caps_lock`. Here :kbd:`super` is either :kbd:`ctrl`, :kbd:`super`, :kbd:`hyper`, :kbd:`meta`, :kbd:`num_lock` and
the *Windows/Linux* key or the :kbd:`command` key on mac keyboards. The :kbd:`caps_lock`. Here :kbd:`super` is either the *Windows/Linux* key or the
:kbd:`alt` key is the :kbd:`option` key on mac keyboards. :kbd:`hyper` and :kbd:`command` key on mac keyboards. The :kbd:`alt` key is the :kbd:`option`
:kbd:`meta` are typically present only on X11/Wayland based systems with key on mac keyboards. :kbd:`hyper` and :kbd:`meta` are typically present only
special XKB rules. Modifiers are encoded as a bit field with:: on X11/Wayland based systems with special XKB rules. Modifiers are encoded as a
bit field with::
shift 0b1 (1) shift 0b1 (1)
alt 0b10 (2) alt 0b10 (2)
@ -210,9 +212,9 @@ Non-Unicode keys
There are many keys that don't correspond to letters from human languages, and There are many keys that don't correspond to letters from human languages, and
thus aren't represented in Unicode. Think of functional keys, such as thus aren't represented in Unicode. Think of functional keys, such as
:kbd:`Escape, Play, Pause, F1, Home, etc`. These are encoded using Unicode code :kbd:`Escape`, :kbd:`Play`, :kbd:`Pause`, :kbd:`F1`, :kbd:`Home`, etc. These
points from the Private Use Area (``57344 - 63743``). The mapping of key are encoded using Unicode code points from the Private Use Area (``57344 -
names to code points for these keys is in the 63743``). The mapping of key names to code points for these keys is in the
:ref:`Functional key definition table below <functional>`. :ref:`Functional key definition table below <functional>`.
@ -289,8 +291,8 @@ encodings overlapping with other control codes. For instance, pressing the
start of an escape code. Similarly pressing the key :kbd:`alt+[` will generate start of an escape code. Similarly pressing the key :kbd:`alt+[` will generate
the bytes used for CSI control codes. the bytes used for CSI control codes.
Turning on this flag will cause the terminal to report the :kbd:`Esc, alt+key, Turning on this flag will cause the terminal to report the :kbd:`Esc`, :kbd:`alt+key`,
ctrl+key, ctrl+alt+key, shift+alt+key` keys using ``CSI u`` sequences instead :kbd:`ctrl+key`, :kbd:`ctrl+alt+key`, :kbd:`shift+alt+key` keys using ``CSI u`` sequences instead
of legacy ones. Here key is any ASCII key as described in :ref:`legacy_text`. of legacy ones. Here key is any ASCII key as described in :ref:`legacy_text`.
Additionally, all keypad keys will be reported as separate keys with ``CSI u`` Additionally, all keypad keys will be reported as separate keys with ``CSI u``
encoding, using dedicated numbers from the :ref:`table below <functional>`. encoding, using dedicated numbers from the :ref:`table below <functional>`.
@ -305,7 +307,7 @@ This makes it very easy to parse key events in an application. In particular,
:kbd:`ctrl+c` will no longer generate the ``SIGINT`` signal, but instead be :kbd:`ctrl+c` will no longer generate the ``SIGINT`` signal, but instead be
delivered as a ``CSI u`` escape code. This has the nice side effect of making it delivered as a ``CSI u`` escape code. This has the nice side effect of making it
much easier to integrate into the application event loop. The only exceptions much easier to integrate into the application event loop. The only exceptions
are the :kbd:`Enter, Tab and Backspace` keys which still generate the same are the :kbd:`Enter`, :kbd:`Tab` and :kbd:`Backspace` keys which still generate the same
bytes as in legacy mode this is to allow the user to type and execute commands bytes as in legacy mode this is to allow the user to type and execute commands
in the shell such as ``reset`` after a program that sets this mode crashes in the shell such as ``reset`` after a program that sets this mode crashes
without clearing it. without clearing it.
@ -345,8 +347,8 @@ only key events are sent. If the text is needed as well, combine with the
Report associated text enhancement below. Report associated text enhancement below.
Additionally, with this mode, events for pressing modifier keys are reported. Additionally, with this mode, events for pressing modifier keys are reported.
Note that *all* keys are reported as escape codes, including :kbd:`Enter, Tab, Note that *all* keys are reported as escape codes, including :kbd:`Enter`,
Backspace` etc. :kbd:`Tab`, :kbd:`Backspace` etc.
.. _report_text: .. _report_text:
@ -459,8 +461,8 @@ Legacy text keys
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
For legacy compatibility, the keys For legacy compatibility, the keys
:kbd:`a-z 0-9 \` - = [ ] \ ; ' , . /` with the modifiers :kbd:`a`-:kbd:`z` :kbd:`0`-:kbd:`9` :kbd:`\`` :kbd:`-` :kbd:`=` :kbd:`[` :kbd:`]` :kbd:`\\` :kbd:`;` :kbd:`'` :kbd:`,` :kbd:`.` :kbd:`/` with the modifiers
:kbd:`shift, alt, ctrl, shift+alt, ctrl+alt` are output using the :kbd:`shift`, :kbd:`alt`, :kbd:`ctrl`, :kbd:`shift+alt`, :kbd:`ctrl+alt` are output using the
following algorithm: following algorithm:
#. If the :kbd:`alt` key is pressed output the byte for ``ESC (0x1b)`` #. If the :kbd:`alt` key is pressed output the byte for ``ESC (0x1b)``

10
docs/kittens/diff.rst
View File

@ -67,9 +67,9 @@ Keyboard controls
========================= =========================== ========================= ===========================
Action Shortcut Action Shortcut
========================= =========================== ========================= ===========================
Quit :kbd:`q, Ctrl+c, Esc` Quit :kbd:`q`, :kbd:`ctrl+c`, :kbd:`Esc`
Scroll line up :kbd:`k, up` Scroll line up :kbd:`k`, :kbd:`up`
Scroll line down :kbd:`j, down` Scroll line down :kbd:`j`, :kbd:`down`
Scroll page up :kbd:`PgUp` Scroll page up :kbd:`PgUp`
Scroll page down :kbd:`PgDn` Scroll page down :kbd:`PgDn`
Scroll to top :kbd:`Home` Scroll to top :kbd:`Home`
@ -85,8 +85,8 @@ Restore default context :kbd:`=`
Search forwards :kbd:`/` Search forwards :kbd:`/`
Search backwards :kbd:`?` Search backwards :kbd:`?`
Clear search :kbd:`Esc` Clear search :kbd:`Esc`
Scroll to next match :kbd:`>, .` Scroll to next match :kbd:`>`, :kbd:`.`
Scroll to previous match :kbd:`<, ,` Scroll to previous match :kbd:`<`, :kbd:`,`
========================= =========================== ========================= ===========================

4
docs/layouts.rst
View File

@ -145,8 +145,8 @@ define a few extra keybindings in :file:`kitty.conf`::
map ctrl+down neighboring_window down map ctrl+down neighboring_window down
Now you can create horizontal and vertical splits by using :kbd:`F5` and Now you can create horizontal and vertical splits by using :kbd:`F5` and
:kbd:`F6`. You can move them around using :kbd:`shift+arrow keys` :kbd:`F6`. You can move them around using :kbd:`shift+arrow` keys
and you can move focus to neighboring windows using :kbd:`ctrl+arrow keys`. and you can move focus to neighboring windows using :kbd:`ctrl+arrow` keys.
You can switch an existing split from horizontal to vertical and vice versa You can switch an existing split from horizontal to vertical and vice versa
using :kbd:`F7`. Finally, windows can be resized using :ref:`window_resizing`. using :kbd:`F7`. Finally, windows can be resized using :ref:`window_resizing`.