kc3-lang/libxkbcommon/doc/user-configuration.md

Download

User-configuration

This page describes how to add a custom layout or option so that it will be parsed by libxkbcommon.

The below requires libxkbcommon as keymap compiler and does not work in X.

Data locations

libxkbcommon searches the following paths for XKB configuration files:

A keymap created with xkb_keymap_new_from_names() will look up those paths in order until the required data is found.

Note: Where libxkbcommon runs in a privileged context, only the system (datadir) path is available.

Each directory should have one or more of the following subdirectories:

RMLVO vs KcCGST

Due to how XKB is configured, there is no such thing as a “layout” in XKB itself, or, indeed, any of the rules, models, variant, options (RMLVO) decribed in struct xkb_rule_names. RMLVO names are merely lookup keys in the rules file provided by xkeyboard-config to map to the correct keycode, compat, geometry (ignored by libxkbcommon), symbols and types (KcCGST). The KcCGST data is the one used by XKB and libxbkcommon to map keys to actual symbols.

For example, a common RMLVO configuration is layout “us”, variant “dvorak” and option “terminate:ctrl_alt_bksp”. Using the default rules file and model this maps into the following KcCGST components:

xkb_keymap {
    xkb_keycodes  { include "evdev+aliases(qwerty)" };
    xkb_types     { include "complete"  };
    xkb_compat    { include "complete"  };
    xkb_symbols   { include "pc+us(dvorak)+inet(evdev)+terminate(ctrl_alt_bksp)"    };
    xkb_geometry  { include "pc(pc105)" };
};

A detailed explanation of how rules files convert RMLVO to KcCGST is out of scope for this document. See the rules file page instead.

Adding a layout

Adding a layout requires that the user adds symbols in the correct location.

The default rules files (usually evdev) have a catch-all to map a layout, say “foo”, and a variant, say “bar”, into the “bar” section in the file $xkb_base_dir/symbols/foo. This is sufficient to define a new keyboard layout. The example below defines the keyboard layout “banana” with an optional variant “orange”

$ cat $XDG_CONFIG_HOME/xkb/symbols/banana
// Like a US layout but swap the top row so numbers are on Shift
default partial alphanumeric_keys
xkb_symbols "basic" {
    include "us(basic)"
    name[Group1]= "Banana (US)";

    key <AE01> { [ exclam,          1]     };
    key <AE02> { [ at,              2]     };
    key <AE03> { [ numbersign,      3]     };
    key <AE04> { [ dollar,          4]     };
    key <AE05> { [ percent,         5]     };
    key <AE06> { [ asciicircum,     6]     };
    key <AE07> { [ ampersand,       7]     };
    key <AE08> { [ asterisk,        8]     };
    key <AE09> { [ parenleft,       9]     };
    key <AE10> { [ parenright,      0]     };
    key <AE11> { [ underscore,      minus] };
    key <AE12> { [ plus,            equal] };
};

// Same as banana but map the euro sign to the 5 key
partial alphanumeric_keys
xkb_symbols "orange" {
    include "banana(basic)"
    name[Group1] = "Banana (Eurosign on 5)";
    include "eurosign(5)"
};

The default section is loaded when no variant is given. The first example sections uses include to populate with a symbols list defined elsewhere (here: section basic from the file symbols/us, aka. the default US keyboard layout) and overrides parts of these symbols. The effect of this section is to swap the numbers and symbols in the top-most row (compared to the US layout) but otherwise use the US layout.

The “orange” variant uses the “banana” symbols and includes a different section to define the eurosign. It does not specificially override any symbols.

The exact details of how xkb_symbols work is out of scope for this document.

Adding an option

For technical reasons, options do not have a catch-all to map option names to files and sections and must be specifically mapped by the user. This requires a custom rules file. As the evdev ruleset is hardcoded in many clients, the custom rules file must usually be named evdev.

$ cat $XDG_CONFIG_HOME/xkb/rules/evdev
! option = symbols
  custom:foo    = +custom(bar)
  custom:baz    = +other(baz)

! include %S/evdev

This rules file maps the RMLVO option “custom:foo” to the “bar” section in the symbols/custom file and the “custom:baz” option to the “baz” section in the symbols/other file. Note how the RMLVO option name may be different to the file or section name.

The include statement includes the system-provided evdev ruleset. This allows users to only override those options they need.

The files themselves are similar to the layout examples in the previous section:

$ cat $XDG_CONFIG_HOME/xkb/symbols/custom
// map the Tilde key to nothing on the first shift level
partial alphanumeric_keys
xkb_symbols "bar" {
    key <TLDE> {        [      VoidSymbol ]       };
};

$ cat $XDG_CONFIG_HOME/xkb/symbols/other
// map first key in bottom row (Z in the US layout) to k/K
partial alphanumeric_keys
xkb_symbols "baz" {
    key <AB01> {        [      k, K ]       };
};

With these in place, a user may select any layout/variant together with the “custom:foo” and/or “custom:baz” options.

Source

Download

kmx.io     mail     discord kmxgit v0.4.0