components/x11/xorg-docs/src/input/XKB-Config.txt

   1 The XKB Configuration Guide
   2
   3 Kamil Toman
   4
   5 Ivan U. Pascal
   6
   7 X Version 11, Release 7.7
   8
   9 November 2010
  10
  11 This document describes how to configure Xorg XKB from a user's point of view.
  12 It covers basic configuration syntax and gives also a few examples.
  13
  14 This version covers Xorg server versions 1.8 and later, used with the data
  15 files from the xkeyboard-config project.
  16
  17 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  18
  19 Table of Contents
  20
  21 Overview
  22 Selecting XKB Configuration
  23
  24     Basic Configuration
  25     Advanced Configuration
  26     Even More Advanced Configuration
  27     Basic Global Options
  28
  29 Keymap XKB Configuration
  30
  31 Overview
  32
  33 The XKB configuration is decomposed into a number of components. Selecting
  34 proper parts and combining them back you can achieve most of the configurations
  35 you might need. Unless you have a completely atypical keyboard you really don't
  36 need to touch any of the xkb configuration files.
  37
  38 Some desktop environments now provide integrated graphical configuration tools
  39 for setting XKB configuration as part of your desktop session. The instructions
  40 in this document are provided for those without such support, those who need to
  41 configure XKB before the session startup (such as at the login screen), or
  42 those who need to perform more advanced configuration than those tools provide.
  43
  44 Selecting XKB Configuration
  45
  46 The easiest and the most natural way to specify a keyboard mapping is to use
  47 the rules component. As its name suggests it describes a number of general
  48 rules to combine all bits and pieces into a valid and useful keyboard mapping.
  49 All you need to do is to select a suitable rules file and then to feed it with
  50 a few parameters that will adjust the keyboard behaviour to fulfill your needs.
  51
  52 The parameters are:
  53
  54 XkbRules   files of rules to be used for keyboard mapping composition
  55
  56 XkbModel   name of the model of your keyboard type
  57
  58 XkbLayout  layout(s) you intend to use
  59
  60 XkbVariant variant(s) of the layout you intend to use
  61
  62 XkbOptions extra xkb configuration options
  63
  64 The rules file used depends on your system. The rules files commonly used with
  65 Xorg are provided by the xkeyboard-config project. On Linux systems, the evdev
  66 rules are most commonly used, on other systems the base rules are used. Some
  67 additional rules files exist for historical reasons, but are no longer widely
  68 used. In general, it's best to simply not specify the rules file, in order to
  69 use the default rules selected automatically by the X server.
  70
  71 For each rules file there is a description file named <vendor-rules>.lst, for
  72 instance base.lst which is located in the xkb configuration subdirectory rules
  73 (for example /usr/share/X11/xkb/rules).
  74
  75 Basic Configuration
  76
  77 Let's say you want to configure a PC-style American keyboard with 104 keys as
  78 described in base.lst. This can be done by simply writing several lines from
  79 below to a new configuration file in /etc/X11/xorg.conf.d, such as /etc/X11/
  80 xorg.conf.d/90-custom-kbd.conf.
  81
  82 Section "InputClass"
  83     Identifier "keyboard defaults"
  84     MatchIsKeyboard "on"
  85
  86     Option "XkbModel" "pc104"
  87     Option "XkbLayout" "us"
  88     Option "XKbOptions" ""
  89 EndSection
  90
  91
  92 The values of XkbModel and XkbLayout are really not surprising. The XkbOptions
  93 has been explicitly set to the empty set of parameters. The XkbVariant option
  94 has been left out. That means the default variant named basic is loaded.
  95
  96 Of course, this can be also done at runtime using the utility setxkbmap. The
  97 shell command loading the same keyboard mapping would look like:
  98
  99 setxkbmap -model pc104 -layout us -option ""
 100
 101
 102 The configuration and the shell command would be very analogous for most other
 103 layouts (internationalized mappings).
 104
 105 If you wanted to enable the Ctrl+Alt+Backspace sequence to kill the X server by
 106 default, you could create a configuration snippet /etc/X11/xorg.conf.d/
 107 90-zap.conf containing:
 108
 109 Section "InputClass"
 110     Identifier "keyboard defaults"
 111     MatchIsKeyboard "on"
 112
 113     Option "XKbOptions" "terminate:ctrl_alt_bksp"
 114 EndSection
 115
 116
 117 This would be equivalent to running the shell command:
 118
 119 setxkbmap -option "terminate:ctrl_alt_bksp"
 120
 121
 122 Advanced Configuration
 123
 124 You can use multi-layouts xkb configuration. What does it mean? Basically it
 125 allows to load up to four different keyboard layouts at a time. Each such
 126 layout would reside in its own group. The groups (unlike complete keyboard
 127 remapping) can be switched very fast from one to another by a combination of
 128 keys.
 129
 130 Let's say you want to configure your new Logitech cordless desktop keyboard,
 131 you intend to use three different layouts at the same time - us, czech and
 132 german (in this order), and that you are used to Alt+Shift combination for
 133 switching among them.
 134
 135 Then the configuration snippet could look like this:
 136
 137 Section "InputClass"
 138     Identifier "Logitech Cordless"
 139     MatchIsKeyboard   "on"
 140
 141     Option "XkbModel" "logicordless"
 142     Option "XkbLayout" "us,cz,de"
 143     Option "XKbOptions" "grp:alt_shift_toggle"
 144 EndSection
 145
 146
 147 Of course, this can be also done at runtime using the utility setxkbmap. The
 148 shell command loading the same keyboard mapping would look like:
 149
 150 setxkbmap -model logicordless -layout "us,cz,de" \
 151          -option "grp:alt_shift_toggle"
 152
 153
 154 Even More Advanced Configuration
 155
 156 Okay, let's say you are more demanding. You do like the example above but you
 157 want it to change a bit. Let's imagine you want the czech keyboard mapping to
 158 use another variant but basic. The configuration snippet then changes into:
 159
 160 Section "InputClass"
 161     Identifier "Logitech Cordless"
 162     MatchIsKeyboard   "on"
 163
 164     Option "XkbModel" "logicordless"
 165     Option "XkbLayout" "us,cz,de"
 166     Option "XkbVariant" ",bksl,"
 167     Option "XKbOptions" "grp:alt_shift_toggle"
 168 EndSection
 169
 170
 171 That seems tricky but it is not. The logic for settings of variants is the same
 172 as for layouts, that means the first and the third variant settings are left
 173 out (set to basic), the second is set to bksl (a special variant with an
 174 enhanced definition of the backslash key).
 175
 176 Analogously, the loading runtime will change to:
 177
 178 setxkbmap -model logicordless -layout "us,cz,de" \
 179          -variant ",bksl," -option "grp:alt_shift_toggle"
 180
 181
 182 Basic Global Options
 183
 184 For a list of available options, with a short decription of what they do, see
 185 the section starting with “! option” in the rules/*.lst files.
 186
 187 Keymap XKB Configuration
 188
 189 Keymap configuration is the way formerly used to configure xkb. The user
 190 included a special keymap file which specified the direct xkb configuration.
 191 This method has been obsoleted by previously described rules files which are
 192 far more flexible and allow simpler and more intuitive syntax. It is preserved
 193 merely for compatibility reasons and should be avoided if possible.
 194