1 The xkb_keycodes section
2 ========================
4 This is the simplest section type, and is the first one to be
5 compiled. The purpose of this is mostly to map between the
6 hardware/evdev scancodes and xkb keycodes. Each key is given a name
7 by which it can be referred to later, e.g. in the symbols section.
11 Statements of the form:
16 The above would let 49 and 10 be valid keycodes in the keymap, and
17 assign them the names TLDE and AE01 respectively. The format <WXYZ> is
18 always used to refer to a key by name.
20 [The naming convention <AE01> just denoted the position of the key
21 in the main alphanumric section of the keyboard, with the two letters
22 specifying the row and the two digits specifying the column, from
25 In the common case this just maps to the evdev scancodes from
26 /usr/include/linux/input.h, e.g. the following definitions:
31 correspond to the ones above. Similar definitions appear in the
32 xf86-input-keyboard driver. Note that in all current keymaps there's a
33 constant offset of 8 (for historical reasons).
35 If there's a conflict, like the same name given to different keycodes,
36 or same keycode given different names, it is resolved according to the
37 merge mode which applies to the definitions.
41 Statements of the form:
43 alias <MENU> = <COMP>;
45 Allows to refer to a previously defined key (here <COMP>) by another
46 name (here <MENU>). Conflicts are handled similarly to keycode
51 Statements of the form:
53 indicator 1 = "Caps Lock";
54 indicator 2 = "Num Lock";
55 indicator 3 = "Scroll Lock";
57 Assigns a name to the keyboard LED (a.k.a indicator) with the given
58 index. The LED may be referred by this name later in the compat section
65 This section is the second to be processesed, after xkb_keycodes.
66 However, it is completely independent and could have been the first
67 to be processed (it does not refer to specific keys as specified in
68 the xkb_keycodes section).
70 This section defines key types, which, given a key and a keyboard
71 state (i.e. modifier state and group), determine the shift level to
72 be used in translating the key to keysyms. These types are assigned
73 to each group in each key, in the xkb_symbols section.
75 Key types are called this way because, in a way, they really describe
76 the "type" of the key (or more correctly, a specific group of the
77 key). For example, an ordinary keymap will provide a type called
78 "KEYPAD", which consists of two levels, with the second level being
79 chosen according to the state of the Num Lock (or Shift) modifiers.
80 Another example is a type called "ONE_LEVEL", which is usually
81 assigned to keys such as Escape; these have just one level and are
82 not affected by the modifier state. Yet more common examples are
83 "TWO_LEVEL" (with Shift choosing the second level), "ALPHABETIC"
84 (where Caps Lock may also choose the second level), etc.
88 Statements of the form:
90 type "FOUR_LEVEL" { ... }
92 The above would create a new type named "FOUR_LEVEL".
93 The body of the definition may include statements of the following
96 - level_name statements (mandatory for each level in the type):
98 level_name[Level1] = "Base";
100 Gives each level in this type a descriptive name. It isn't used
102 Note: A level may be specified as Level[1-8] or just a number (can
105 - modifiers statement (mandatory, should be specified only once):
107 modifiers = Shift+Lock+LevelThree;
109 A mask of real and virtual modifiers. These are the only modifiers
110 being considered when matching the modifier state against the type.
111 The other modifiers, whether active or not, are masked out in the
114 - map entry statements (should have at least as many mappings as there
115 are levels in the type):
117 map[Shift+LevelThree] = Level4;
119 If the active modifiers, masked with the type's modifiers (as stated
120 above), match (i.e. equal) the modifiers inside the map[] statement,
121 then the level in the right hand side is chosen. For example, in the
122 above, if in the current keyboard state the Shift and LevelThree
123 modifiers are active, while the Lock modifier is not, then the
124 keysym(s) in the 4th level of the group will be returned to the
127 - preserve statements:
129 map[Shift+Lock+LevelThree] = Level5;
130 preserve[Shift+Lock+LevelThree] = Lock;
132 When a map entry matches the active modifiers and the level it
133 specified is chosen, then these modifiers are said to be "consumed";
134 for example, in a simple US keymap where the "g" key is assigned an
135 ordinary ALPHABETIC key type, if the Lock (Caps Lock) modifier is
136 active and the key is pressed, then a "G" keysym is produced (as
137 opposed to lower-case "g"). This is because the type definition has
138 a map entry like the following:
142 And as such the Lock modifier is consumed. This information is
143 relevant for applications which further process the modifiers,
144 since by then the consumed modifiers have already "done their part"
145 and should be masked out.
147 However, sometimes even if a modifier is actually used to choose
148 the shift level (as Lock above), it should *not* be reported as
149 consumed, for various reasons. In this case, a preserve[] statement
150 can be used to augment the map entry. The modifiers inside the square
151 brackets should match one of the map[] statements in the type. The
152 right hand side should consists of modifiers from the left hand
153 side; these modifiers are then "preserved" and not reported as
157 The xkb_compat section
158 ======================
160 This section is the third to be processed, after xkb_keycodes and
165 Statements of the form:
167 interpret Num_Lock+Any { ... }
168 interpret Shift_Lock+AnyOf(Shift+Lock) { ... }
170 The xkb_symbols section (see below) allows the keymap author to perform,
171 among other things, the following things for each key:
173 - Bind an action, like SetMods or LockGroup, to the key. Actions, like
174 symbols, are specified for each level of each group in the key
177 - Add a virtual modifier to the key's virtual modifier mapping (vmodmap).
179 - Specify whether the key should repeat or not.
181 However, doing this for each key (or level) is tedious and inflexible.
182 Interpret's are a mechanism to apply these settings to a bunch of
185 Each interpret specifies a condition by which it attaches to certain
186 levels. The condition consists of two parts:
188 - A keysym. If the level has a different (or more than one) keysym, the
189 match fails. Leaving out the keysym is equivalent to using the NoSymbol
190 keysym, which always matches successfully.
192 - A modifier predicate. The predicate consists of a matching operation
193 and a mask of (real) modifiers. The modifiers are matched against the
194 key's modifier map (modmap). The matching operation can be one of the
197 * AnyOfOrNone - The modmap must either be empty or include at least
198 one of the specified modifiers.
199 * AnyOf - The modmap must include at least one of the specified
201 * NoneOf - The modmap must not include any of the specified modifiers.
202 * AllOf - The modmap must include all of the specified modifiers (but
203 may include others as well).
204 * Exactly - The modmap must be exactly the same as the specified
207 Leaving out the predicate is equivalent to using AnyOfOrNone while
208 specifying all modifiers. Leaving out just the matching condition
209 is equivalent to using Exactly.
211 An interpret may also include "useModMapMods = level1;" - see below.
213 If a level fulfils the conditions of several interpret's, only the
214 most specific one is used:
216 - A specific keysym will always match before a generic NoSymbol
219 - If the keysyms are the same, the interpret with the more specific
220 matching operation is used. The above list is sorted from least to
223 - If both the keysyms and the matching operations are the same (but the
224 modifiers are different), the first interpret is used.
226 As described above, once an interpret "attaches" to a level, it can bind
227 an action to that level, add one virtual modifier to the key's vmodmap,
228 or set the key's repeat setting. You should note the following:
230 - The key repeat is a property of the entire key; it is not level-specific.
231 In order to avoid confusion, it is only inspected for the first level of
232 the first group; the interpret's repeat setting is ignored when applied
235 - If one of the above fields was set directly for a key in xkb_symbols,
236 the explicit setting takes precedence over the interpret.
238 The body of the statement may include statements of the following
239 forms (all of which are optional):
241 - useModMapMods statement:
243 useModMapMods = level1;
245 When set to 'level1', the interpret will only match levels which are
246 the first level of the first group of the keys. This can be useful in
247 conjunction with e.g. a virtualModifier statement.
251 action = LockMods(modifiers=NumLock);
253 Bind this action to the matching levels.
255 - virtual modifier statement:
257 virtualModifier = NumLock;
259 Add this virtual modifier to the key's vmodmap. The given virtual
260 modifier must be declared at the top level of the file with a
261 virtual_modifiers statement, e.g.:
263 virtual_modifiers NumLock;
269 Set whether the key should repeat or not. Must be a boolean value.
273 Statements of the form:
275 indicator "Shift Lock" { ... }
277 This statement specifies the behavior and binding of the LED (a.k.a
278 indicator) with the given name ("Shift Lock" above). The name should
279 have been declared previously in the xkb_keycodes section (see LED
280 name statement), and given an index there. If it wasn't, it is created
281 with the next free index.
282 The body of the statement describes the conditions of the keyboard
283 state which will cause the LED to be lit. It may include the following
286 - modifiers statement:
288 modifiers = ScrollLock;
290 If the given modifiers are in the required state (see below), the
293 - whichModifierState statment:
295 whichModState = Latched+Locked;
297 Can be any combination of:
299 * base, latched, locked, effective
300 * any (i.e. all of the above)
301 * none (i.e. none of the above)
302 * compat (legacy value, treated as effective)
304 This will cause the respective portion of the modifer state (see
305 struct xkb_state) to be matched against the modifiers given in the
306 "modifiers" statement.
308 Here's a simple example:
310 indicator "Num Lock" {
312 whichModState = Locked;
315 Whenever the NumLock modifier is locked, the Num Lock LED will light
320 groups = All - group1;
322 If the given groups are in the required state (see below), the LED
325 - whichGroupState statment:
327 whichGroupState = Effective;
329 Can be any combination of:
331 * base, latched, locked, effective
332 * any (i.e. all of the above)
333 * none (i.e. none of the above)
335 This will cause the respective portion of the group state (see
336 struct xkb_state) to be matched against the groups given in the
339 Note: the above conditions are disjunctive, i.e. if any of them are
340 satisfied the LED is lit.
343 The xkb_symbols section
344 =======================
346 This section is the fourth to be processed, after xkb_keycodes,
347 xkb_types and xkb_compat.
352 Virtual modifier statements
353 ===========================
355 Statements of the form:
356 virtual_modifiers LControl;
358 Can appear in the xkb_types, xkb_compat, xkb_symbols sections.