Raw FFI Layer

The system cl-xkbcommon/ffi and the package of the same name hold the raw bindings that cl-xkbcommon is built on. They cover the part of xkbcommon.h and xkbcommon-compose.h that cl-xkbcommon uses.

Use them only for what cl-xkbcommon does not cover. They take and return foreign pointers, do no error checking, and leave freeing memory to you. If you need something from this layer for a common task, the idiomatic layer is missing it: please open an issue.

Naming

One Lisp function per C function. The xkb_ prefix is dropped and underscores become hyphens:

C	Lisp
xkb_context_new	context-new
xkb_keymap_new_from_names	keymap-new-from-names
xkb_state_key_get_one_sym	state-key-get-one-sym
xkb_compose_state_feed	compose-state-feed

Enums and flags are cl-ffi enums and bitfields, so they take keywords and lists of keywords:

(cl-xkbcommon/ffi:context-new '(:no-environment-names))
(cl-xkbcommon/ffi:state-serialize-mods state-pointer '(:mods-depressed :mods-latched))

Contents

Constants: +keycode-invalid+, +layout-invalid+, +mod-invalid+, +keysym-no-symbol+.

Enums and bitfields: context-flags, log-level, keymap-format, key-direction, state-component, keysym-flags, compose-status, compose-feed-result.

Structs: rule-names, with slots rules, model, layout, variant, options.

Contexts: context-new, context-unref, context-set-log-fn, context-set-log-level, context-set-user-data, context-get-user-data.

Keymaps: keymap-new-from-names, keymap-new-from-string, keymap-new-from-buffer, keymap-unref, keymap-get-as-string, keymap-min-keycode, keymap-max-keycode, keymap-num-layouts, keymap-layout-get-name, keymap-num-mods, keymap-mod-get-name, keymap-mod-get-index, keymap-mod-get-mask (libxkbcommon 1.10), keymap-key-repeats, keymap-key-get-name, keymap-key-by-name.

States: state-new, state-unref, state-update-key, state-update-mask, state-key-get-one-sym, state-key-get-utf8, state-serialize-mods, state-serialize-layout, state-mod-index-is-active, state-mod-index-is-consumed.

Keysyms: keysym-get-name, keysym-from-name, keysym-to-utf32, utf32-to-keysym.

Compose: compose-table-new-from-locale, compose-table-new-from-buffer, compose-table-unref, compose-state-new, compose-state-unref, compose-state-feed, compose-state-reset, compose-state-get-status, compose-state-get-utf8, compose-state-get-one-sym.

The C library: free, for strings libxkbcommon returns to the caller, such as that of keymap-get-as-string.

Each function has a short docstring and an ftype declamation. Its C function is its name with xkb_ in front and underscores for hyphens. For the full behaviour, see the libxkbcommon API documentation.

Loading the library

cl-xkbcommon/ffi loads libxkbcommon.so.0, or libxkbcommon.so, when the system is loaded. On other platforms, it loads libxkbcommon with the platform's suffix, such as libxkbcommon.dylib.

Mixing the layers

The idiomatic layer offers no way to get at its objects' foreign pointers. Use one layer or the other for a given object, not both.