This is a read-only archive. Find the latest Linux articles, documentation, and answers at the new!


Creating custom keyboard layouts for X11 using XKB

By Michał Kosmulski on June 10, 2004 (8:00:00 AM)

Share    Print    Comments   

In most modern desktop environments there is a small applet that allows users to quickly switch between keyboard layouts when they need to type text in more than one language. However, there are situations where this solution is not quite satisfactory. Some writing jobs (that of a translator, for example) require writing text in which words from several languages are intermixed, which would make frequent switches between keyboard layouts necessary. This is a big inconvenience, even when keyboard shortcuts are used to switch between layouts. Another problem is that the logical keyboard layouts used may sometimes not fit the physical keyboard layout very well, resulting in a confusing setup.

One solution is to use layouts with so called dead keys. This is a way of generating accented characters by first pressing a key which corresponds to the accent (the dead key) and then a letter key (e.g. pressing ~ and then n generates ñ).

This allows you to generate many accented characters using just a few keys, since a dead key need not be a single keystroke but can also be a combination of keys. For example, the backtick key is often used as a dead key and generates four different accents depending on whether it's pressed alone or with combinations of Shift and AltGr (the right Alt key). This is a clever trick, but writing using dead keys is usually less convenient than using a simple combination like AltGr+letter. Dead keys are a good solution for characters that are seldom used, but for characters that need to be typed often, we need a more convenient technique.

KDE Control Center - keyboard layout list

The X Window System used on most Unix-like systems today uses X Keyboard Extension (XKB) for translating keystrokes into character codes. Thanks to XKB's flexibility, one can easily create custom keyboard layouts that can help solve the problems mentioned in the preceding paragraphs. This tutorial describes how to create a custom keyboard layout combining diacritic characters from several standard layouts, thus eliminating the need to switch keyboard layouts while writing. On the right is an image showing the final result: a custom keyboard layout called de_pl, listed together with standard layouts in the KDE Control Center.

Throughout this document I will use a keyboard layout combining Polish and German diacritic characters as an example. Standard layouts for Polish and German are quite different, and switching between them while writing is very inconvenient. The Polish layout is essentially the same as a standard US keyboard, the only difference being Polish diacritic characters (ĄĆĘŁŃÓŚŻŹ) which are generated using AltGr and the corresponding nonaccented letter (AltGr+X is used for Ź). The German layout is radically different, since it is a QWERTZ layout. The differing position of Y and Z alone is enough to make the writer's life really hard. But that's not all: separate keys are reserved for German umlauts ÄÖÜ and ß, causing almost all punctuation and special characters like &, +, /, <, >, etc., to have a different position than in the Polish layout. Writing any text where characters from both languages appears and having to switch between the two layouts is very inconvenient.

Our goal is to create a keyboard layout combining accented letters from both languages that fits well to the physical layout of a German keyboard. Thus we want it to essentially be a German layout (preserving the position of punctuation marks and umlauts as well as of Y and Z) but we want to bind additional AltGr+letter combinations to Polish accented characters.

XKB layouts are defined by text files living in /etc/X11/xkb/. On some systems they may be placed in /usr/X11R6/lib/X11/xkb/ (on my machine, the later is a symlink to the former directory). There are several subdirectories in that folder, but for the simple task of creating a new layout we are interested only in the symbols subdirectory. Root permissions are necessary for most tasks described below, as all configuration files in this directory are owned by root. Note that some of the files we need to edit are read-only even for the superuser, so it may be necessary to change their access permissions before editing (most text editors allow saving read-only files after confirming the operation, though).

Files to describe the basic keyboard layouts are given the names of their language name abbreviations (e.g. de for German). Names such as ge_la are used for keyboard variants (la (Latin) variant of the ge (Georgian) keyboard). Thus, in order to follow this convention, we use de_pl for our new keyboard layout instead of e.g. depl. Using this naming scheme is not mandatory -- the layout would also work under another name -- but recommended. Some applications, such as the KDE Control Center, also rely upon this naming scheme in order to assign icons (national flags) to keyboard layouts.

We go to the /etc/X11/xkb/symbols/pc/ directory (if a non-PC keyboard model is to be used, all actions should be performed in /etc/X11/xkb/symbols/ instead) and copy the file de to de_pl in the same directory.

