The Keyboard Layout Editor

Update Dec 2010: Get the latest version of the Keyboard Layout Editor from

(this entry is a repost, the original was lost in a database mishap.)

As part of the 2008 GSoC program, I worked on a Keyboard Layout Editor for the X.Org Foundation.

The Keyboard Layout Editor (KLE) is an application that allows you to create keyboard layouts for the X.Org server, commonly found in the Linux, OpenSolaris, *BSD, etc Desktops.

My mentor was Sergey Udaltsov, maintainer of xkeyboard-config, the Keyboard Indicator applet in GNOME, supporting libraries for keyboard layouts and much more. I had great help and Sergey was very supportive. Highly recommended mentor for your GSoC’09 project.

The Keyboard Layout Editor showing a layout

The Keyboard Layout Editor showing a layout

The screenshot above shows the main window of the program; a keyboard with blank layout (keys are empty), a section Add to layout with items that can be used to populate the layout, and a section for the description of the layout (Layout details).

There are typically two workflows; first you start off with a blank layout and you add Unicode characters, dead keys, include files, then you save.

The other workflow is to start with an appropriate existing layout as a base, then add more characters, make changes, etc.

It might be strange to talk about different workflows, but in terms of usability it’s important provide assistance for such cases. For example, having tooltips is important when a person starts off with a new layout.

Using the Keyboard Layout Editor

Using the Keyboard Layout Editor

Here we started with a blank layout; we click on Start Character Map, then locate the characters you need, and drag and drop them to the appropriate keys. Each key is composed of four parts, and we number these from 1 to 4. The way we count is quite peculiar,

  1. bottom left, when you press the key as is (key)
  2. top left, when you press the key with Shift (Shift + key)
  3. bottom right, when you press the key with AltGr (AltGr + key)
  4. top right, when you press the key with Shilft+AltGr (Shift + AltGr + key)
Analysis of a key

Analysis of a key

This is my entry to the most engineered diagram competition.

The dead keys relate to diacritic marks such as grave and acute. Since they are too small to see, we present them next to a D letter (D for Dead key). In some cases I could not find a character equivalent to the diacritic mark, so I put ?, therefore it looks like D?. If you put the mouse pointer over the key, you can see the full details in the tooltip.

Including files

Including files

In many cases, there exist layouts/variants that contain most of the characters you want to add. In this case, you add and enable in the Include files section. You can then override any of those characters by dragging and dropping to the layout.

At this stage in the blog post, it is important to clarify the notions of a layout and a variant. The two are quite similar and the distinction is messy when trying to explain to the end-user. The French layout file is fr, which contains several variants (distinct groups of mappings of physical keys to Unicode characters). When you are actually talking about a French keyboard layout, you are actually referring to the default variant of the «fr» file. Oftentimes people refer to the «fr» file as a whole as the French layout. You can also pick a non-default variant of the layout file, and call it your layout.

The way I would like to define layout and variant is this: a layout refers to the default variant of the layout file. This is consistent to the fact that distributions pick the default variant in the settings so it’s what get the most visibility, or when users select a new layout, they are presented with the default setting first. Regarding layouts in general, it is important for different languages/scripts to make effort that the default layout is updated and includes extra useful and relevant characters.

The new Greek keyboard layout

The new Greek keyboard layout

This is the updated Greek keyboard layout, and is the near-final version that we are planning to submit to xkeyboard-config. It adds Greek Polytonic to the existing Greek layout.  It does not make changes to the previous default layout, so users will not be unpleasantly surprised. It also adds all sort of characters that are found in the Greek Unicode block.

In this post I simplified some of the terms/description. If I went a bit too far, please correct me and I’ll update in-place.

