Configuring keyboard layouts in X

From ArchWiki
Revision as of 18:01, 28 October 2008 by Bender02 (Talk | contribs) (initial commit)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


This page should describe howto configure the keyboard settings for X properly, and also some common pitfalls when trying to do so.

Note that this page deals with X only, if you want to set a proper keyboard for the console, you should edit /etc/rc.conf (KEYMAP variable), or you can do it manually with 'loadkeys'.

Setting the layouts: the keyboard section in xorg.conf

Let's do it by example: mine looks like this:

Section "InputDevice"
        Identifier      "IntegratedKeyboard"
        Option          "CoreKeyboard"
        Option          "XkbModel" "thinkpad60" # "pc105"
        Option          "XkbLayout"             "us,sk,de"
        Option          "XkbVariant"    "altgr-intl,qwerty,"
        Option          "XkbOptions"    "grp:menu_toggle,grp_led:caps"
        Option          "XkbRules"              "xorg"
        Driver          "kbd"

The outcome is the following: I have three keyboard layouts available (us, sk and de) with my preferred variants; I can switch cyclically between them by pressing the 'menu' key, and when one of the last two is selected, my caps led is on (obviously, the caps led doesn't show if I have capslock on anymore). Also, the extra multimedia keys on my thinkpad will produce appropriate events.

Now some explanations for the variables:

  • XkbModel: selects the keyboard model. This has an influence only for some extra keys your keyboard might have. The safe fallback is "pc105". But for instance laptops usually have some extra keys, and usually to get them working (without messing up with xmodmap, see below) you can set a proper model. The list of models can be found in /usr/share/X11/xkb/rules/xorg
  • XkbLayout: sets the list of available layouts. The possibilities can be found in /usr/share/X11/xkb/symbols/* (each layout has a file there)
  • XkbVariant: specify variants for each of the layouts given in XkbLayout. For instance, the default sk variant is 'qwertz', so I had to specify 'qwerty' to get the one I wanted. The possibilities for variants can be found in /usr/share/X11/xkb/symbols/<layout> and they tend to have some commentary about what do they actually do. Warning: if you do specify some XkbVariant, you need to have as many commas in it as in XkbLayout, otherwise it may not work. For instance, if I just wanted sk-qwerty, and us and de with their default variants, I need to write 'XkbVariant ",qwerty,"' (notice the commas).
  • XkbOptions: some extras. Here you can specify how do you want to switch the layouts, what led will be used for notification, a special way to enter the euro-sign, etc... For the possibilities, look at /usr/share/X11/xkb/rules/xorg and then for their descriptions in the appropriate file in /usr/share/X11/xkb/symbols/*

What to do when it doesn't work as expected?

First try to narrow down the problem by removing most of the settings, and adding them one-by-one to see when the problem occurs. Make sure that the syntax is correct (ie the commas in 'XkbVariant').

Read the section on xmodmap and xev below for more ways to check what's going on.

If you're still puzzled, try politely asking on the forums, with a good description of the problem, and also the list of things that you tried.

xev and xmodmap

To test what keys generate which keycodes and symbols in X, use the utility 'xev'. Run it in a terminal, and watch what output do you get when you press various keys. This is useful to see 1) what keycode is reported 2) what 'symbol' is currently assigned to it

For instance, when you press 'insert', you should get some keycode (which could depend on your keyboard model), but more importantly, you should see 'Insert' written somewhere. If you get 'NoSymbol', it means that that particular key isn't being recognized properly. For multimedia keys, you should get something like 'XF86AudioPlay', 'XF86AudioNext', etc... [For the possibilities for XF86 symbols, you can look at /usr/include/X11/XF86keysym.h]

What to do when the extra keys don't generate symbols that you want them to generate? The first option is to tweak your XkbModel (see above). If you're sure that you cannot achieve what you want with this setting, 'xmodmap' comes into play.

With xmodmap you can explicitly (re)assign symbols to keycodes. Find out what keycode is generated when you press the desired key with xev, and add it to ~/.xmodmaprc My ~/.xmodmaprc is below:

! browser
keycode 178 = XF86WWW
! mail
keycode 236 = XF86Mail
! file manager
keycode 230 = XF86Documents
! sleep
keycode 223 = XF86Sleep

The exclamation mark denotes comments. Having done this, you let X know your preferences by running 'xmodmap ~/.xmodmaprc'. You probably want this to be executed whenever you start X. Some DEs or WMs do this automatically, for others you need to add manually.

Some applications and window managers automatically react on proper symbols (for instance, when 'XF86AudioStop' is pressed in gnome, it stops audio playback; when 'XF86Back' is pressed in firefox, it goes 'back'), but for others you have to assign actions to it manually. This can be done either in your DE or WM; or you can use 'xbindkeys' - a handy utility designed exactly for this purpose.