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!

Permanent link to this article:


1 pings

Skip to comment form

  1. Hi
    I have downloaded your software.
    I think it would be a nice stuff. I will try it.
    Thank you.

    • walter on July 17, 2009 at 15:53
    • Reply

    thank you for your project, i will try it

    • Anonymus on September 13, 2010 at 02:13
    • Reply

    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 on December 3, 2010 at 02:36
    • Reply

    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.

  2. Pothik: You probably do not have GNOME installed. The button simply starts Character Map, /usr/bin/gucharmap
    What you can do is simply install the ‘gucharmap’ package and start ‘gucharmap’ manually.

    The latest version of the program is available from

    • SAWSD on December 12, 2010 at 04:24
    • Reply

    I download the soft and install bot not open. How to open this soft? I am using ubuntu 10.10

    • Baagii on January 7, 2011 at 17:09
    • Reply

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

    • chickendude on June 1, 2011 at 10:11
    • Reply

    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 on June 29, 2011 at 05:41
    • Reply

    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 on October 30, 2011 at 06:48
    • Reply

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

    • Required on November 13, 2011 at 20:20
    • Reply

    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 on September 1, 2012 at 16:07
    • Reply

    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 on May 1, 2013 at 14:22
    • Reply

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

    • Dr Dreyeth on April 4, 2014 at 21:59
    • Reply

    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 on January 3, 2017 at 09:02
    • Reply

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

  3. 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!

  4. Appologies: I should have mentioned: Mint 18.1 Cinnamon. Sorry about that.

    • Sigour on June 2, 2017 at 10:56
    • Reply

    Excuse me, but when trying to use the kle, Start Character Map does nothing. How can this be possible? How can I fix it?

  5. I can’t assign backslash character to any key at all… When I try, the key section where I drag the gliph keep being empty. Maybe there’s some escape (‘\’) who interferes?

  6. Hello! I tried to install your Keyboard Editor in Ubuntu; I followed all the steps here:

    but I got stuck when launching it, that is, when running the command: ./KeyboardLayoutEditor

    the terminal answer is:
    A generated source file by ANTLR was not found.
    See the README on how to generate.
    Import error: No module named XKBGrammarLexer

    I have searched for information on XKBG grammar lexer but I did not get any consistent answer.
    Could you tell me what I need to do to run your Keyboard Editor?

    Thank you very much!

  7. Hello, Simos

    Your code seems to be just what I need to fix my layout, but unfortunately I can’t get it to work. Admittedly I’m a newbie when it comes to Linux but I do know a few things about programming.
    Problem is, I followed all steps mentioned in GitHub, but launching the program came up with an error:
    The Python bindings for libxml2 were not found: No module named lxml
    My system is Linux Mint 19.1 x64 with a lot of updates from Ubuntu Eoan. All libxml2 files are installed according to Synaptic, except for -dbg and -doc.
    Could you please help with this issue? Thank you in advance.

    Apologies if this is a duplicate, didn’t get any reaction from WP/site on my previous comment, thought it may have gotten lost; please feel free to delete this comment if needed.

    1. To answer my own query: there were several packages missing from the system. After someone hinted that it should’ve been python-lxml what I was looking for I started looking for missing packages. Installing them one by one according to the errors received during attempted installation of Keyboard Layout Editor I found out what was missing from my system; for anyone else in a similar situation: your mileage may vary, so please read carefully the error messages in the terminal and try to find what’s missing.
      So, what I had to install before the application actually started was:
      – python-lxml
      – python-setuptools
      – python-setuptools-git
      – python-wheel
      – python-wheel-common
      – python3-wheel

      I hope this could be of help to others. Good luck!

  1. […] found Simos Xenitellis’ Keyboard Layout Editor here, with the code here. To install on Ubuntu 12.04, you need Java installed. The simplest way of […]

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.