API Reference

Every exported symbol of the package cl-xkbcommon, by topic. Every function checks the types of its arguments and signals a type-error for a wrong one.

• Conditions and types
• Contexts
• Keymaps
• Keyboard states
• Keysyms
• Compose
• Typing

Conditions and types

xkb-error condition

Signalled when libxkbcommon cannot do what was asked, such as compiling a keymap for a layout that does not exist, and when a destroyed object is used. The message includes what libxkbcommon logged about it. Subtype of error. See Errors and Logging.

xkb-error-message condition → string

The message of an xkb-error: what went wrong, and what to do about it.

keycode type

An xkb keycode: on Linux, the evdev code of a key plus 8, as evdev-keycode computes it. (unsigned-byte 32).

evdev-keycode code → keycode

Return the xkb keycode of the key with the Linux evdev code code, as wl_keyboard's key and enter events and evdev itself report keys: code plus 8. X11 reports xkb keycodes already.

keysym type

A keysym: the symbol a key produces, such as the one find-keysym returns for "Return" or "a". (unsigned-byte 32).

modifier-keyword type

A keyword that names one of the common modifiers: :shift, :caps-lock, :control, :alt, :num-lock, :super, :level-3 (AltGr), :level-5, :meta, :hyper or :scroll-lock, in the order active-modifiers lists them. keymap-modifier-p, modifier-active-p and modifier-consumed-p take one, or the name of a modifier as a string; any other keyword is a type-error. A keymap need not have every modifier: keymap-modifier-p says whether it has one.

Contexts

context class

A libxkbcommon context, where keymaps and compose tables are compiled, and what libxkbcommon logs about compiling them. One thread at a time.

make-context &key (default-includes t) (environment t) (log-limit 100) → context

Return a new context.

• default-includes: when true, keymap data is found where the system keeps it.
• environment: when true, layout names left out of make-keymap default to the variables XKB_DEFAULT_RULES, XKB_DEFAULT_MODEL, XKB_DEFAULT_LAYOUT, XKB_DEFAULT_VARIANT and XKB_DEFAULT_OPTIONS. When false, they default to the built-in defaults, which is repeatable.
• log-limit: a positive integer, the most log messages the context keeps for take-log-messages. Once it holds that many, each new message drops the oldest. Anything else signals a type-error.

Signals xkb-error if libxkbcommon cannot make one.

destroy-context context → (no values)

Destroy context. Keymaps and compose tables made with it stay usable.

with-context (var &rest options) &body body macro

Evaluate body with var bound to a context made with options, as make-context takes them, and destroy it afterwards.

take-log-messages context → list

Return what libxkbcommon logged through context since the last call, and empty the log. The result is a list of (level message), oldest first, where level is :critical, :error or :warning: the newest, up to the context's log limit. Returns nil on platforms other than x86-64, where the messages go to standard error.

Keymaps

keymap class

A compiled keymap: what each key of a keyboard produces, in each layout and with each combination of modifiers. May be read from several threads at once.

make-keymap context &key rules model layout variant options → keymap

Return a keymap compiled in context from layout names. Each is a string or nil; nil means the default.

• layout: such as "us", "se", or "us,se" for two layouts.
• variant: such as "dvorak"; one per layout, separated by commas.
• model: such as "pc105".
• options: such as "compose:ralt"; several separated by commas.
• rules: normally "evdev".

Signals xkb-error if the names make no keymap.

make-keymap-from-string context string → keymap

Return a keymap compiled in context from string, a keymap in the XKB text format, as a Wayland compositor sends it or keymap-string returns it. Signals xkb-error if it does not compile.

destroy-keymap keymap → (no values)

Destroy keymap. Keyboard states made from it stay usable.

with-keymap (var context &rest options) &body body macro

Evaluate body with var bound to a keymap made in context with options, as make-keymap takes them, and destroy it afterwards.

keymap-string keymap → string

Return keymap in the XKB text format, which make-keymap-from-string reads.

keymap-layouts keymap → list

Return the names of keymap's layouts, in order of their indices, such as ("English (US)" "Swedish").