Let's make some modifications to our new layout. Open de_pl in a text editor and find the section that assigns character codes to keys. It should look similar to this (only a small part is quoted here for brevity):

    key <AE02> { [         2,   quotedbl,    twosuperior,      oneeighth ] };
    key <AE03> { [         3,    section,  threesuperior,       sterling ] };
    key <AE04> { [         4,     dollar,     onequarter,       currency ] };
    key <AE11> { [    ssharp,   question,      backslash,   questiondown ] };
    key <AE12> { [dead_acute, dead_grave,   dead_cedilla,    dead_ogonek ] };
    key <AD03> { [         e,          E,       EuroSign,       EuroSign ] };
    key <AD06> { [         z,          Z,      leftarrow,            yen ] };
    key <AD11> { [udiaeresis, Udiaeresis, dead_diaeresis, dead_abovering ] };
    key <AD12> { [      plus,   asterisk,     dead_tilde,    dead_macron ] };
The meaning of these lines is obvious -- they assign characters to key positions on the keyboard. For example <AE03> means the third alphanumeric key in the fifth row (the letters A, B, etc., denote key row numbers counted from the bottom of the keyboard). Special keys have their own names -- e.g. <ESC>, <TAB>, <RTRN> etc. Character names are usually self-explanatory and in most cases identical or very similar to Unicode names. A complete list of all available character names can be found in file /usr/X11/include/X11/keysymdef.h in the form of constant definitions for C programs.

Each line of the form #define XK_xyz corresponds to the character name xyz that can be used in keyboard layout definition files. However, usually it is easiest to just copy some lines directly from other keyboard layouts (in this case, from file pl, which defines the Polish layout). The four character names assigned to each key are characters generated when the key is pressed alone, with the Shift key pressed, with the Multi_key key (which is defined to be AltGr in this layout) pressed, and with both Shift and Multi_key pressed, respectively.

We can change the characters assigned to some keys. For example, we can use AltGr+Z to generate the character Ż (lower/uppercase depending on Shift state) instead of a left-pointing arrow and the yen symbol by changing the corresponding line to:

    key <AD06> { [         z,          Z,    zabovedot,    Zabovedot ] };
In a similar manner, we can add or modify the corresponding characters' descriptions to get all the other Polish characters. (Ł is bound to AltGr+L in the German layout already so there's no need to add it.):
    key <AD03> { [         e,          E,      eogonek,      Eogonek ] };
    key <AD09> { [         o,          O,       oacute,       Oacute ] };
    key <AC01> { [         a,          A,      aogonek,      Aogonek ] };
    key <AC02> { [         s,          S,       sacute,       Sacute ] };
    key <AB02> { [         x,          X,       zacute,       Zacute ] };
    key <AB03> { [         c,          C,       cacute,       Cacute ] };
    key <AB06> { [         n,          N,       nacute,       Nacute ] };
As the last touch, we bind the euro sign to AltGr+5, since the original AltGr+E binding is used for Ę now:
    key <AE05> { [         5,    percent,     EuroSign,     EuroSign ] };
This makes our new keyboard layout description complete.

The last step is letting X know that a new layout was added. The file /etc/X11/xkb/rules/xfree86.lst contains a list of available layouts together with their descriptions. Adding the below line:

    de_pl      German (with Polish characters)
makes our newly created layout usable in X. If you want to make the new layout the default (which is probably the case), edit /etc/X11/XF86Config (sometimes /etc/X11/XF86Config-4 is used) and modify the InputDevice section for your keyboard to contain the line:
    Option "XkbLayout" "de_pl"
After modifying these files, restart the X server by pressing Ctrl+Alt+Backspace. The new layout should now be loaded if you made it the default in XF86Config. If not, you can select it from the list of layouts in your favorite keyboard layout switching applet.

See an updated version of this article at the author's Web site.

Share    Print    Comments   


on Creating custom keyboard layouts for X11 using XKB

Note: Comments are owned by the poster. We are not responsible for their content.

Re:This simply doesn't work...

Posted by: Anonymous Coward on January 20, 2005 02:00 AM
Strange, I can't find your bugreport at
<A HREF="" title=""></a>


Re:This simply doesn't work...

Posted by: Anonymous Coward on April 28, 2005 12:37 PM
grr... given up and moved to xp. cmon, my fellow countryman, why do you do this?!<nobr> <wbr></nobr>... anyways.
you can simply set the korean keyboard locale with the<nobr> <wbr></nobr>/usr/local/profile.d/ the file in there.
then u can use nabi to switch between english and korean typeset. it took me a while to figure it out. its cause a lack of documentation.


Re:This simply doesn't work...

Posted by: Anonymous Coward on June 17, 2006 02:29 AM
It didn't work for me either. I just wanted to
replace the top row of digits from my keyboard
with accented characters. I don't need 2 ways
to input numbers when this means no 1-key 1-stroke
way of inputing accented characters.

I started by copying the us file, then saving it
as us_fr. The control center accepted us_fr. I
rebooted: still no accents.

I ended up discovering their were MANY files
describing the keys, and changing them all.
Saving them under their original names, too.

