This package provides support for the Kitty Keyboard Protocol (KKP).
KKP defines an alternative way to handle keyboard input for programs running in the terminal. This allows, if the terminal (and intermediaries such as terminal multiplexers) support the protocol as well, the transmission of more detailed information about a key event from the terminal to Emacs, e.g., it transmits “<tab>” and “C-i” differently.
Currently, there exists another solution which solves the same problem, xterm’s “modifyOtherKeys”, which is already supported by Emacs (and activated by default if the terminal supports it). KKP has the advantage of supporting more keys (e.g., “<menu>” or “<Scroll_Lock>”), more key combinations (e.g., “C-M-S-z”) and more modifiers, i.e., the Hyper and Super keys. It can also dynamically detect if a terminal supports the protocol, whereas Emacs has to deduce “modifyOtherKeys” support from the TERM variable.
This package supports the “Disambiguate escape codes” and “Report alternate keys” enhancements. I use it on a regular basis and it has seen some testing from other users.
You can install this package from Melpa, by first ensuring that you have the melpa source in your package-archives.
(require 'package)
(add-to-list 'package-archives
'("melpa" . "http://melpa.org/packages/") t)
(package-initialize)
(package-refresh-contents)Once that is done, this package can be installed.
package-install kkp(use-package kkp
:ensure t
:config
;; (setq kkp-alt-modifier 'alt) ;; use this if you want to map the Alt keyboard modifier to Alt in Emacs (and not to Meta)
(global-kkp-mode +1))kkp.el works out of the box by enabling global-kkp-mode and is customizable via the kkp-* customization variables.
If you want to know if your terminal supports kkp, if its activated, and if yes, which enhancements are active, use kkp-status.
You can control the enabled enhancements by setting kkp-active-enhancements.
By default, it is set to (disambiguate-escape-codes report-alternate-keys).
Note that when you activate only disambiguate-escape-codes,
the terminal reports shifted keypresses which involve another modifier by sending the modifiers with the base layout of the key.
This means “M-S-.” (Meta-Shift-.) is not translated to “M-:” (on a German keyboard) and Emacs will probably not find the proper keybinding.
report-alternate-keys fixes this, but if you do not want to activate it, you can remap keys by using the key-translation-map:
(define-key key-translation-map (kbd "M-S-.") (kbd "M-:"))The standard xterm encoding is quite old and cannot transmit key combinations such as “C-.”.
At the request of an Emacs user, xterm introduced “modifyOtherKeys” in version 216. This feature encodes ‘ordinary (i.e., “other”) keys (such as “2”) when modified by Shift-, Control-, Alt- or Meta-modifiers by an escape sequence’ (source). By default, it uses a “CSI 27 ; modifier ; code ~” encoding. CSI (Control Sequence Introducer) is the bytes sequence “\e[“, i.e., \x1b\x5b.
By request of Paul Leonerd Evans, xterm introduced an alternative encoding for the same keys, using a CSI-u encoding (“CSI modifier ; code u”). This is turned on by an xterm setting, formatOtherKeys. Paul Leonerd Evans documented this approach in his fixterms proposals, but does not mention if it differs from the formatOtherKeys implementation in xterm.
Thomas Dickey documents the “modifyOtherKeys/formatOtherKeys” evolution in more detail here.
On the basis of the fixterms proposal, Kovid Goyal devised the Kitty Keyboard Protocol. This protocol does not deviate a lot from the fixterms proposal:
- It fixes some bugs in fixterms.
- It enables runtime opt-in and opt-out of enhancements (e.g., CSI-u encoding).
- It optionally also supports reporting event types or alternate keys.
For a complete list of enhancements, read https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement. For Emacs, other enhancements than “Disambiguate escape codes” and “Report alternate keys” do not appear to be relevant.