How to further enhance XKB configuration : Defining New Layouts
Previous: Enhancing XKB Configuration
Next: How to further enhance XKB configuration

## 4. Defining New Layouts

See Some Words About XKB internals for explanation of used xkb terms and problems addressed by XKB extension.

See Common notes about XKB configuration files language for more precise explanation of syntax of xkb configuration files.

### 4.1. Predefined XKB Symbol Sets

If you are about to define some European symbol map extension, you might want to use on of four predefined latin alphabet layouts.

Okay, let's assume you want extend an existing keymap and you want to override a few keys. Let's take a simple U.K. keyboard as an example (defined in `pc/gb`):

> `

>     partial default alphanumeric_keys
>     xkb_symbols "basic" {
>       include "pc/latin"

>       name[Group1]="Great Britain";

>       key <AE02>  { [         2,   quotedbl,  twosuperior,    oneeighth ] };
>       key <AE03>  { [         3,   sterling, threesuperior,    sterling ] };
>       key <AC11>  { [apostrophe,         at, dead_circumflex, dead_caron] };
>       key <TLDE>  { [     grave,    notsign,          bar,          bar ] };
>       key <BKSL>  { [numbersign, asciitilde,   dead_grave,   dead_breve ] };
>       key <RALT>  { type[Group1]="TWO_LEVEL",
>                     [ ISO_Level3_Shift, Multi_key ]   };

>       modifier_map Mod5   { <RALT> };
>     };

> `

It defines a new layout in `basic` variant as an extension of common latin alphabet layout. The layout (symbol set) name is set to "Great Britain". Then there are redefinitions of a few keycodes and a modifiers binding. As you can see the number of shift levels is the same for `<AE02>`, `<AE03>`, `<AC11>`, `<TLDE>` and `<BKSL>` keys but it differs from number of shift levels of `<RALT>`.

Note that the `<RALT>` key itself is a binding key for Mod5 and that it serves like a shift modifier for LevelThree, together with Shift as a multi-key. It is a good habit to respect this rule in a new similar layout.

Okay, you could now define more variants of your new layout besides `basic` simply by including (augmenting/overriding/...) the basic definition and altering what may be needed.

### 4.2. Key Types

The differences in the number of columns (shift levels) are caused by a different types of keys (see the types definition in section basics). Most keycodes have implicitly set the keytype in the included `"pc/latin"` file to `"FOUR_LEVEL_ALPHABETIC"`. The only exception is `<RALT>` keycode which is explicitly set `"TWO_LEVEL"` keytype.

All those names refer to pre-defined shift level schemes. Usually you can choose a suitable shift level scheme from `default` types scheme list in proper xkb component's subdirectory.

The most used schemes are:

ONE_LEVEL

  The key does not depend on any modifiers. The symbol from first level is always chosen.

TWO_LEVEL

  The key uses a modifier Shift and may have two possible values. The second level may be chosen by Shift modifier. If Lock modifier (usually Caps-lock) applies the symbol is further processed using system-specific capitalization rules. If both Shift+Lock modifier apply the symbol from the second level is taken and capitalization rules are applied (and usually have no effect).

ALPHABETIC

  The key uses modifiers Shift and Lock. It may have two possible values. The second level may be chosen by Shift modifier. When Lock modifier applies, the symbol from the first level is taken and further processed using system-specific capitalization rules. If both Shift+Lock modifier apply the symbol from the first level is taken and no capitalization rules applied. This is often called shift-cancels-caps behaviour.

THREE_LEVEL

  Is the same as TWO_LEVEL but it considers an extra modifier - LevelThree which can be used to gain the symbol value from the third level. If both Shift+LevelThree modifiers apply the value from the third level is also taken. As in TWO_LEVEL, the Lock modifier doesn't influence the resulting level. Only Shift and LevelThree are taken into that consideration. If the Lock modifier is active capitalization rules are applied on the resulting symbol.

FOUR_LEVEL

  Is the same as THREE_LEVEL but unlike LEVEL_THREE if both Shift+LevelThree modifiers apply the symbol is taken from the fourth level.

FOUR_LEVEL_ALPHABETIC

  Is similar to FOUR_LEVEL but also defines shift-cancels-caps behaviour as in ALPHABETIC. If Lock+LevelThree apply the symbol from the third level is taken and the capitalization rules are applied. If Lock+Shift+LevelThree apply the symbol from the third level is taken and no capitalization rules are applied.

