Keysyms

A keysym is an integer that stands for the symbol a key produces, such as a, Return or dead_acute. The type keysym is (unsigned-byte 32). The keysyms and their names are those of X11 and xkbcommon; the full list is in xkbcommon-keysyms.h.

Four functions convert keysyms. None of them needs a context or a keymap.

find-keysym: from a name

(xkb:find-keysym "Return")                         ; => 65293 (#xff0d)
(xkb:find-keysym "a")                              ; => 97
(xkb:find-keysym "A")                              ; => 65
(xkb:find-keysym "aring")                          ; => 229, for å
(xkb:find-keysym "return")                         ; => NIL
(xkb:find-keysym "RETURN" :case-insensitive t)     ; => 65293
(xkb:find-keysym "NoSuchKeysym")                   ; => NIL

Names are case-sensitive, because a and A are different keysyms. With :case-insensitive t, case does not matter, and where two keysyms differ only in case the lowercase one is returned.

Use find-keysym to turn the keysym names in a configuration file into keysyms once, at load time, and compare integers afterwards.

keysym-name: to a name

(xkb:keysym-name 65293)        ; => "Return"
(xkb:keysym-name #x1234567)    ; => "0x01234567"  (a keysym without a name)
(xkb:keysym-name #x20000000)   ; => NIL           (not a keysym)

Keysyms have 29 bits. A valid keysym without a name is named by its number in hex. Anything above 29 bits is not a keysym, and keysym-name returns nil for it.

keysym-character: to a character

(xkb:keysym-character (xkb:find-keysym "a"))       ; => #\a
(xkb:keysym-character (xkb:find-keysym "aring"))   ; => #\å
(xkb:keysym-character (xkb:find-keysym "Return"))  ; => #\Return
(xkb:keysym-character (xkb:find-keysym "F1"))      ; => NIL

It returns nil for keysyms that stand for no character, such as function keys and modifiers.

character-keysym: from a character

(xkb:keysym-name (xkb:character-keysym #\[))       ; => "bracketleft"
(xkb:keysym-name (xkb:character-keysym #\å))       ; => "aring"
(xkb:keysym-name (xkb:character-keysym #\Return))  ; => "Return"
(xkb:character-keysym (code-char 0))               ; => NIL

The inverse of keysym-character. Use it to write shortcuts by the character a key types, as (character-keysym #\[) rather than (find-keysym "bracketleft"). Characters without a keysym name get a Unicode keysym, which keysym-name names as "U1F600".

For text input, use key-press-text rather than keysym-character of key-keysym. It composes dead keys and compose sequences, handles keys whose text is not one character, and gives control characters such as Control+C.

Common keysym names

Name	Key
Return, KP_Enter	Return, keypad Enter
Escape, Tab, ISO_Left_Tab	Escape, Tab, Shift+Tab
BackSpace, Delete, Insert
Left, Right, Up, Down	arrows
Home, End, Prior, Next	Home, End, Page Up, Page Down
F1 ... F35	function keys
Shift_L, Shift_R, Control_L, Control_R	modifiers
Alt_L, Alt_R, Super_L, Super_R, ISO_Level3_Shift	modifiers (AltGr is ISO_Level3_Shift)
space, a ... z, A ... Z, 0 ... 9
aring, adiaeresis, odiaeresis, eacute	å, ä, ö, é
dead_acute, dead_grave, dead_diaeresis, dead_tilde	dead keys
Multi_key	the Compose key