1056N/AHow to further enhance XKB configuration
1056N/AThis guide is aimed to relieve one's labour to create a new (internationalized)
1056N/Akeyboard layout. Unlike other documents this guide accents the keymap
1056N/A━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1056N/AThe developer of a new layout should read the xkb protocol specification (The X
1056N/AKeyboard Extension: Protocol Specification) at least to clarify for himself
1056N/Asome xkb-specific terms used in this document and elsewhere in xkb
1056N/Aconfiguration. Also it shows wise to understand how the X server and a client
1056N/Adigest their keyboard inputs (with and without xkb).
1056N/AA useful source is also Ivan Pascal's text about xkb configuration often
1056N/Areferenced throughout this document.
1056N/ANote that this document covers only enhancements which are to be made to
1056N/AXFree86 version 4.3 and X11R6.7.0 and above.
1056N/AAt the startup (or at later at user's command) X server starts its xkb keyboard
1056N/Amodule extension and reads data from a compiled configuration file.
1056N/AThis compiled configuration file is prepared by the program xkbcomp which
1056N/Abehaves altogether as an ordinary compiler (see man xkbcomp). Its input are
1056N/Ahuman readable xkb configuration files which are verified and then composed
1056N/Ainto a useful xkb configuration. Users don't need to mess with xkbcomp
1056N/Athemselves, for them it is invisible. Usually, it is started upon X server
1056N/AAs you probably already know, the xkb configuration consists of five main
1056N/A Tables that defines translation from keyboard scan codes into
1056N/A reasonable symbolic names, maximum, minimum legal keycodes, symbolic
1056N/A aliases and description of physically present LED-indicators. The
1056N/A primary sence of this component is to allow definitions of maps of
1056N/A symbols (see below) to be independent of physical keyboard scancodes.
1056N/A There are two main naming conventions for symbolic names (always four
1056N/A ● names which express some traditional meaning like <SPCE> (stands
1056N/A ● names which express some relative positioning on a keyboard, for
1056N/A example <AE01> (an exclamation mark on US keyboards), on the right
1056N/A there are keys <AE02>, <AE03> etc.
1056N/A Types describe how the produced key is changed by active modifiers
1056N/ATypes (like Shift, Control, Alt, ...). There are several predefined types
1056N/A which cover most of used combinations.
1056N/A Compatibility component defines internal behaviour of modifiers. Using
1276N/ACompat compat component you can assign various actions (elaborately described
1276N/A in xkb specification) to key events. This is also the place where
1056N/A LED-indicators behaviour is defined.
1056N/A For i18n purposes, this is the most important table. It defines what
1056N/A values (=symbols) are assigned to what keycodes (represented by their
1056N/ASymbols symbolic name, see above). There may be defined more than one value
1056N/A for each key and then it depends on a key type and on modifiers state
1056N/A (respective compat component) which value will be the resulting one.
1056N/AGeometry Geometry files aren't used by xkb itself but they may be used by some
1056N/A external programs to depict a keyboard image.
1056N/AAll these components have the files located in xkb configuration tree in
1056N/AMost of xkb enhancements concerns a need to define new output symbols for the
1056N/Asome input key events. In other words, a need to define a new symbol map (for a
1056N/Anew language, standard or just to feel more comfortable when typing text).
1056N/AWhat do you need to do? Generally, you have to define following things:
1056N/A ● the map of symbols itself
1056N/A ● the rules to allow users to select the new mapping
1056N/A ● the description of the new layout
1056N/AFirst of all, it is good to go through existing layouts and to examine them if
1056N/Athere is something you could easily adjust to fit your needs. Even if there is
1056N/Anothing similar you may get some ideas about basic concepts and used tricks.
1056N/ASince XFree86 4.3.0 and X11R6.7.0 you can use multi-layout concept of xkb
1056N/Aconfiguration. Though it is still in boundaries of xkb protocol and general
1056N/Aideas, the keymap designer must obey new rules when creating new maps. In
1056N/Aexchange we get a more powerful and cleaner configuration system.
1056N/ARemember that it is the application which must decide which symbol matches
1056N/Awhich keycode according to effective modifier state. The X server itself sends
1056N/Aonly an input event message to. Of course, usually the general interpretation
1056N/Ais processed by Xlib, Xaw, Motif, Qt, Gtk and similar libraries. The X server
1056N/Aonly supplies its mapping table (usually upon an application startup).
1056N/AYou can think of the X server's symbol table as of a irregular table where each
1056N/Akeycode has its row and where each combination of modifiers determines exactly
1056N/Aone column. The resulting cell then gives the proper symbolic value. Not all
1056N/Akeycodes need to bind different values for different combination of modifiers.
1056N/A<ENTER> key, for instance, usually doesn't depend on any modifiers so it its
1056N/Arow has only one column defined.
1056N/ANote that in XKB there is no prior assumption that certain modifiers are bound
1276N/Ato certain columns. By editing proper files (see Key Types) this mapping can be
1056N/AUnlike the original X protocol the XKB approach is far more flexible. It is
1056N/Acomfortable to add one additional XKB term - group. You can think of a group as
1056N/Aof a vector of columns per each keycode (naturally the dimension of this vector
1056N/Amay differ for different keycodes). What is it good for? The group is not very
1056N/Auseful unless you intend to use more than one logically different set of
1056N/Asymbols (like more than one alphabet) defined in a single mapping table. But
1056N/Athen, the group has a natural meaning - each symbol set has its own group and
1056N/Achanging it means selecting a different one. XKB approach allows up to four
1056N/Adifferent groups. The columns inside each group are called (shift) levels. The
1056N/AX server knows the current group and reports it together with modifier set and
1056N/Awith a keycode in key events.
1056N/A ● for each keycode XKB keyboard map contains up to four one-dimensional
1056N/A tables - groups (logically different symbol sets)
1056N/A ● for each group of a keycode XKB keyboard map contains some columns - shift
1056N/A levels (values reached by combinations of Shift, Ctrl, Alt, ... modifiers)
1056N/A ● different keycodes can have different number of groups
1056N/A ● different groups of one keycode can have different number of shift levels
1056N/A ● the current group number is tracked by X server
1056N/AIt is clear that if you sanely define levels, groups and sanely bind modifiers
1056N/Aand associated actions you can have simultaneously loaded up to four different
1056N/Asymbol sets where each of them would reside in its own group.
1056N/AThe multi-layout concept provides a facility to manipulate xkb groups and
1056N/Asymbol definitions in a way that allows almost arbitrary composition of
1056N/Apredefined symbol tables. To keep it fully functional you have to:
1056N/A ● define all symbols only in the first group
1056N/A ● (re)define any modifiers with extra care to avoid strange (anisometric)
1056N/ASee Some Words About XKB internals for explanation of used xkb terms and
1056N/Aproblems addressed by XKB extension.
1056N/ASee Common notes about XKB configuration files language for more precise
1056N/Aexplanation of syntax of xkb configuration files.
1056N/AIf you are about to define some European symbol map extension, you might want
1056N/Ato use on of four predefined latin alphabet layouts.
1056N/AOkay, let's assume you want extend an existing keymap and you want to override
1056N/Aa few keys. Let's take a simple
U.K. keyboard as an example (defined in
pc/gb):
1056N/Apartial default alphanumeric_keys
1056N/A name[Group1]="Great Britain";
1056N/A key <AE02> { [ 2, quotedbl, twosuperior, oneeighth ] };
1056N/A key <AE03> { [ 3, sterling, threesuperior, sterling ] };
1056N/A key <AC11> { [apostrophe, at, dead_circumflex, dead_caron] };
1056N/A key <TLDE> { [ grave, notsign, bar, bar ] };
1056N/A key <BKSL> { [numbersign, asciitilde, dead_grave, dead_breve ] };
1056N/A key <RALT> { type[Group1]="TWO_LEVEL",
1056N/A [ ISO_Level3_Shift, Multi_key ] };
1056N/A modifier_map Mod5 { <RALT> };
1056N/AIt defines a new layout in basic variant as an extension of common latin
1056N/Aalphabet layout. The layout (symbol set) name is set to "Great Britain". Then
1056N/Athere are redefinitions of a few keycodes and a modifiers binding. As you can
1056N/Asee the number of shift levels is the same for <AE02>, <AE03>, <AC11>, <TLDE>
1056N/Aand <BKSL> keys but it differs from number of shift levels of <RALT>.
1056N/ANote that the <RALT> key itself is a binding key for Mod5 and that it serves
1056N/Alike a shift modifier for LevelThree, together with Shift as a multi-key. It is
1056N/Aa good habit to respect this rule in a new similar layout.
1056N/AOkay, you could now define more variants of your new layout besides basic
1056N/Aaltering what may be needed.
1056N/AThe differences in the number of columns (shift levels) are caused by a
1056N/Adifferent types of keys (see the types definition in section basics). Most
1056N/Akeycodes have implicitly set the keytype in the included “
pc/latin” file to
1056N/A“FOUR_LEVEL_ALPHABETIC”. The only exception is <RALT> keycode which is
1056N/Aexplicitly set “TWO_LEVEL” keytype.
1056N/AAll those names refer to pre-defined shift level schemes. Usually you can
1056N/Achoose a suitable shift level scheme from default types scheme list in proper
1056N/Axkb component's subdirectory.
1276N/AONE_LEVEL The key does not depend on any modifiers. The symbol from
1276N/A first level is always chosen.
1056N/A The key uses a modifier Shift and may have two possible
1056N/A values. The second level may be chosen by Shift modifier.
1056N/A If Lock modifier (usually Caps-lock) applies the symbol
1056N/ATWO_LEVEL is further processed using system-specific capitalization
1056N/A rules. If both Shift+Lock modifier apply the symbol from
1056N/A the second level is taken and capitalization rules are
1056N/A applied (and usually have no effect).
1056N/A The key uses modifiers Shift and Lock. It may have two
1056N/A possible values. The second level may be chosen by Shift
1056N/A modifier. When Lock modifier applies, the symbol from the
1276N/AALPHABETIC first level is taken and further processed using
1276N/A system-specific capitalization rules. If both Shift+Lock
1056N/A modifier apply the symbol from the first level is taken
1056N/A and no capitalization rules applied. This is often called
1056N/A shift-cancels-caps behaviour.
1056N/A Is the same as TWO_LEVEL but it considers an extra
1056N/A modifier - LevelThree which can be used to gain the
1056N/A symbol value from the third level. If both
1056N/A Shift+LevelThree modifiers apply the value from the third
1056N/ATHREE_LEVEL level is also taken. As in TWO_LEVEL, the Lock modifier
1056N/A doesn't influence the resulting level. Only Shift and
1056N/A LevelThree are taken into that consideration. If the Lock
1056N/A modifier is active capitalization rules are applied on
1056N/A Is the same as THREE_LEVEL but unlike LEVEL_THREE if both
1056N/AFOUR_LEVEL Shift+LevelThree modifiers apply the symbol is taken from
1056N/A Is similar to FOUR_LEVEL but also defines
1056N/A shift-cancels-caps behaviour as in ALPHABETIC. If
1276N/AFOUR_LEVEL_ALPHABETIC Lock+LevelThree apply the symbol from the third level is
1276N/A taken and the capitalization rules are applied. If
1056N/A Lock+Shift+LevelThree apply the symbol from the third
1056N/A level is taken and no capitalization rules are applied.
1056N/A As the name suggest this scheme is primarily used for
1056N/A numeric keypads. The scheme considers two modifiers -
1056N/A Shift and NumLock. If none of modifiers applies the
1276N/AKEYPAD symbol from the first level is taken. If either Shift or
1276N/A NumLock modifiers apply the symbol from the second level
1056N/A is taken. If both Shift+NumLock modifiers apply the
1056N/A symbol from the first level is taken. Again,
1056N/A shift-cancels-caps variant.
1056N/A Is similar to KEYPAD scheme but considers also LevelThree
1056N/A modifier. If LevelThree modifier applies the symbol from
1056N/A the third level is taken. If Shift+LevelThree or
1056N/AFOUR_LEVEL_KEYPAD NumLock+LevelThree apply the symbol from the fourth level
1056N/A is taken. If all Shift+NumLock+LevelThree modifiers apply
1056N/A the symbol from the third level is taken. This also,
1056N/A shift-cancels-caps variant.
1056N/ABesides that, there are several schemes for special purposes:
1056N/A It is similar to TWO_LEVEL scheme but it considers the Control
1056N/APC_BREAK modifier rather than Shift. That means, the symbol from the second
1056N/A level is chosen by Control rather than by Shift.
1056N/A It is similar to TWO_LEVEL scheme but it considers the Alt modifier
1056N/APC_SYSRQ rather than Shift. That means, the symbol from the second level is
1056N/A chosen by Alt rather than by Shift.
1056N/A The key uses modifiers Alt and Control. It may have two possible
1276N/ACTRL+ALT values. If only one modifier (Alt or Control) applies the symbol from
1276N/A the first level is chosen. Only if both Alt+Control modifiers apply
1056N/A the symbol from the second level is chosen.
1056N/A The key uses modifiers Shift and Alt. It may have two possible
1056N/ASHIFT+ALT values. If only one modifier (Alt or Shift) applies the symbol from
1056N/A the first level is chosen. Only if both Alt+Shift modifiers apply the
1056N/A symbol from the second level is chosen.
1056N/AIf needed, special caps schemes may be used. They redefine the standard
1056N/Abehaviour of all *ALPHABETIC types. The layouts (maps of symbols) with keys
1056N/Adefined in respective types then automatically change their behaviour
1056N/Aaccordingly. Possible redefinitions are:
1056N/ANone of these schemes should be used directly. They are defined merely for
1056N/A'caps:' xkb options (used to globally change the layouts behaviour).
1056N/ADon't alter any of existing key types. If you need a different behaviour create
1056N/AMore On Definitions Of Types
1056N/AWhen the XKB software deals with a separate type description it gets a complete
1056N/Alist of modifiers that should be taken into account from the 'modifiers=<list
1056N/Aof modifiers>' list and expects that a set of 'map[<combination of modifiers>]=
1056N/A<list of modifiers>' instructions that contain the mapping for each combination
1056N/Aof modifiers mentioned in that list. Modifiers that are not explicitly listed
1056N/Aare NOT taken into account when the resulting shift level is computed. If some
1056N/Acombination is omitted the program (subroutine) should choose the first level
1056N/Afor this combination (a quite reasonable behavior).
1056N/ALets consider an example with two modifiers ModOne and ModTwo:
1056N/AIn this case the map statements for ModTwo only and ModOne+ModTwo are omitted.
1056N/AIt means that if the ModTwo is active the subroutine can't found explicit
1056N/Amapping for such combination an will use the default level
i.e. Level1.
1056N/ABut in the case the type described as:
1056N/Athe ModTwo will not be taken into account and the resulting level depends on
1056N/Athe ModOne state only. That means, ModTwo alone produces the Level1 but the
1056N/Acombination ModOne+ModTwo produces the Level2 as well as ModOne alone.
1056N/AWhat does it mean if the second modifier is the Lock? It means that in the
1056N/Afirst case (the Lock itself is included in the list of modifiers but
1056N/Acombinations with this modifier aren't mentioned in the map statements) the
1056N/Ainternal capitalization rules will be applied to the symbol from the first
1056N/Alevel. But in the second case the capitalization will be applied to the symbol
1056N/Achosen accordingly to he first modifier - and this can be the symbol from the
1056N/Afirst as well as from the second level.
1056N/AUsually, all modifiers introduced in 'modifiers=<list of modifiers>' list are
1056N/Aused for shift level calculation and then discarded. Sometimes this is not
1056N/Adesirable. If you want to use a modifier for shift level calculation but you
1056N/Adon't want to discard it, you may list in 'preserve[<combination of modifiers>]
1056N/A=<list of modifiers>'. That means, for a given combination all listed modifiers
1056N/Awill be preserved. If the Lock modifier is preserved then the resulting symbol
1056N/Ais passed to internal capitalization routine regardless whether it has been
1056N/Aused for a shift level calculation or not.
1056N/AAny key type description can use both real and virtual modifiers. Since real
1056N/Amodifiers always have standard names it is not necessary to explicitly declare
1056N/Athem. Virtual modifiers can have arbitrary names and can be declared (prior
1056N/Ausing them) directly in key type definition:
1056N/Avirtual_modifiers <comma-separated list of modifiers> ;
1056N/Aas seen in for example basic, pc or mousekeys key type definitions.
1056N/AOnce you are finished with your symbol map you need to add it to rules file.
1056N/AThe rules file describes how all the five basic keycodes, types, compat,
1056N/Asymbols and geometry components should be composed to give a sensible resulting
1056N/AThe main advantage of rules over formerly used keymaps is a possibility to
1056N/Asimply parameterize (once) fixed patterns of configurations and thus to
1056N/Aelegantly allow substitutions of various local configurations into predefined
1056N/Aparameterized with four other arguments: Model, Layout, Variant and Options.
1056N/AFor most cases parameters model and layout should be sufficient for choosing a
1056N/Afunctional keyboard mapping.
1056N/AThe rules file itself is composed of pattern lines and lines with rules. The
1056N/Apattern line starts with an exclamation mark ('!') and describes how will the
1056N/Axkb interpret the following lines (rules). A sample rules file looks like this:
1056N/A caps:internal = +caps(internal)
1056N/A caps:internal_nocancel = +caps(internal_nocancel)
1056N/AEach rule defines what certain combination of values on the left side of equal
1056N/Asign ('=') results in. For example a (keyboard) model macintosh_old instructs
1056N/Aof models (represented by a wild card '*') instructs it to take them from file
1056N/Awhich were not found in any of the previous rules. The more specialized (more
1056N/Acomplete) rules have higher precedence than general ones,
i.e. the more general
1056N/Arules supply reasonable default values.
1056N/AAs you can see some lines contain substitution parameters - the parameters
1056N/Apreceded by the percent sign ('%'). The first alphabetical character after the
1056N/Apercent sign expands to the value which has been found on the left side. For
1056N/Aexample +%l%(v) expands into +cz(bksl) if the respective values on the left
1056N/Aside were cz layout in its bksl variant. More, if the layout resp. variant
1056N/Aparameter is followed by a pair of brackets ('[', ']') it means that xkb should
1056N/Aplace the layout resp. variant into specified xkb group. If the brackets are
1056N/Aomitted the first group is the default value.
1056N/ASo the second block of rules enhances symbol definitions for some particular
1056N/Akeyboard models with extra keys (for internet, multimedia, ...) . Other models
1056N/Aare left intact. Similarly, the last block overrides some key type definitions,
1056N/Aso the common global behaviour ''shift cancels caps'' or ''shift doesn't cancel
1056N/Acaps'' can be selected. The rest of rules produces special symbols for each
1056N/Avariant us layout of macintosh keyboard and standard pc symbols in appropriate
1056N/ANow you just need to add a detailed description to <rules>.xml description file
1056N/Aso the other users (and external programs which often parse this file) know
1056N/AThe formerly used descriptive files were named <rules>.lst Its structure is
1056N/Avery simple and quite self descriptive but such simplicity had also some
1056N/Acavities, for example there was no way how to describe local variants of
1056N/Alayouts and there were problems with the localization of descriptions. To
1056N/Apreserve compatibility with some older programs, new XML descriptive files can
1056N/Abe converted to old format '.lst'.
1056N/AFor each parameter of rules file should be described its meaning. For the rules
1056N/Afile described above the .lst file could look like:
1056N/A microsoft Microsoft Natural
1056N/A macintosh Original Macintosh
1056N/A caps:internal uses internal capitalization. Shift cancels Caps
1056N/A caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps
1056N/AAnd that should be it. Enjoy creating your own xkb mapping.