KEYPAD

  As the name suggest this scheme is primarily used for numeric keypads. The scheme considers two modifiers - Shift and NumLock. If none of modifiers applies the symbol from the first level is taken. If either Shift or NumLock modifiers apply the symbol from the second level is taken. If both Shift+NumLock modifiers apply the symbol from the first level is taken. Again, shift-cancels-caps variant.

FOUR_LEVEL_KEYPAD

  Is similar to KEYPAD scheme but considers also LevelThree modifier. If LevelThree modifier applies the symbol from the third level is taken. If Shift+LevelThree or NumLock+LevelThree apply the symbol from the fourth level is taken. If all Shift+NumLock+LevelThree modifiers apply the symbol from the third level is taken. This also, shift-cancels-caps variant.

Besides that, there are several schemes for special purposes:

PC_BREAK

  It is similar to TWO_LEVEL scheme but it considers the Control modifier rather than Shift. That means, the symbol from the second level is chosen by Control rather than by Shift.

PC_SYSRQ

  It is similar to TWO_LEVEL scheme but it considers the Alt modifier rather than Shift. That means, the symbol from the second level is chosen by Alt rather than by Shift.

CTRL+ALT

  The key uses modifiers Alt and Control. It may have two possible values. If only one modifier (Alt or Control) applies the symbol from the first level is chosen. Only if both Alt+Control modifiers apply the symbol from the second level is chosen.

SHIFT+ALT

  The key uses modifiers Shift and Alt. It may have two possible values. If only one modifier (Alt or Shift) applies the symbol from the first level is chosen. Only if both Alt+Shift modifiers apply the symbol from the second level is chosen.

If needed, special `caps` schemes may be used. They redefine the standard behaviour of all `*ALPHABETIC` types. The layouts (maps of symbols) with keys defined in respective types then automatically change their behaviour accordingly. Possible redefinitions are:

- internal
- internal_nocancel
- shift
- shift_nocancel

None of these schemes should be used directly. They are defined merely for `'caps:'` xkb options (used to globally change the layouts behaviour).

Don't alter any of existing key types. If you need a different behaviour create a new one.

#### 4.2.1. More On Definitions Of Types

When the XKB software deals with a separate type description it gets a complete list of modifiers that should be taken into account from the `'modifiers=<list of modifiers>'` list and expects that a set of `'map[<combination of modifiers>]=<list of modifiers>'` instructions that contain the mapping for each combination of modifiers mentioned in that list. Modifiers that are not explicitly listed are NOT taken into account when the resulting shift level is computed. If some combination is omitted the program (subroutine) should choose the first level for this combination (a quite reasonable behavior).

Lets consider an example with two modifiers `ModOne` and `ModTwo`:

> `

>     type "..." {
>         modifiers = ModOne+ModTwo;
>         map[None] = Level1;
>         map[ModOne] = Level2;
>     };

> `

In this case the map statements for `ModTwo` only and `ModOne+ModTwo` are omitted. It means that if the `ModTwo` is active the subroutine can't found explicit mapping for such combination an will use the default level i.e. Level1.

But in the case the type described as:

> `

>     type "..." {
>         modifiers = ModOne;
>         map[None] = Level1;
>         map[ModOne] = Level2;
>     };

> `

the ModTwo will not be taken into account and the resulting level depends on the ModOne state only. That means, ModTwo alone produces the Level1 but the combination ModOne+ModTwo produces the Level2 as well as ModOne alone.

