1 How to further enhance XKB configuration
3 Kamil Toman, Ivan U. Pascal
9 This guide is aimed to relieve one's labour to create a new (inter-
10 nationalized) keyboard layout. Unlike other documents this guide
11 accents the keymap developer's point of view.
15 The developer of a new layout should read the xkb protocol specification (The
16 X Keyboard Extension: Protocol Specification <URL:http://www.x-
17 docs.org/XKB/XKBproto.pdf>) at least to clarify for himself some xkb-specific
18 terms used in this document and elsewhere in xkb configuration. Also it shows
19 wise to understand how the X server and a client digest their keyboard inputs
20 (with and without xkb).
22 A useful source is also Ivan Pascal's text about xkb configuration
23 <URL:http://www.tsu.ru/~pascal/en/xkb> often referenced throughout this docu-
26 Note that this document covers only enhancements which are to be made to
27 XFree86 version 4.3.x and above.
31 At the startup (or at later at user's command) X server starts its xkb key-
32 board module extension and reads data from a compiled configuration file.
34 This compiled configuration file is prepared by the program xkbcomp which
35 behaves altogether as an ordinary compiler (see man xkbcomp). Its input are
36 human readable xkb configuration files which are verified and then composed
37 into a useful xkb configuration. Users don't need to mess with xkbcomp them-
38 selves, for them it is invisible. Usually, it is started upon X server
41 As you probably already know, the xkb configuration consists of five main
45 Tables that defines translation from keyboard scan codes into
46 reasonable symbolic names, maximum, minimum legal keycodes, sym-
47 bolic aliases and description of physically present LED-indica-
48 tors. The primary sence of this component is to allow definitions
49 of maps of symbols (see below) to be independent of physical key-
50 board scancodes. There are two main naming conventions for sym-
51 bolic names (always four bytes long):
53 o names which express some traditional meaning like <SPCE>
54 (stands for space bar) or
56 o names which express some relative positioning on a key-
57 board, for example <AE01> (an exclamation mark on US key-
58 boards), on the right there are keys <AE02>, <AE03> etc.
61 Types describe how the produced key is changed by active modi-
62 fiers (like Shift, Control, Alt, ...). There are several prede-
63 fined types which cover most of used combinations.
66 Compatibility component defines internal behaviour of modifiers.
67 Using compat component you can assign various actions (elabo-
68 rately described in xkb specification) to key events. This is
69 also the place where LED-indicators behaviour is defined.
72 For i18n purposes, this is the most important table. It defines
73 what values (=symbols) are assigned to what keycodes (represented
74 by their symbolic name, see above). There may be defined more
75 than one value for each key and then it depends on a key type and
76 on modifiers state (respective compat component) which value will
80 Geometry files aren't used by xkb itself but they may be used by
81 some external programs to depict a keyboard image.
83 All these components have the files located in xkb configuration tree in sub-
84 directories with the same names (usually in /usr/lib/X11/xkb).
86 3. Enhancing XKB Configuration
88 Most of xkb enhancements concerns a need to define new output symbols for the
89 some input key events. In other words, a need to define a new symbol map (for
90 a new language, standard or just to feel more comfortable when typing text).
92 What do you need to do? Generally, you have to define following things:
94 o the map of symbols itself
96 o the rules to allow users to select the new mapping
98 o the description of the new layout
100 First of all, it is good to go through existing layouts and to examine them
101 if there is something you could easily adjust to fit your needs. Even if
102 there is nothing similar you may get some ideas about basic concepts and used
105 3.1 Levels And Groups
107 Since XFree86 4.3.0 you can use multi-layout concept of xkb configuration.
108 Though it is still in boundaries of xkb protocol and general ideas, the
109 keymap designer must obey new rules when creating new maps. In exchange we
110 get a more powerful and cleaner configuration system.
112 Remember that it is the application which must decide which symbol matches
113 which keycode according to effective modifier state. The X server itself
114 sends only an input event message to. Of course, usually the general inter-
115 pretation is processed by Xlib, Xaw, Motif, Qt, Gtk and similar libraries.
116 The X server only supplies its mapping table (usually upon an application
119 You can think of the X server's symbol table as of a irregular table where
120 each keycode has its row and where each combination of modifiers determines
121 exactly one column. The resulting cell then gives the proper symbolic value.
122 Not all keycodes need to bind different values for different combination of
123 modifiers. <ENTER> key, for instance, usually doesn't depend on any modi-
124 fiers so it its row has only one column defined.
126 Note that in XKB there is no prior assumption that certain modifiers are
127 bound to certain columns. By editing proper files (see keytypes (section 4.2,
128 page 1)) this mapping can be changed as well.
130 Unlike the original X protocol the XKB approach is far more flexible. It is
131 comfortable to add one additional XKB term - group. You can think of a group
132 as of a vector of columns per each keycode (naturally the dimension of this
133 vector may differ for different keycodes). What is it good for? The group is
134 not very useful unless you intend to use more than one logically different
135 set of symbols (like more than one alphabet) defined in a single mapping ta-
136 ble. But then, the group has a natural meaning - each symbol set has its own
137 group and changing it means selecting a different one. XKB approach allows
138 up to four different groups. The columns inside each group are called (shift)
139 levels. The X server knows the current group and reports it together with
140 modifier set and with a keycode in key events.
144 o for each keycode XKB keyboard map contains up to four one-dimensional
145 tables - groups (logically different symbol sets)
147 o for each group of a keycode XKB keyboard map contains some columns -
148 shift levels (values reached by combinations of Shift, Ctrl, Alt, ...
151 o different keycodes can have different number of groups
153 o different groups of one keycode can have different number of shift lev-
156 o the current group number is tracked by X server
158 It is clear that if you sanely define levels, groups and sanely bind modi-
159 fiers and associated actions you can have simultaneously loaded up to four
160 different symbol sets where each of them would reside in its own group.
162 The multi-layout concept provides a facility to manipulate xkb groups and
163 symbol definitions in a way that allows almost arbitrary composition of pre-
164 defined symbol tables. To keep it fully functional you have to:
166 o define all symbols only in the first group
168 o (re)define any modifiers with extra care to avoid strange (anisometric)
171 4. Defining New Layouts
173 See Some Words About XKB internals <URL:http://www.tsu.ru/~pas-
174 cal/en/xkb/internals.html> for explanation of used xkb terms and problems
175 addressed by XKB extension.
177 See Common notes about XKB configuration files language
178 <URL:http://www.tsu.ru/~pascal/en/xkb/gram-common.html> for more precise
179 explanation of syntax of xkb configuration files.
181 4.1 Predefined XKB Symbol Sets
183 If you are about to define some European symbol map extension, you might want
184 to use on of four predefined latin alphabet layouts.
186 Okay, let's assume you want extend an existing keymap and you want to over-
187 ride a few keys. Let's take a simple U.K. keyboard as an example (defined in
190 partial default alphanumeric_keys
191 xkb_symbols "basic" {
194 name[Group1]="Great Britain";
196 key <AE02> { [ 2, quotedbl, twosuperior, oneeighth ] };
197 key <AE03> { [ 3, sterling, threesuperior, sterling ] };
198 key <AC11> { [apostrophe, at, dead_circumflex, dead_caron] };
199 key <TLDE> { [ grave, notsign, bar, bar ] };
200 key <BKSL> { [numbersign, asciitilde, dead_grave, dead_breve ] };
201 key <RALT> { type[Group1]="TWO_LEVEL",
202 [ ISO_Level3_Shift, Multi_key ] };
204 modifier_map Mod5 { <RALT> };
207 It defines a new layout in basic variant as an extension of common latin
208 alphabet layout. The layout (symbol set) name is set to "Great Britain".
209 Then there are redefinitions of a few keycodes and a modifiers binding. As
210 you can see the number of shift levels is the same for <AE02>, <AE03>,
211 <AC11>, <TLDE> and <BKSL> keys but it differs from number of shift levels of
214 Note that the <RALT> key itself is a binding key for Mod5 and that it serves
215 like a shift modifier for LevelThree, together with Shift as a multi-key. It
216 is a good habit to respect this rule in a new similar layout.
218 Okay, you could now define more variants of your new layout besides basic
219 simply by including (augmenting/overriding/...) the basic definition and
220 altering what may be needed.
224 The differences in the number of columns (shift levels) are caused by a dif-
225 ferent types of keys (see the types definition in section basics). Most key-
226 codes have implicitly set the keytype in the included "pc/latin" file to
227 "FOUR_LEVEL_ALPHABETIC". The only exception is <RALT> keycode which is
228 explicitly set "TWO_LEVEL" keytype.
230 All those names refer to pre-defined shift level schemes. Usually you can
231 choose a suitable shift level scheme from default types scheme list in proper
232 xkb component's subdirectory.
234 The most used schemes are:
237 The key does not depend on any modifiers. The symbol from first
238 level is always chosen.
241 The key uses a modifier Shift and may have two possible values.
242 The second level may be chosen by Shift modifier. If Lock modi-
243 fier (usually Caps-lock) applies the symbol is further processed
244 using system-specific capitalization rules. If both Shift+Lock
245 modifier apply the symbol from the second level is taken and cap-
246 italization rules are applied (and usually have no effect).
249 The key uses modifiers Shift and Lock. It may have two possible
250 values. The second level may be chosen by Shift modifier. When
251 Lock modifier applies, the symbol from the first level is taken
252 and further processed using system-specific capitalization rules.
253 If both Shift+Lock modifier apply the symbol from the first level
254 is taken and no capitalization rules applied. This is often
255 called shift-cancels-caps behaviour.
258 Is the same as TWO_LEVEL but it considers an extra modifier -
259 LevelThree which can be used to gain the symbol value from the
260 third level. If both Shift+LevelThree modifiers apply the value
261 from the third level is also taken. As in TWO_LEVEL, the Lock
262 modifier doesn't influence the resulting level. Only Shift and
263 LevelThree are taken into that consideration. If the Lock modi-
264 fier is active capitalization rules are applied on the resulting
268 Is the same as THREE_LEVEL but unlike LEVEL_THREE if both
269 Shift+LevelThree modifiers apply the symbol is taken from the
272 FOUR_LEVEL_ALPHABETIC
273 Is similar to FOUR_LEVEL but also defines shift-cancels-caps
274 behaviour as in ALPHABETIC. If Lock+LevelThree apply the symbol
275 from the third level is taken and the capitalization rules are
276 applied. If Lock+Shift+LevelThree apply the symbol from the
277 third level is taken and no capitalization rules are applied.
280 As the name suggest this scheme is primarily used for numeric
281 keypads. The scheme considers two modifiers - Shift and NumLock.
282 If none of modifiers applies the symbol from the first level is
283 taken. If either Shift or NumLock modifiers apply the symbol from
284 the second level is taken. If both Shift+NumLock modifiers apply
285 the symbol from the first level is taken. Again, shift-cancels-
289 Is similar to KEYPAD scheme but considers also LevelThree modi-
290 fier. If LevelThree modifier applies the symbol from the third
291 level is taken. If Shift+LevelThree or NumLock+LevelThree apply
292 the symbol from the fourth level is taken. If all Shift+Num-
293 Lock+LevelThree modifiers apply the symbol from the third level
294 is taken. This also, shift-cancels-caps variant.
296 FOUR_LEVEL_MIXED_KEYPAD
297 A four-level keypad scheme where the first two levels are similar
298 to the KEYPAD scheme (NumLock+Shift)
299 LevelThree acts as an override providing access to two Shift-ed
300 levels. When LevelThree is active we totally ignore NumLock state
301 Intended for the digit area of the keypad
304 A four-level scheme where the base level accepts no modifier,
305 LevelThree provides two more Shift-ed levels like in the previous
306 scheme, and Ctrl+Alt controls the fourth level
307 Intended for the operator part of a keypad, though since NumLock
308 plays no part, it is not keypad-specific
310 Besides that, there are several schemes for special purposes:
313 It is similar to TWO_LEVEL scheme but it considers the Control
314 modifier rather than Shift. That means, the symbol from the sec-
315 ond level is chosen by Control rather than by Shift.
318 It is similar to TWO_LEVEL scheme but it considers the Alt modi-
319 fier rather than Shift. That means, the symbol from the second
320 level is chosen by Alt rather than by Shift.
323 The key uses modifiers Alt and Control. It may have two possible
324 values. If only one modifier (Alt or Control) applies the symbol
325 from the first level is chosen. Only if both Alt+Control modi-
326 fiers apply the symbol from the second level is chosen.
329 The key uses modifiers Shift and Alt. It may have two possible
330 values. If only one modifier (Alt or Shift) applies the symbol
331 from the first level is chosen. Only if both Alt+Shift modifiers
332 apply the symbol from the second level is chosen.
334 If needed, special caps schemes may be used. They redefine the standard
335 behaviour of all *ALPHABETIC types. The layouts (maps of symbols) with keys
336 defined in respective types then automatically change their behaviour accord-
337 ingly. Possible redefinitions are:
347 None of these schemes should be used directly. They are defined merely for
348 'caps:' xkb options (used to globally change the layouts behaviour).
350 Don't alter any of existing key types. If you need a different behaviour cre-
353 4.2.1 More On Definitions Of Types
355 When the XKB software deals with a separate type description it gets a com-
356 plete list of modifiers that should be taken into account from the 'modi-
357 fiers=<list of modifiers>' list and expects that a set of 'map[<combination
358 of modifiers>]=<list of modifiers>' instructions that contain the mapping for
359 each combination of modifiers mentioned in that list. Modifiers that are not
360 explicitly listed are NOT taken into account when the resulting shift level
361 is computed. If some combination is omitted the program (subroutine) should
362 choose the first level for this combination (a quite reasonable behavior).
364 Lets consider an example with two modifiers ModOne and ModTwo:
367 modifiers = ModOne+ModTwo;
369 map[ModOne] = Level2;
372 In this case the map statements for ModTwo only and ModOne+ModTwo are omit-
373 ted. It means that if the ModTwo is active the subroutine can't found
374 explicit mapping for such combination an will use the default level i.e.
377 But in the case the type described as:
382 map[ModOne] = Level2;
385 the ModTwo will not be taken into account and the resulting level depends on
386 the ModOne state only. That means, ModTwo alone produces the Level1 but the
387 combination ModOne+ModTwo produces the Level2 as well as ModOne alone.
389 What does it mean if the second modifier is the Lock? It means that in the
390 first case (the Lock itself is included in the list of modifiers but combina-
391 tions with this modifier aren't mentioned in the map statements) the internal
392 capitalization rules will be applied to the symbol from the first level. But
393 in the second case the capitalization will be applied to the symbol chosen
394 accordingly to he first modifier - and this can be the symbol from the first
395 as well as from the second level.
397 Usually, all modifiers introduced in 'modifiers=<list of modifiers>' list are
398 used for shift level calculation and then discarded. Sometimes this is not
399 desirable. If you want to use a modifier for shift level calculation but you
400 don't want to discard it, you may list in 'preserve[<combination of modi-
401 fiers>]=<list of modifiers>'. That means, for a given combination all listed
402 modifiers will be preserved. If the Lock modifier is preserved then the
403 resulting symbol is passed to internal capitalization routine regardless
404 whether it has been used for a shift level calculation or not.
406 Any key type description can use both real and virtual modifiers. Since real
407 modifiers always have standard names it is not necessary to explicitly
408 declare them. Virtual modifiers can have arbitrary names and can be declared
409 (prior using them) directly in key type definition:
411 virtual_modifiers <comma-separated list of modifiers> ;
413 as seen in for example basic, pc or mousekeys key type definitions.
417 Once you are finished with your symbol map you need to add it to rules file.
418 The rules file describes how all the five basic keycodes, types, compat, sym-
419 bols and geometry components should be composed to give a sensible resulting
422 The main advantage of rules over formerly used keymaps is a possibility to
423 simply parameterize (once) fixed patterns of configurations and thus to ele-
424 gantly allow substitutions of various local configurations into predefined
427 A pattern in a rules file (often located in /usr/lib/X11/xkb/rules) can be
428 parameterized with four other arguments: Model, Layout, Variant and Options.
429 For most cases parameters model and layout should be sufficient for choosing
430 a functional keyboard mapping.
432 The rules file itself is composed of pattern lines and lines with rules. The
433 pattern line starts with an exclamation mark ('!') and describes how will the
434 xkb interpret the following lines (rules). A sample rules file looks like
438 macintosh_old = macintosh
444 microsoftpro = +inet(%m)
445 geniuscomfy = +inet(%m)
447 ! model layout[1] = symbols
448 macintosh us = macintosh/us%(v[1])
449 * * = pc/pc(%m)+pc/%l[1]%(v[1])
451 ! model layout[2] = symbols
452 macintosh us = +macintosh/us[2]%(v[2]):2
453 * * = +pc/%l[2]%(v[2]):2
456 caps:internal = +caps(internal)
457 caps:internal_nocancel = +caps(internal_nocancel)
459 Each rule defines what certain combination of values on the left side of
460 equal sign ('=') results in. For example a (keyboard) model macintosh_old
461 instructs xkb to take definitions of keycodes from file keycodes/macintosh
462 while the rest of models (represented by a wild card '*') instructs it to
463 take them from file keycodes/xfree86. The wild card represents all possible
464 values on the left side which were not found in any of the previous rules.
465 The more specialized (more complete) rules have higher precedence than gen-
466 eral ones, i.e. the more general rules supply reasonable default values.
468 As you can see some lines contain substitution parameters - the parameters
469 preceded by the percent sign ('%'). The first alphabetical character after
470 the percent sign expands to the value which has been found on the left side.
471 For example +%l%(v) expands into +cz(bksl) if the respective values on the
472 left side were cz layout in its bksl variant. More, if the layout resp. vari-
473 ant parameter is followed by a pair of brackets ('[', ']') it means that xkb
474 should place the layout resp. variant into specified xkb group. If the brack-
475 ets are omitted the first group is the default value.
477 So the second block of rules enhances symbol definitions for some particular
478 keyboard models with extra keys (for internet, multimedia, ...) . Other mod-
479 els are left intact. Similarly, the last block overrides some key type defi-
480 nitions, so the common global behaviour ''shift cancels caps'' or ''shift
481 doesn't cancel caps'' can be selected. The rest of rules produces special
482 symbols for each variant us layout of macintosh keyboard and standard pc sym-
483 bols in appropriate variants as a default.
485 4.4 Descriptive Files of Rules
487 Now you just need to add a detailed description to <rules>.xml description
488 file so the other users (and external programs which often parse this file)
489 know what is your work about.
491 4.4.1 Old Descriptive Files
493 The formerly used descriptive files were named <rules>.lst Its structure is
494 very simple and quite self descriptive but such simplicity had also some cav-
495 ities, for example there was no way how to describe local variants of layouts
496 and there were problems with the localization of descriptions. To preserve
497 compatibility with some older programs, new XML descriptive files can be con-
498 verted to old format '.lst'.
500 For each parameter of rules file should be described its meaning. For the
501 rules file described above the .lst file could look like:
504 pc104 Generic 104-key PC
505 microsoft Microsoft Natural
507 macintosh Original Macintosh
517 caps:internal uses internal capitalization. Shift cancels Caps
518 caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps
520 And that should be it. Enjoy creating your own xkb mapping.
522 Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/XKB-Enhancing.sgml,v 1.2 dawes Exp $
525 $XFree86: xc/programs/xkbcomp/README.enhancing,v 1.5 2003/10/19 19:57:44 dawes Exp $
projects / xorg / xkeyboard-config / blob