keymap-modifiers keymap → list

Return the names of keymap's modifiers, in order of their indices: modifier n is bit n of the masks of update-modifiers and keyboard-state-masks.

keymap-modifier-p keymap modifier → boolean

Return true if keymap has modifier, a modifier-keyword such as :alt or :super, or the name of a modifier as a string.

keymap-keycode-range keymap → least, greatest

Return the least and the greatest keycode keymap may use.

key-name keymap keycode → string or nil

Return the name of the key keycode in keymap, such as "AC01" for the key where US keyboards have A, or nil if it has none.

find-key keymap name → keycode or nil

Return the keycode of the key called name in keymap, such as "AC01", or nil if there is none.

key-repeats-p keymap keycode → boolean

Return true if the key keycode should repeat while held, as letters do and modifiers do not. Repeating is the application's job.

Keyboard states

keyboard-state class

The state of a keyboard: which modifiers are held, latched or locked, and which layout is active. One thread at a time.

make-keyboard-state keymap → keyboard-state

Return a new keyboard state of a keyboard with keymap, with no key held.

destroy-keyboard-state state → (no values)

Destroy the keyboard state. Its keymap stays usable.

with-keyboard-state (var keymap) &body body macro

Evaluate body with var bound to a new keyboard state of keymap, and destroy it afterwards.

keyboard-state-keymap state → keymap

Return the keymap state was made with, to ask it about keys, as with key-repeats-p, or to destroy it with the state.

update-key state keycode direction → boolean

Update state for the key keycode going down or up; direction is :press or :release. Return true if the modifiers in effect or the active layout changed, and with them what keys produce.

Use it where the application tracks modifiers itself, as with evdev. Where the platform tracks them, as Wayland does, use update-modifiers instead.

update-modifiers state depressed latched locked layout → boolean

Set state's modifiers from the masks depressed, latched and locked, and its active layout index, as a Wayland compositor sends them in wl_keyboard.modifiers. Bit n of a mask stands for modifier n of the keymap. Return true if the modifiers in effect or the active layout changed. All four arguments are (unsigned-byte 32).

keyboard-state-masks state → depressed, latched, locked, layout

Return state's depressed, latched and locked modifier masks and its layout index, as update-modifiers takes them.

keyboard-state-layout state → index

Return the index of the active layout, among keymap-layouts.

key-keysym state keycode → keysym or nil

Return the keysym the key keycode produces in state, with its modifiers and layout, or nil if it produces none or more than one.

key-text state keycode → string or nil

Return the text the key keycode types in state, with its modifiers and layout, or nil if it types none, as for Shift, an arrow key or a dead key. It does not compose: for typing, use key-press-text.

modifier-active-p state modifier → boolean

Return true if modifier is in effect in state: held, latched or locked. modifier is a modifier-keyword, one of :shift, :caps-lock, :control, :alt, :num-lock, :super, :level-3 (AltGr), :level-5, :meta, :hyper and :scroll-lock, or the name of one of the keymap's modifiers as a string. A keyword the keymap lacks is never in effect. Signals xkb-error for a name the keymap lacks.

modifier-consumed-p state keycode modifier → boolean

Return true if modifier went into what the key keycode produces in state, as Shift does into A, so that a shortcut such as Control+A should not count it. modifier is as for modifier-active-p, and a keyword the keymap lacks is never consumed.

active-modifiers state &key except-consumed-by → list

Return the modifier keywords in effect in state, such as (:shift :control), in the order modifier-active-p lists them. A keyword that the keymap maps to the same real modifiers as one before it is left out: most keymaps put Meta on Alt's, so holding Alt gives (:alt), while modifier-active-p is true for both.

With except-consumed-by, a keycode, leave out the modifiers that key consumes, so that Control+Shift+A gives (:control) with the keysym A. For matching shortcuts, key-shortcut also leaves out the locks.

key-shortcut state keycode → keysym, modifiers