This worked for SOME accents. The slanted ones.
I still don't have ocirc, ecirc, euml, etc, but
I have eacute, egrave, agrave and ugrave. Better
than nothing I supposed.

Why it worked for some characters and not for
the others is a deep mystery.

Mariane _aatt_ no-log _ddott_ org, if ever some very
kind person could tell me...


lower back pain

Posted by: Anonymous Coward on May 28, 2006 07:11 PM
[URL=] Pain relief [/URL]

  [URL=] Back Pain [/URL]

  [URL=] Pain relief [/URL]
[URL=] Pain relief [/URL]
[URL=<nobr>.<wbr></nobr> htm] Nerve pain relief [/URL]


This simply doesn't work...

Posted by: Administrator on June 10, 2004 05:21 PM
This article is misleading. I've been struggling for years to be able to type Korean (needs an IMM), Greek, and French under a French locale. This simply doesn't work.

For Korean, it simply doesn't work. There's no Korean choice in the KDE Control Center, which is at the least surprizing for such an important language.

For other languages, it may work for native KDE applications, but doesn't work for most other application one uses for everyday work: OpenOffice, Mozilla, etc.

From what I've heard, this is a fundamental bug in X11. A typical symptom is that you can't use a Korean IMM under a non-Korean locale. It seems Gnome try to work around the problem by introducing their own IMMs at the Gnome level. But this looks like a bad hack, adding yet another layer and more complexity to X11 graphics systems. KDE doesn't seem to be using its own IMMs yet.

Maybe this doesn't make much sense, as I didn't have much time to look into the technical details. But as a user, it was a frustrating experience, and certainly not as easy as this article implies.

I've given up and moved to Windows XP.


Re:This simply doesn't work...

Posted by: Administrator on June 11, 2004 01:43 AM
I have no experience with Korean language, however on my current system it does seem that the Korean keyboard layout is indeed broken. There is a reference to the Korean layout in<nobr> <wbr></nobr>/etc/X11/xkb/rules/xfree86.xml and<nobr> <wbr></nobr>/etc/X11/xkb/rules/xorg.xml (I'm running 6.7.0) and Korean layout is shown in KDE (3.2.2) but the description file "ko" which is referenced seems to be missing. So it's quite possible that this procedure doesn't work for the Korean layout since this layout itself is broken. But this does not mean that the article is "misleading". The procedure described here works for the layouts I used and for any layouts which are not themselves broken.


ravindra mudumby--Creating custom keyboard layouts

Posted by: Administrator on June 25, 2005 10:32 AM
XKB is a very powerful system for controlling keyboard layouts on your Linux machine. I do not know how old it is, Jon says it works in Xfree 4.3 as well, but I have only tried it in xorg. It will allow you to set up something like what I have on my computer: my standard qwerty keyboard can switch to Dvorak layout by pressing both shift keys at the same time, and switch back the same way. My scroll lock LED comes on when I am in Dvorak mode, and my caps lock key is now a third control key.

Unlike user xmodmap files, this will affect all users on the system, so avoid doing anything too weird if others use your computer. Also, you need root access to do this, as you will obviously be editing your X configuration scripts.

This is the relavent section of my<nobr> <wbr></nobr>/etc/X11/xorg.conf with the parts I was talking about in the meeting today. The comments I have added should help anybody that wants to try this out. The complete listing and description of various keyboard models, keyboard layouts, and XKB options can be found in<nobr> <wbr></nobr>/etc/X11/xkb/rules/xorg.lst

This should work in newer versions of xfree as well, if you are using that, replace xorg with xfree86 where nessicary and it should work.

If you look around in<nobr> <wbr></nobr>/etc/X11/xkb you should be able to figure out how to create your own rules, and modify existing options and such. For example,<nobr> <wbr></nobr>/etc/X11/xkb/rules/xorg specifies what each group switching option does in terms of scripts in<nobr> <wbr></nobr>/etc/X11/xkb/symbols/group. You can edit this to make your own group switching rules, such as to hit the right windows key, left alt, and right shift to toggle keyboard layouts.


Creating custom keyboard layouts for X11 using XKB

Posted by: Anonymous [ip:] on December 03, 2007 05:48 PM
no comment


Creating custom keyboard layouts for X11 using XKB

Posted by: Anonymous [ip:] on February 06, 2008 12:10 AM
This is great and all, but how would one go about creating their own custom character set? I would be more than willing to try this, if there were any way to create my own character set. This article is about the furthest I've ever gotten. If you have any idea, or any suggestions, please feel free to let me know.


This story has been archived. Comments can no longer be posted.

Tableless layout Validate XHTML 1.0 Strict Validate CSS Powered by Xaraya