Difference between revisions of "Keyboard configuration in Xorg"

From ArchWiki
Jump to: navigation, search
(Setting keyboard layout)
(Undo revision 296430 by Arkranur (talk) and added a more explicit version.)
(40 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 +
[[Category:Keyboards]]
 +
[[Category:X Server]]
 +
[[es:Keyboard Configuration in Xorg]]
 +
[[ja:Keyboard Configuration in Xorg]]
 +
{{Related articles start}}
 +
{{Related|Keyboard Configuration in Console}}
 +
{{Related|Extra Keyboard Keys}}
 +
{{Related|Xorg}}
 +
{{Related|X KeyBoard extension}}
 +
{{Related articles end}}
 +
 
{{Note|This article covers only basic configuration without modifying layouts, mapping extra keys etc. See [[Extra Keyboard Keys]] for these advanced topics.}}
 
{{Note|This article covers only basic configuration without modifying layouts, mapping extra keys etc. See [[Extra Keyboard Keys]] for these advanced topics.}}
 +
 +
Xorg uses the [[X KeyBoard extension]] (XKB) to manage keyboard layouts. Alternatively, [[xmodmap]] can be used to access the internal keymap table directly. Generally it is not recommended to use ''xmodmap'', except perhaps for the simplest tasks.
 +
 +
This article describes low-level configuration using XKB which is effective in most cases, but some desktop environments like [[GNOME]] override it with its own settings. You should read the information specific to the desktop environment:
 +
 +
* [[GNOME#Modify Keyboard with XkbOptions]]
 +
* [[KDE#Set keyboard]]
 +
 +
== Viewing keyboard settings ==
 +
 +
You can use the following command to see the actual XKB settings:
 +
 +
{{hc|$ setxkbmap -print -verbose 10|<nowiki>
 +
Setting verbose level to 10
 +
locale is C
 +
Applied rules from evdev:
 +
model:      evdev
 +
layout:    us
 +
options:    terminate:ctrl_alt_bksp
 +
Trying to build keymap using the following components:
 +
keycodes:  evdev+aliases(qwerty)
 +
types:      complete
 +
compat:    complete
 +
symbols:    pc+us+inet(evdev)+terminate(ctrl_alt_bksp)
 +
geometry:  pc(pc104)
 +
xkb_keymap {
 +
        xkb_keycodes  { include "evdev+aliases(qwerty)" };
 +
        xkb_types    { include "complete"      };
 +
        xkb_compat    { include "complete"      };
 +
        xkb_symbols  { include "pc+us+inet(evdev)+terminate(ctrl_alt_bksp)"    };
 +
        xkb_geometry  { include "pc(pc104)"    };
 +
};
 +
</nowiki>}}
 +
 +
=== Third party utilities ===
 +
 +
There are some "unofficial" utilities which allow to print specific information about the currently used keyboard layout.
 +
 +
* {{AUR|xkb-switch-git}}:
 +
 +
{{hc|$ xkb-switch|us}}
 +
 +
* {{AUR|xkblayout-state}}:
 +
 +
{{hc|$ xkblayout-state print "%s"|de}}
  
 
== Setting keyboard layout ==
 
== Setting keyboard layout ==
Line 11: Line 67:
 
* {{ic|XkbOptions}} contains some extra options. Used for specifying layout switching, notification LED, compose mode etc.
 
* {{ic|XkbOptions}} contains some extra options. Used for specifying layout switching, notification LED, compose mode etc.
  
To see a full list of keyboard models, layouts, variants and options, open {{ic|/usr/share/X11/xkb/rules/xorg.lst}}. Alternatively, you may use one of the following commands:
+
The layout name is usually a [[Wikipedia:ISO_3166-1_alpha-2#Officially_assigned_code_elements|2-letter country code]]. To see a full list of keyboard models, layouts, variants and options, along with a short description, open {{ic|/usr/share/X11/xkb/rules/base.lst}}. Alternatively, you may use one of the following commands to see a list without a description:
 +
 
 +
* {{ic|localectl list-x11-keymap-models}}
 +
* {{ic|localectl list-x11-keymap-layouts}}
 +
* {{ic|localectl list-x11-keymap-variants [''layout'']}}
 +
* {{ic|localectl list-x11-keymap-options}}
  
 
Examples in the following subsections will have the same effect, they will set {{ic|pc104}} model, {{ic|cz}} as primary layout, {{ic|us}} as secondary layout, {{ic|dvorak}} variant for {{ic|us}} layout and the {{ic|Alt+Shift}} combination for switching between layouts.
 
Examples in the following subsections will have the same effect, they will set {{ic|pc104}} model, {{ic|cz}} as primary layout, {{ic|us}} as secondary layout, {{ic|dvorak}} variant for {{ic|us}} layout and the {{ic|Alt+Shift}} combination for switching between layouts.
Line 17: Line 78:
 
=== Using setxkbmap ===
 
=== Using setxkbmap ===
  
The tool ''setxkbmap'' sets the keyboard layout for an active X server and the setting is persistent only until the session ends. It is useful to override system-wide configuration specified by [[#Using X configuration files|X configuration files]].
+
The tool ''setxkbmap'' sets the keyboard layout for an active X server and the setting is persistent only until the session ends, but you can use [[xinitrc]] to make it persistent across reboots. It is useful to override system-wide configuration specified by [[#Using X configuration files|X configuration files]].
  
 
The usage is as follows:
 
The usage is as follows:
  
  $ setxkbmap -model ''xkb_model'' -layout ''xkb_layout'' -variant ''xkb_variant'' -option ''xkb_options''
+
  $ setxkbmap [-model ''xkb_model''] [-layout ''xkb_layout''] [-variant ''xkb_variant''] [-option ''xkb_options'']
  
 
It is not necessary to specify all options, e.g. you can change just a layout:
 
It is not necessary to specify all options, e.g. you can change just a layout:
Line 62: Line 123:
 
  $ localectl set-x11-keymap cz,us pc104 ,dvorak grp:alt_shift_toggle
 
  $ localectl set-x11-keymap cz,us pc104 ,dvorak grp:alt_shift_toggle
  
 +
== Frequently used XKB options ==
  
 +
=== Switching between keyboard layouts ===
  
 +
To be able to easily switch keyboard layouts, first specify multiple layouts between which you want to switch (the first one is the default). Then specify a key (or key combination), which will be used for switching. For example, to switch between a US and a Swedish layout using the {{ic|CapsLock}} key, use {{ic|us,se}} as an argument of {{ic|XkbLayout}} and {{ic|grp:caps_toggle}} as an argument of {{ic|XkbOptions}}.
  
 +
You can use other key combinations than {{ic|CapsLock}}, they are listed in {{ic|/usr/share/X11/xkb/rules/base.lst}}, start with {{ic|grp:}} and end with {{ic|_toggle}}. To get the full list of available options, run the following command:
  
 +
$ grep "grp:.*_toggle" /usr/share/X11/xkb/rules/base.lst
  
== Key repeat delay and rate ==
+
=== Terminating Xorg with Ctrl+Alt+Backspace ===
  
Use {{ic|xset r rate ''delay'' ''rate''}} to change them, then use [[xinitrc]] to make it permanent. Values 170 and 30 respectively are a good start point.
+
By default, the key combination {{ic|Ctrl+Alt+Backspace}} is disabled. You can enable it by passing {{ic|terminate:ctrl_alt_bksp}} to {{ic|XkbOptions}}.
  
== Viewing keyboard settings ==
+
=== Swapping Caps Lock with Left Control ===
  
{{hc|$ setxkbmap -print -verbose 10|<nowiki>
+
To swap Caps Lock with Left Control key, add {{ic|ctrl:swapcaps}} to {{ic|XkbOptions}}. Run the following command to see similar options along with their descriptions:
Setting verbose level to 10
+
locale is C
+
Applied rules from evdev:
+
model:      evdev
+
layout:    us
+
options:    terminate:ctrl_alt_bksp
+
Trying to build keymap using the following components:
+
keycodes:  evdev+aliases(qwerty)
+
types:      complete
+
compat:    complete
+
symbols:    pc+us+inet(evdev)+terminate(ctrl_alt_bksp)
+
geometry:  pc(pc104)
+
xkb_keymap {
+
        xkb_keycodes  { include "evdev+aliases(qwerty)" };
+
        xkb_types    { include "complete"      };
+
        xkb_compat    { include "complete"      };
+
        xkb_symbols  { include "pc+us+inet(evdev)+terminate(ctrl_alt_bksp)"    };
+
        xkb_geometry  { include "pc(pc104)"    };
+
};
+
</nowiki>}}
+
  
== Setting keyboard layout ==
+
$ grep -E "(ctrl|caps):" /usr/share/X11/xkb/rules/base.lst
  
{{Note|If you use [[GNOME]], these settings will be ignored. You will have to set the keyboard layout from the GNOME Keyboard applet. Follow the Keyboard Layout link and add the layout you require and remove any you do not. For XkbOptions, see [[GNOME#Modify Keyboard with XkbOptions]].}}
+
=== Enabling mouse keys ===
  
 +
[[Wikipedia:Mouse keys|Mouse keys]] is now disabled by default and has to be manually enabled by passing {{ic|keypad:pointerkeys}} to {{ic|XkbOptions}}. This will make the {{ic|Shift+NumLock}} shortcut toggle mouse keys.
  
 +
=== Configuring compose key ===
  
== Switching between keyboard layouts ==
+
The [[Wikipedia:Compose key|compose key]], when pressed in sequence with other keys, produces a unicode character. For example, in most configurations pressing {{ic|''compose_key'' ' e}} produces {{ic|é}}. This is especially useful if you need to type in a different language then the one for which the keyboard layout was designed (such as typing in French, Italian and German on an American keyboard).
  
To be able to easily switch keyboard layouts, modify the Options used in either of the above two methods. For example, to switch between a US and a Swedish layout using the {{ic|Caps Lock}} key, create a file {{ic|/etc/X11/xorg.conf.d/01-keyboard-layout.conf}} with the following content:
+
For example, for a system-wide right {{ic|Alt}} compose key that is persistent between reboots, pass {{ic|compose:ralt}} to {{ic|XkbOptions}} in {{ic|/etc/X11/xorg.conf.d/10-keyboard.conf}}
  
{{bc|
+
{{hc|/etc/X11/xorg.conf.d/10-keyboard.conf|
 
Section "InputClass"
 
Section "InputClass"
    Identifier             "keyboard-layout"
+
        Identifier "system-keyboard"
    MatchIsKeyboard       "on"
+
        MatchIsKeyboard "on"
    Option "XkbLayout"    "us, se"
+
        Option "XkbOptions" "compose:ralt"
    Option "XkbOptions"   "grp:caps_toggle"
+
 
EndSection
 
EndSection
 
}}
 
}}
  
As an alternative, you can add the following to your {{ic|.xinitrc}}:
+
You can use other keys as compose keys, they are listed in {{ic|/usr/share/X11/xkb/rules/base.lst}} and start with {{ic|compose:}}. To get the full list of available options, run the following command:
  
  $ setxkbmap -layout "us, se" -option "grp:caps_toggle"
+
  $ grep "compose:" /usr/share/X11/xkb/rules/base.lst
  
This is mainly useful if you run a Desktop Environment which does not take care of keyboard layouts for you.
+
==== Key combinations ====
  
{{Tip|If you want to get a list of possible values for the layout and options, you can find them in {{ic|/usr/share/X11/xkb/rules/xorg.lst}}. They are under sections {{ic|! layout}} and {{ic|! option}} respectively. These values work for both the configuration file solution, and the command line alternative.}}
+
The default combinations for the compose keys depend on the locale and are stored in {{ic|/usr/share/X11/locale/''used_locale''/Compose}}, where {{ic|''used_locale''}} is for example {{ic|en_US.UTF-8}}.
  
== Enable pointerkeys ==
+
You can define your own compose key combinations by copying the default file to {{ic|~/.XCompose}} and editing it. The compose key works with any of the thousands of valid Unicode characters, including those outside the Basic Multilingual Plane.
  
[[Wikipedia:Mouse keys|Mouse keys]] is now disabled by default and has to be manually enabled:
+
However, GTK does not use [[Wikipedia:X Input Method|XIM]] by default and therefore does not follow {{ic|~/.XCompose}} keys. This can be fixed by forcing GTK to use XIM by adding {{ic|1=export GTK_IM_MODULE=xim}} and/or {{ic|1=export XMODIFIERS="@im=none"}} to {{ic|~/.xprofile}}.
  
{{hc|/etc/X11/xorg.conf.d/20-enable-pointerkeys.conf|<nowiki>
+
{{Tip|XIM is very old, you might have better luck with other input methods: [[Wikipedia:Smart Common Input Method|SCIM]], [[Wikipedia:Uim|uim]], [[Wikipedia:Intelligent Input Bus|IBus]] etc. See [[Internationalization#Input methods in Xorg]] for details.}}
Section "InputClass"
+
 
    Identifier            "Keyboard Defaults"
+
=== Currency sign on other key ===
    MatchIsKeyboard        "yes"
+
 
    Option                "XkbOptions" "keypad:pointerkeys"
+
Most European keyboards have a Euro sign (€) printed on on the {{ic|5}} key. To access it with, for example, {{ic|ALT}}+{{ic|5}}, use the {{ic|lv3:lalt_switch}} and {{ic|eurosign:5}} options.
EndSection
+
 
</nowiki>}}
+
The Rupee sign (₹) can be used the same way with {{ic|rupeesign:4}}.
 +
 
 +
== Other settings ==
 +
 
 +
=== Adjusting typematic delay and rate ===
 +
 
 +
The ''typematic delay'' indicates the amount of time (typically in miliseconds) a key needs to be pressed in order for the repeating process to begin. After the repeating process has been triggered, the character will be repeated with a certain frequency (usually given in Hz) specified by the ''typematic rate''. These values can be changed using the ''xset'' command:
 +
 
 +
$ xset r rate ''delay'' [''rate'']
 +
 
 +
For example to set a typematic delay to 200ms and a typematic rate to 30Hz, use the following command (use [[xinitrc]] to make it permanent):
  
You can also run:
+
$ xset r rate 200 30
  
$ setxkbmap -option keypad:pointerkeys
+
Issuing the command without specifying the delay and rate will reset the typematic values to their respective defaults; a delay of 660ms and a rate of 25Hz:
  
Both will make the {{ic|Shift+Num Lock}} shortcut toggle mouse keys.
+
$ xset r rate

Revision as of 00:18, 7 February 2014

Note: This article covers only basic configuration without modifying layouts, mapping extra keys etc. See Extra Keyboard Keys for these advanced topics.

Xorg uses the X KeyBoard extension (XKB) to manage keyboard layouts. Alternatively, xmodmap can be used to access the internal keymap table directly. Generally it is not recommended to use xmodmap, except perhaps for the simplest tasks.

This article describes low-level configuration using XKB which is effective in most cases, but some desktop environments like GNOME override it with its own settings. You should read the information specific to the desktop environment:

Viewing keyboard settings

You can use the following command to see the actual XKB settings:

$ setxkbmap -print -verbose 10
Setting verbose level to 10
locale is C
Applied rules from evdev:
model:      evdev
layout:     us
options:    terminate:ctrl_alt_bksp
Trying to build keymap using the following components:
keycodes:   evdev+aliases(qwerty)
types:      complete
compat:     complete
symbols:    pc+us+inet(evdev)+terminate(ctrl_alt_bksp)
geometry:   pc(pc104)
xkb_keymap {
        xkb_keycodes  { include "evdev+aliases(qwerty)" };
        xkb_types     { include "complete"      };
        xkb_compat    { include "complete"      };
        xkb_symbols   { include "pc+us+inet(evdev)+terminate(ctrl_alt_bksp)"    };
        xkb_geometry  { include "pc(pc104)"     };
};

Third party utilities

There are some "unofficial" utilities which allow to print specific information about the currently used keyboard layout.

$ xkb-switch
us
$ xkblayout-state print "%s"
de

Setting keyboard layout

Keyboard layout in Xorg can be set in multiple ways. Here is an explanation of used options:

  • XkbModel selects the keyboard model. This has an influence only for some extra keys your keyboard might have. The safe fallback are pc104 or pc105. But for instance laptops usually have some extra keys, and sometimes you can make them work by simply setting a proper model.
  • XkbLayout selects the keyboard layout. Multiple layouts may be specified in a comma-separated list, e.g. if you want to quickly switch between layouts.
  • XkbVariant selects a specific layout variant. For instance, the default sk variant is qwertz, but you can manually specify qwerty etc.
Warning: You must specify as many variants as the number of specified layouts. If you want the default variant, specify an empty string as the variant (the comma must stay). For example, to have the default us layout as primary and the dvorak variant of us layout as secondary, specify us,us as XkbLayout and ,dvorak as XkbVariant.
  • XkbOptions contains some extra options. Used for specifying layout switching, notification LED, compose mode etc.

The layout name is usually a 2-letter country code. To see a full list of keyboard models, layouts, variants and options, along with a short description, open /usr/share/X11/xkb/rules/base.lst. Alternatively, you may use one of the following commands to see a list without a description:

  • localectl list-x11-keymap-models
  • localectl list-x11-keymap-layouts
  • localectl list-x11-keymap-variants [layout]
  • localectl list-x11-keymap-options

Examples in the following subsections will have the same effect, they will set pc104 model, cz as primary layout, us as secondary layout, dvorak variant for us layout and the Alt+Shift combination for switching between layouts.

Using setxkbmap

The tool setxkbmap sets the keyboard layout for an active X server and the setting is persistent only until the session ends, but you can use xinitrc to make it persistent across reboots. It is useful to override system-wide configuration specified by X configuration files.

The usage is as follows:

$ setxkbmap [-model xkb_model] [-layout xkb_layout] [-variant xkb_variant] [-option xkb_options]

It is not necessary to specify all options, e.g. you can change just a layout:

$ setxkbmap -layout xkb_layout

See man 1 setxkbmap for a full list of command line arguments.

For example:

$ setxkbmap -model pc104 -layout cz,us -variant ,dvorak -option grp:alt_shift_toggle

Using X configuration files

The syntax of X configuration files is explained in Xorg#Configuration. This method creates system-wide configuration which is persistent across reboots.

Here is an example:

/etc/X11/xorg.conf.d/10-keyboard.conf
Section "InputClass"
        Identifier "system-keyboard"
        MatchIsKeyboard "on"
        Option "XkbLayout" "cz,us"
        Option "XkbModel" "pc104"
        Option "XkbVariant" ",dvorak"
        Option "XkbOptions" "grp:alt_shift_toggle"
EndSection

Using localectl

For convenience, the tool localectl may be used instead of manual editing of X configuration file. It will save the configuration in /etc/X11/xorg.conf.d/00-keyboard.conf, this file should not be manually edited, because localectl will overwrite the changes on next start.

The usage is as follows:

$ localectl set-x11-keymap layout [model] [variant] [options]

The following command will create a file /etc/X11/xorg.conf.d/00-keyboard.conf with pretty much the same content as the example above:

$ localectl set-x11-keymap cz,us pc104 ,dvorak grp:alt_shift_toggle

Frequently used XKB options

Switching between keyboard layouts

To be able to easily switch keyboard layouts, first specify multiple layouts between which you want to switch (the first one is the default). Then specify a key (or key combination), which will be used for switching. For example, to switch between a US and a Swedish layout using the CapsLock key, use us,se as an argument of XkbLayout and grp:caps_toggle as an argument of XkbOptions.

You can use other key combinations than CapsLock, they are listed in /usr/share/X11/xkb/rules/base.lst, start with grp: and end with _toggle. To get the full list of available options, run the following command:

$ grep "grp:.*_toggle" /usr/share/X11/xkb/rules/base.lst

Terminating Xorg with Ctrl+Alt+Backspace

By default, the key combination Ctrl+Alt+Backspace is disabled. You can enable it by passing terminate:ctrl_alt_bksp to XkbOptions.

Swapping Caps Lock with Left Control

To swap Caps Lock with Left Control key, add ctrl:swapcaps to XkbOptions. Run the following command to see similar options along with their descriptions:

$ grep -E "(ctrl|caps):" /usr/share/X11/xkb/rules/base.lst

Enabling mouse keys

Mouse keys is now disabled by default and has to be manually enabled by passing keypad:pointerkeys to XkbOptions. This will make the Shift+NumLock shortcut toggle mouse keys.

Configuring compose key

The compose key, when pressed in sequence with other keys, produces a unicode character. For example, in most configurations pressing compose_key ' e produces é. This is especially useful if you need to type in a different language then the one for which the keyboard layout was designed (such as typing in French, Italian and German on an American keyboard).

For example, for a system-wide right Alt compose key that is persistent between reboots, pass compose:ralt to XkbOptions in /etc/X11/xorg.conf.d/10-keyboard.conf

/etc/X11/xorg.conf.d/10-keyboard.conf
Section "InputClass"
        Identifier "system-keyboard"
        MatchIsKeyboard "on"
        Option "XkbOptions" "compose:ralt"
EndSection

You can use other keys as compose keys, they are listed in /usr/share/X11/xkb/rules/base.lst and start with compose:. To get the full list of available options, run the following command:

$ grep "compose:" /usr/share/X11/xkb/rules/base.lst

Key combinations

The default combinations for the compose keys depend on the locale and are stored in /usr/share/X11/locale/used_locale/Compose, where used_locale is for example en_US.UTF-8.

You can define your own compose key combinations by copying the default file to ~/.XCompose and editing it. The compose key works with any of the thousands of valid Unicode characters, including those outside the Basic Multilingual Plane.

However, GTK does not use XIM by default and therefore does not follow ~/.XCompose keys. This can be fixed by forcing GTK to use XIM by adding export GTK_IM_MODULE=xim and/or export XMODIFIERS="@im=none" to ~/.xprofile.

Tip: XIM is very old, you might have better luck with other input methods: SCIM, uim, IBus etc. See Internationalization#Input methods in Xorg for details.

Currency sign on other key

Most European keyboards have a Euro sign (€) printed on on the 5 key. To access it with, for example, ALT+5, use the lv3:lalt_switch and eurosign:5 options.

The Rupee sign (₹) can be used the same way with rupeesign:4.

Other settings

Adjusting typematic delay and rate

The typematic delay indicates the amount of time (typically in miliseconds) a key needs to be pressed in order for the repeating process to begin. After the repeating process has been triggered, the character will be repeated with a certain frequency (usually given in Hz) specified by the typematic rate. These values can be changed using the xset command:

$ xset r rate delay [rate]

For example to set a typematic delay to 200ms and a typematic rate to 30Hz, use the following command (use xinitrc to make it permanent):

$ xset r rate 200 30

Issuing the command without specifying the delay and rate will reset the typematic values to their respective defaults; a delay of 660ms and a rate of 25Hz:

$ xset r rate