Return the keysym of the key keycode as a shortcut in state, and the list of the shortcut's modifiers, or nil and nil if the key produces no single keysym. The modifiers are those of active-modifiers that the key does not consume, without the locks Caps Lock, Num Lock and Scroll Lock. The keysym is the one the key produces with Caps Lock off.

So Control+Shift+S gives the keysym S and (:control), and Control+S gives s and (:control), whether Caps Lock or Num Lock is on or not. Num Lock still decides what keypad keys produce, as KP_1 or KP_End.

Keysyms

keysym-name keysym → string or nil

Return the name of keysym, such as "Return", "a" or "aring", or nil if it is not a keysym. A keysym without a name is named by its number, such as "0x01234567".

find-keysym name &key case-insensitive → keysym or nil

Return the keysym called name, such as "Return", "a" or "F1", or nil if there is none. With case-insensitive, letter case in name does not matter, and where two keysyms differ only in case, the lowercase one wins.

keysym-character keysym → character or nil

Return the character keysym stands for, such as #\a, #\å or #\Return, or nil if it stands for none, as for F1 or Shift_L.

character-keysym character → keysym or nil

Return the keysym that stands for character, such as the one called "bracketleft" for #\[, "aring" for #\å or "Return" for #\Return, or nil if there is none, as for #\Nul. Use it to write shortcuts by the character a key types; keysym-character goes the other way.

Compose

compose-table class

The compose sequences of a locale: which sequences of keysyms, such as a dead acute and e, compose which text, such as é. One thread at a time.

make-compose-table context &key locale (errorp t) → compose-table or nil

Return the compose table of locale, such as "en_US.UTF-8", compiled in context from the system's compose files and the user's ~/.XCompose. locale defaults to the environment's: LC_ALL, LC_CTYPE or LANG, or "C".

If the locale has no table, signal xkb-error; or, with errorp false, return nil, which key-press-text and with-compose-state take as typing without composing, and leave the reason to take-log-messages.

make-compose-table-from-string context string &key (locale "C") → compose-table

Return a compose table compiled in context from string, in the XCompose format, such as <dead_acute> <e> : "é" eacute. locale decides what an include of %L in string reads. A line that does not parse is skipped, and take-log-messages says why. Signals xkb-error if the table cannot be made at all.

destroy-compose-table table → (no values)

Destroy the compose table. Compose states made from it stay usable.

with-compose-table (var context &rest options) &body body macro

Evaluate body with var bound to a compose table made in context with options, as make-compose-table takes them, and destroy it afterwards. With :errorp nil among options, var is nil if the locale has no table.

compose-state class

Where a compose sequence has got to. One thread at a time. Its status is one of

Status	Meaning	What to do
:nothing	no sequence is under way	use the key's own text
:composing	the key continues a sequence	type nothing yet
:composed	the sequence is complete	type compose-text, then compose-reset
:cancelled	the key broke the sequence	type nothing, then compose-reset

key-press-text does all of this.

make-compose-state table → compose-state

Return a new compose state for table, with no sequence under way.

destroy-compose-state state → (no values)

Destroy the compose state.

with-compose-state (var table) &body body macro

Evaluate body with var bound to a new compose state for table, and destroy it afterwards. If table is nil, as with-compose-table binds it with :errorp nil for a locale without one, var is nil, which key-press-text takes as typing without composing.

compose-feed state keysym → status

Feed keysym, of a key just pressed, to state, and return its status after it. Keysyms of modifiers leave the status as it was.

compose-status state → status

Return the status of state.

compose-text state → string or nil

Return the text state has composed when its status is :composed, else nil.

compose-keysym state → keysym or nil

Return the keysym state has composed when its status is :composed, else nil.

compose-reset state → (no values)

Return state to no sequence under way.

Typing

key-press-text state compose keycode → string or nil

Return the text a press of the key keycode types in the keyboard state, or nil if it types none, with dead keys and compose sequences composed by the compose state compose: a dead acute types nothing, and an e after it types "é".

Call it once for each press, never for releases, since it feeds compose. With update-key, call it before updating state for the same press. With compose nil, as when the locale has no compose table, or for a repeated key, it returns key-text.