https://wiki.archlinux.org/api.php?action=feedcontributions&user=Kinono&feedformat=atomArchWiki - User contributions [en]2024-03-29T11:51:27ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Xorg/Keyboard_configuration&diff=580585Xorg/Keyboard configuration2019-08-20T13:20:14Z<p>Kinono: Add instructions for Fcitx/IBus users to set keyboard layout.</p>
<hr />
<div>[[Category:X server]]<br />
[[Category:Keyboard configuration]]<br />
[[es:Keyboard configuration in Xorg]]<br />
[[ja:Xorg でのキーボード設定]]<br />
[[ru:Xorg (Русский)/Keyboard configuration]]<br />
{{Related articles start}}<br />
{{Related|X keyboard extension}}<br />
{{Related|Linux console/Keyboard configuration}}<br />
{{Related|Extra keyboard keys}}<br />
{{Related|Xorg}}<br />
{{Related|Keyboard shortcuts}}<br />
{{Related articles end}}<br />
<br />
This article describes the basics of [[Xorg]] keyboard configuration. For advanced topics such as keyboard layout modification or additional key mappings, see [[X keyboard extension]] or [[Extra keyboard keys]] respectively.<br />
<br />
The Xorg server uses the [[X keyboard extension]] (XKB) to define keyboard layouts. Optionally, [[xmodmap]] can be used to access the internal keymap table directly, although this is not recommended for complex tasks. Also [[systemd]]'s ''localectl'' can be used to define the keyboard layout for both the Xorg server and the virtual console.<br />
<br />
{{Note|XKB options can be overridden by the tools provided by some desktop environments such as [[GNOME]] and [[KDE]].}}<br />
<br />
== Viewing keyboard settings ==<br />
<br />
You can use the following command to see the actual XKB settings:<br />
<br />
{{hc|$ setxkbmap -print -verbose 10|<nowiki><br />
Setting verbose level to 10<br />
locale is C<br />
Applied rules from evdev:<br />
model: evdev<br />
layout: us<br />
options: terminate:ctrl_alt_bksp<br />
Trying to build keymap using the following components:<br />
keycodes: evdev+aliases(qwerty)<br />
types: complete<br />
compat: complete<br />
symbols: pc+us+inet(evdev)+terminate(ctrl_alt_bksp)<br />
geometry: pc(pc104)<br />
xkb_keymap {<br />
xkb_keycodes { include "evdev+aliases(qwerty)" };<br />
xkb_types { include "complete" };<br />
xkb_compat { include "complete" };<br />
xkb_symbols { include "pc+us+inet(evdev)+terminate(ctrl_alt_bksp)" };<br />
xkb_geometry { include "pc(pc104)" };<br />
};<br />
</nowiki>}}<br />
<br />
=== Third party utilities ===<br />
<br />
There are some "unofficial" utilities which allow to print specific information about the currently used keyboard layout.<br />
<br />
* {{AUR|xkb-switch-git}}:<br />
<br />
{{hc|$ xkb-switch|us}}<br />
<br />
* {{AUR|xkblayout-state-git}}:<br />
<br />
{{hc|$ xkblayout-state print "%s"|de}}<br />
<br />
== Setting keyboard layout ==<br />
<br />
{{Expansion|Udev also comes into play (for example when plugging in a keyboard), undoing changes by ''setxkbmap''}}<br />
<br />
Keyboard layout in Xorg can be set in multiple ways. Here is an explanation of used options:<br />
<br />
* {{ic|XkbModel}} selects the keyboard model. This has an influence only for some extra keys your keyboard might have. The safe fallback are {{ic|pc104}} or {{ic|pc105}}. But for instance laptops usually have some extra keys, and sometimes you can make them work by simply setting a proper model.<br />
* {{ic|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.<br />
* {{ic|XkbVariant}} selects a specific layout variant. For instance, the default {{ic|sk}} variant is {{ic|qwertz}}, but you can manually specify {{ic|qwerty}}, etc.<br />
* {{ic|XkbOptions}} contains some extra options. Used for specifying layout switching, notification LED, compose mode etc. See the [[#Frequently used XKB options]] section for examples.<br />
<br />
{{Note|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 {{ic|us}} layout as primary and the {{ic|dvorak}} variant of {{ic|us}} layout as secondary, specify {{ic|us,us}} as {{ic|XkbLayout}} and {{ic|,dvorak}} as {{ic|XkbVariant}}.}}<br />
<br />
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:<br />
<br />
* {{ic|localectl list-x11-keymap-models}}<br />
* {{ic|localectl list-x11-keymap-layouts}}<br />
* {{ic|localectl list-x11-keymap-variants [''layout'']}}<br />
* {{ic|localectl list-x11-keymap-options}}<br />
<br />
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. See {{man|7|xkeyboard-config}} for more detailed information.<br />
<br />
{{Note|Fcitx/IBus users may find these methods not work, or just work for a while, since they will try to control keyboard layout. Fcitx users need to set the first input method to be {{ic|Keyboard - ''layout''}}. See [[Fcitx#Input methods configuration]]. IBus users need to enable "Use system keyboard layout" option in Preference -> Advanced if using X configuration files, or manually specify the layout if using setxkbmap. See [[IBus#Non US keyboards]]}}<br />
<br />
=== Using setxkbmap ===<br />
<br />
''setxkbmap'' sets the keyboard layout for the current X session only, but can be made persistent in [[xinitrc]] or [[xprofile]]. This overrides system-wide configuration specified following [[#Using X configuration files]].<br />
<br />
The usage is as follows (see {{man|1|setxkbmap}}):<br />
<br />
$ setxkbmap [-model ''xkb_model''] [-layout ''xkb_layout''] [-variant ''xkb_variant''] [-option ''xkb_options'']<br />
<br />
To change just the layout ({{ic|-layout}} is the default flag):<br />
<br />
$ setxkbmap ''xkb_layout''<br />
<br />
For multiple customizations:<br />
<br />
$ setxkbmap -model pc104 -layout cz,us -variant ,dvorak -option grp:alt_shift_toggle<br />
<br />
=== Using X configuration files ===<br />
<br />
{{Note|{{ic|xorg.conf}} is parsed by the X server at start-up. To apply changes, restart X.}}<br />
<br />
The syntax of X configuration files is explained in [[Xorg#Configuration]]. This method creates system-wide configuration which is persistent across reboots.<br />
<br />
Here is an example:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/00-keyboard.conf|<br />
Section "InputClass"<br />
Identifier "system-keyboard"<br />
MatchIsKeyboard "on"<br />
Option "XkbLayout" "cz,us"<br />
Option "XkbModel" "pc104"<br />
Option "XkbVariant" ",dvorak"<br />
Option "XkbOptions" "grp:alt_shift_toggle"<br />
EndSection<br />
}}<br />
<br />
==== Using localectl ====<br />
<br />
For convenience, the tool ''localectl'' may be used instead of manually editing X configuration files. It will save the configuration in {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}}, this file should not be manually edited, because ''localectl'' will overwrite the changes on next start.<br />
<br />
The usage is as follows:<br />
<br />
$ localectl [--no-convert] set-x11-keymap ''layout'' [''model'' [''variant'' [''options'']]]<br />
<br />
To set a ''model'', ''variant'' or ''options'', all preceding fields need to be specified, but the preceding fields can be skipped by passing an empty string with {{ic|""}}. Unless the {{ic|--no-convert}} option is passed, the specified keymap is also converted to the closest matching console keymap and applied to the [[Keyboard configuration in console|console configuration]] in {{ic|vconsole.conf}}. See {{man|1|localectl}} for more information.<br />
<br />
To create a {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}} like the above:<br />
<br />
$ localectl --no-convert set-x11-keymap cz,us pc104 ,dvorak grp:alt_shift_toggle<br />
<br />
== Frequently used XKB options ==<br />
<br />
=== Switching between keyboard layouts ===<br />
<br />
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}}.<br />
<br />
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:<br />
<br />
$ grep "grp:.*toggle" /usr/share/X11/xkb/rules/base.lst<br />
<br />
=== Terminating Xorg with Ctrl+Alt+Backspace ===<br />
<br />
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}}. This can also be done by binding a key to {{ic|Terminate_Server}} in {{ic|xmodmap}} (which undoes any existing {{ic|XkbOptions}} setting). <br />
In order for either method to work, one also needs to have {{ic|DontZap}} set to "off" in {{ic|ServerFlags}}; however, from at least version R6.8.0 (year 2004) [https://www.x.org/archive/X11R6.8.0/doc/xorg.conf.5.html] this is the default.<br />
<br />
=== Swapping Caps Lock with Left Control ===<br />
<br />
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:<br />
<br />
$ grep -E "(ctrl|caps):" /usr/share/X11/xkb/rules/base.lst<br />
<br />
=== Enabling mouse keys ===<br />
<br />
[[w:Mouse keys|Mouse keys]] is 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.<br />
<br />
See also [[X keyboard extension#Mouse control]] for advanced configuration.<br />
<br />
=== Configuring compose key ===<br />
<br />
Though typically not on traditional keyboards, a [[Wikipedia:Compose key|Compose key]] can be configured to an existent key.<br />
<br />
The {{ic|Compose}} key begins a keypress sequence that involves (usually two) additional keypresses. Usage is typically either for entering characters in a language that the keyboard was not designed for, or for other less-used characters that are not covered with the {{ic|AltGr}} modifier. For example, pressing {{ic|Compose}} {{ic|'}} {{ic|e}} produces {{ic|é}}, or {{ic|Compose}} {{ic|-}} {{ic|-}} {{ic|-}} will produce an "em dash": {{ic|—}}.<br />
<br />
Though a few more eccentric keyboards feature a {{ic|Compose}} key, its availability is usually through substituting an already existing key to it. For example, to make the {{ic|Menu}} key a {{ic|Compose}} key use the [[Desktop environment]] configuration, or pass {{ic|compose:menu}} to {{ic|XkbOptions}} (or [[#Using setxkbmap|setxkbmap]]: {{ic|setxkbmap -option compose:menu}}). Allowed key substitutions are defined in {{ic|/usr/share/X11/xkb/rules/base.lst}}:<br />
<br />
$ grep "compose:" /usr/share/X11/xkb/rules/base.lst<br />
<br />
If the desired mapping is not found in that file, an alternative is to use [[xmodmap]] to map the desired key to the {{ic|Multi_key}} keysym, which acts as a compose key by default (note that ''xmodmap'' settings are reset by ''setxkbmap'').<br />
<br />
==== Key combinations ====<br />
<br />
The default combinations for the compose keys depend on the [[locale]] configured for the session and are stored in {{ic|/usr/share/X11/locale/''used_locale''/Compose}}, where {{ic|''used_locale''}} is for example {{ic|en_US.UTF-8}}.<br />
<br />
You can define your own compose key combinations by copying the default file to {{ic|~/.XCompose}} and editing it. Alternatively, create an empty {{ic|~/.XCompose}} and include the default one using {{ic|include "%L"}}, for example:<br />
{{hc|~/.XCompose|<nowiki><br />
include "%L"<br />
<br />
<Multi_key> <g> <a> : "α"<br />
<Multi_key> <g> <b> : "β"<br />
<Multi_key> <g> <g> : "γ"<br />
</nowiki>}}<br />
<br />
The compose key works with any of the thousands of valid Unicode characters, including those outside the Basic Multilingual Plane. Take a look at the {{man|5|Compose}} man page, it explains the format of the XCompose files.<br />
<br />
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}}.<br />
<br />
{{Tip|XIM is very old, you might have better luck with other input methods: [[SCIM]], [[Uim]], [[IBus]], etc. See [[Localization#Input methods]] for details.}}<br />
<br />
{{Note|XIM will prevent insertion of Unicode characters with the {{ic|Ctrl+Shift+u}} combination.}}<br />
<br />
=== Currency sign on other key ===<br />
<br />
Most European keyboards have a Euro sign (€) printed on on the {{ic|5}} key. For example, to access it with {{ic|Alt+5}}, use the {{ic|lv3:lalt_switch}} and {{ic|eurosign:5}} options.<br />
<br />
The Rupee sign (₹) can be used the same way with {{ic|rupeesign:4}}.<br />
<br />
=== Switching state immediately when Caps Lock is pressed ===<br />
<br />
Those who prefer typing capital letters with the Caps Lock key may experience a short delay when Caps Lock state is switched, resulting in two or more capital letters (e.g. ''THe'', ''ARch LInux''). This behaviour [[Wikipedia:Caps_lock#History|stems from typewriters]].<br />
<br />
Some more popular operating systems have removed this behaviour, either voluntarily (as it can be confusing to some) or by mistake, however this is a question of preference. Bug reports have been filed on the Xserver bug tracker, as there is currently no easy way to switch to the behaviour reflected by those other operating systems. For anyone who would like to follow up the issue, bug reports and latest working progress can be found at [https://bugs.freedesktop.org/show_bug.cgi?id=27903] and [https://gitlab.freedesktop.org/xorg/xserver/issues/312].<br />
<br />
==== Workaround ====<br />
<br />
First, export your keyboard configurations to a file:<br />
<br />
$ xkbcomp -xkb $DISPLAY xkbmap<br />
<br />
In the file ''xkbmap'', locate the Caps Lock section which begins with ''key <CAPS>'':<br />
<br />
key <CAPS> { [ Caps_Lock ] };<br />
<br />
and replace whole section with the following code:<br />
<br />
key <CAPS> {<br />
repeat=no,<br />
type[group1]="ALPHABETIC",<br />
symbols[group1]=[ Caps_Lock, Caps_Lock],<br />
actions[group1]=[ LockMods(modifiers=Lock), Private(type=3,data[0]=1,data[1]=3,data[2]=3)]<br />
};<br />
<br />
Save and reload keyboard configurations:<br />
<br />
$ xkbcomp -w 0 xkbmap $DISPLAY<br />
<br />
Consider making it a service launching after X starts, since reloaded configurations do not survive a system reboot.<br />
<br />
== One-click key functions ==<br />
To assign an additional one-click function to a modifier key, you can use {{pkg|xcape}}. For example it is possible to have {{ic|CapsLock}} work as {{ic|Escape}} when pressed alone, and as {{ic|Control}} when used with another key. First set the {{ic|Control}} swapping using [[#Swapping Caps Lock with Left Control|setxkbmap]] as mentioned earlier, and ''xcape'' to set the {{ic|Escape}} association:<br />
<br />
$ xcape -e 'Caps_Lock=Escape'<br />
<br />
You can set multiple associations separated with a semicolon, e.g.: {{ic|1=Caps_Lock=Escape;Shift_L=Escape}}.<br />
<br />
If you hold a key for longer than the timeout value (default 500 ms), ''xcape'' will not generate a key event.<br />
<br />
== Adjusting typematic delay and rate ==<br />
<br />
The ''typematic delay'' indicates the amount of time (typically in milliseconds) a key needs to be pressed and held 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''. Note that these settings are configured separately for Xorg and [[Keyboard configuration in console#Adjusting typematic delay and rate|for the virtual console]].<br />
<br />
=== Using xset ===<br />
<br />
The tool ''xset'' can be used to set the typematic delay and rate for an active X server, certain actions during runtime though may cause the X server to reset these changes and revert instead to its ''seat defaults''.<br />
<br />
Usage:<br />
<br />
$ xset r rate ''delay'' [''rate'']<br />
<br />
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):<br />
<br />
$ xset r rate 200 30<br />
<br />
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:<br />
<br />
$ xset r rate<br />
<br />
=== Using XServer startup options ===<br />
<br />
A more resistant way to set the typematic delay and rate is to make them the ''seat defaults'' by passing the desired settings to the X server on its startup using the following options:<br />
<br />
* {{ic|-ardelay ''milliseconds''}} - sets the autorepeat delay (length of time in milliseconds that a key must be depressed before autorepeat starts).<br />
* {{ic|-arinterval ''milliseconds''}} - sets the autorepeat interval (length of time in milliseconds that should elapse between autorepeat-generated keystrokes).<br />
<br />
See {{man|1|Xserver}} for a full list of X server options and refer to your [[display manager]] for information about how to pass these options.<br />
<br />
== See also ==<br />
<br />
* [https://web.archive.org/web/20170825051821/http://madduck.net:80/docs/extending-xkb/ Madduck guide on extending XKB] (archived at Wayback Machine)</div>Kinono