What does it mean if the second modifier is the Lock? It means that in the first case (the Lock itself is included in the list of modifiers but combinations with this modifier aren't mentioned in the map statements) the internal capitalization rules will be applied to the symbol from the first level. But in the second case the capitalization will be applied to the symbol chosen accordingly to he first modifier - and this can be the symbol from the first as well as from the second level.

Usually, all modifiers introduced in `'modifiers=<list of modifiers>'` list are used for shift level calculation and then discarded. Sometimes this is not desirable. If you want to use a modifier for shift level calculation but you don't want to discard it, you may list in '`preserve[<combination of modifiers>]=<list of modifiers>'`. That means, for a given combination all listed modifiers will be preserved. If the Lock modifier is preserved then the resulting symbol is passed to internal capitalization routine regardless whether it has been used for a shift level calculation or not.

Any key type description can use both real and virtual modifiers. Since real modifiers always have standard names it is not necessary to explicitly declare them. Virtual modifiers can have arbitrary names and can be declared (prior using them) directly in key type definition:

> `

>     virtual_modifiers <comma-separated list of modifiers>  ;

> `

as seen in for example `basic`, `pc` or `mousekeys` key type definitions.

### 4.3. Rules

Once you are finished with your symbol map you need to add it to rules file. The rules file describes how all the five basic keycodes, types, compat, symbols and geometry components should be composed to give a sensible resulting xkb configuration.

The main advantage of rules over formerly used keymaps is a possibility to simply parameterize (once) fixed patterns of configurations and thus to elegantly allow substitutions of various local configurations into predefined templates.

A pattern in a rules file (often located in `/usr/lib/X11/xkb/rules`) can be parameterized with four other arguments: `Model`, `Layout`, `Variant` and `Options`. For most cases parameters `model` and `layout` should be sufficient for choosing a functional keyboard mapping.

The rules file itself is composed of pattern lines and lines with rules. The pattern line starts with an exclamation mark ('`!`') and describes how will the xkb interpret the following lines (rules). A sample rules file looks like this:

> `

>     ! model 	                =	keycodes
>       macintosh_old	                =	macintosh
>       ...
>       *		                =	xfree86

>     ! model		                =	symbols
>       hp		                =	+inet(%m)
>       microsoftpro	                =	+inet(%m)
>       geniuscomfy	                =	+inet(%m)

>     ! model	    layout[1]	        =	symbols
>       macintosh	us	        =	macintosh/us%(v[1])
>       *             *               =       pc/pc(%m)+pc/%l[1]%(v[1])

>     ! model     layout[2]	        =	symbols
>       macintosh     us              =	+macintosh/us[2]%(v[2]):2
>       *		*               =	+pc/%l[2]%(v[2]):2

>     ! option			=	types
>       caps:internal			=	+caps(internal)
>       caps:internal_nocancel	=	+caps(internal_nocancel)

> `

Each rule defines what certain combination of values on the left side of equal sign ('`=`') results in. For example a (keyboard) model `macintosh_old` instructs xkb to take definitions of keycodes from file `keycodes/macintosh` while the rest of models (represented by a wild card '`*`') instructs it to take them from file `keycodes/xfree86`. The wild card represents all possible values on the left side which were not found in any of the previous rules. The more specialized (more complete) rules have higher precedence than general ones, i.e. the more general rules supply reasonable default values.

As you can see some lines contain substitution parameters - the parameters preceded by the percent sign ('`%`'). The first alphabetical character after the percent sign expands to the value which has been found on the left side. For example `+%l%(v)` expands into `+cz(bksl)` if the respective values on the left side were `cz` layout in its `bksl` variant. More, if the layout resp. variant parameter is followed by a pair of brackets ('`[`', '`]`') it means that xkb should place the layout resp. variant into specified xkb group. If the brackets are omitted the first group is the default value.

So the second block of rules enhances symbol definitions for some particular keyboard models with extra keys (for internet, multimedia, ...) . Other models are left intact. Similarly, the last block overrides some key type definitions, so the common global behaviour ''shift cancels caps'' or ''shift doesn't cancel caps'' can be selected. The rest of rules produces special symbols for each variant `us` layout of `macintosh` keyboard and standard pc symbols in appropriate variants as a default.

### 4.4. Descriptive Files of Rules

Now you just need to add a detailed description to `<rules>.xml` description file so the other users (and external programs which often parse this file) know what is your work about.

#### 4.4.1. Old Descriptive Files

The formerly used descriptive files were named `<rules>.lst` Its structure is very simple and quite self descriptive but such simplicity had also some cavities, for example there was no way how to describe local variants of layouts and there were problems with the localization of descriptions. To preserve compatibility with some older programs, new XML descriptive files can be converted to old format '.lst'.

For each parameter of rules file should be described its meaning. For the rules file described above the `.lst` file could look like:

> `

>     ! model
>       pc104		Generic 104-key PC
>       microsoft	Microsoft Natural
>       pc98		PC-98xx Series
>       macintosh     Original Macintosh
>       ...

>     ! layout
>       us		U.S. English
>       cz		Czech
>       de		German
>       ...

>     ! option
>       caps:internal		 uses internal capitalization. Shift cancels Caps
>       caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps

> `

And that should be it. Enjoy creating your own xkb mapping.

How to further enhance XKB configuration : Defining New Layouts
Previous: Enhancing XKB Configuration
Next: How to further enhance XKB configuration