Update 8th Sep 08: What are the plans for further development of the layout editor;

  • Increase the user base and get more people trying out the editor. This requires some more cleanup of the code, more instructions on how to run it youselves, and get people to provide feedback. An open-source project without users is not a successful project.
  • Make it easier for developers to contribute on the project. If you use Eclipse, you can install pydev, antlr3ide, mylyn, subclipse, and you can do the full development from within the cozy Eclipse environment. These need documentation.
  • The Issues page at the project has about ten items. This list needs to be reduced.
  • The natural place for users of the layout editor is the mailing list. We need to promote the editor there, and get examples of users actually using it to maintain layouts.
  • An issue that plagues some users is when they need compose sequences to generate characters that no pre-composed forms exist. If users really need this (mainly Latin and Cyrillic scripts, complex scripts), it can be adapted to the UI.
  • It is technically easy to adapt the editor so that it produces XML layouts. Considering the state of XKB-atkins, this may not be a top priority at the moment. libxml2 comes with the MIT license, so in license terms it would be OK. Not sure if it is OK to link libxml2 to the server. It might actually solve the slow parsing of the configurations files and the issues of xkbcomp.
  • At the moment the default geometry is a somewhat generic keyboard. In addition, I deactivated several keys (such as the function keys), in order not to confuse users (you can activate with a small change in the code). The keyboard can be expanded to a full 105-keys style. A related project would be to figure out an efficient way to edit those geometry files, and make the keyboard customised. If people start creating layouts with the editor, they will certainly love to edit geometry files!


  • Anonymus

    This was extremely useful! This should totally be packaged by most distributions. I also think you should make a hassle-free package with the xkb grammar already compiled.

  • Pothik

    Thanks for this software. I have tried it. In my case, it can open existing xkb layouts in my local drive. I can see the layout. But I can not make any change because the “start character map” command button is not working. The dialog box that you have shown in this blog post (2nd figure from top) is not showing. So, no change can be make. Please help.

  • Baagii

    I started blank layout and clicked “Start Character map”, but window is not opened, please help

  • chickendude

    Baagli and everyone else who is having trouble:
    If the “Start Character map” button does nothing, open a terminal and type “gucharmap”. If it doesn’t load up, type “sudo apt-get install gucharmap” and then run “gucharmap” (without quotes). From there, drag-and-drop the characters onto the keyboard in the layout editor.

  • Dimitris Papadakis

    I use Ubuntu10.04. I have Greek Polytonic Keyboard to type Ancient Greek.
    When I type Greek Oxia, the system automatically displays a Tonos!

    The Tonos and the Oxia are not the same, so I have incompatibility with the Perseus.tufts website (one of biggest ancient Greek websites) and ancient Greek spellchecker sees every word I type incorrect, I don’t want to use their online system all the time to do work!

    I tried your keyboard layout editor to change key bindings for dead_acute with U1FFD (Greek Oxia) but the key is not behave dead anymore: when I press it, it outputs Oxia (it should do nothing when pressed, and after I press a vowel it should output vowel with Oxia)


    PLease see similar problem:

  • Chascon

    Ever think of making a .deb available to the Debian/Ubuntu community? I know it would be appreciated.

  • Required

    Yeah, it would be great if this was packaged into common distros. I don’t think Debian has a graphical keyboard layout editor in its repository, and this is by far the slickest one.

  • Marie

    I’ve been trying to use this software to create a new keyboard layout, and have named it ga for Turkish variant ‘Gagauz’ language. Since I am using KDE desktop for Linux, I do not have gucharmap installed. Instead, from command line I open kcharselect and drag and drop letters from it to KeyboardLayoutEditor.

    The c source code file is created, but how do I implement it into kbdz? For instance, I open System settings>Input Devices>Keyboard>Layouts and click “add” but ‘ga’ is not shown anywhere under “Limit selection by Language”, “Layout”, “Variant”, or “Label”. Is there some extra step involved in getting the newly created layout listed in /usr/share/X11/xkb/rules in files such as base.lst and base.xml so it shows under System Settings Keyboard Layout GUI?

    As for the editor, it is easy to use. I can easily remove a key if I make a mistake.
    Regards, Marie

  • prakash

    your program is very good. but i thing it not work on windows platform

  • Dr Dreyeth

    It might open and run on the windows platform (not sure about this), but the keyboard layouts it creates are for linux which I haven’t been able to find a great gui keyboard layout creator for until this project.

    The keyboard layout file it creates when you’re done itsn’t designed for Windows, microsoft has its on graphical keyboard layout creator you can get off their website made for windows.

  • Arashk

    I have downloaded “KeyboardLayoutEditor-3.40.tar.gz” from “”.
    May you help me install it on Xubuntu?

  • timinski

    I have tried to install your utility on Mint but when launching ./KeyboardLayoutEditor I always get:

    Import error: No module named antlr3
    This script requires to have the python antl3 package installed.
    Please see the README file for further instructions.

    I manually installed antlr3 without incident but still get the above error result when launching the toolkit.

    ….any suggestions?

    Thanks kindly for your work and your help!

Leave a Reply

%d bloggers like this: