Writing keyboard layout for xorg – Notes

· Matti

I had a privilege to be the first person in universe to implement Skolt Sami keyboard for Linux. I had two references:

The job was pretty straight-forward: change the keyboard combinations in the file.

Keycodes

The idea of xkb file is to translate keycodes to characters. The first step is to identify the keys in the keyboard. Each key produces its own keycode. For a start I used Figure 2 in this documentation to get an idea ofo the keycodes. However, my keyboard layout (and the documented Sami layout) differed from fig 2.

To get a keycode for a key:

$ xev -event keyboard

KeyRelease event, serial 28, synthetic NO, window 0x2200001,
 root 0x12d, subw 0x0, time 85909731, (-350,-52), root:(244,267),
 state 0x0, keycode 38 (keysym 0x61, a), same_screen YES,
 XLookupString gives 1 bytes: (61) "a"
 XFilterEvent returns: False

The xev utility gives you the keycodes but this code cannot be used as such in your xkb definitions where the keys are identified with a hex tuplet (e.g. AC01) or a tag (e.g. LSGT). To get your xkb-compliant key identifier:

$ xkbcomp :0 keyboad-mapping.txt
$ grep 38 keyboard-mapping.txt
 <AC01> = 38;
 <PROP> = 138;
 <I238> = 238;
 key <I238> { [ XF86KbdBrightnessUp ] };
 { [ 38, 18 ] },
 left= 382;

Wow! Now I know that A in my keyboard -> keycode 38 -> AC01 in xkb definition.

Characters not defined in keysymdef.h

Most of the xkb howtos I browsed explained that all the symbols are defined in the keysymdef.h. Well, that wasn’t the case with Sami characters. Instead of using the defined keyboard symbols I had to use Unicodes. Say we want to implement Đ character.

  1. If possible, try to get the character to a clipboard. I ended up using Windows implementation to get all three different hyphens right.
  2. Go to http://www.utf8-chartable.de/unicode-utf8-table.pl and locate the character there. This evil beast was hiding in the page “Latin Extended-A”.
  3. Get the Unicode code point (for Đ it is U+0110) which can be used in the xkb definition (“U0110”).

When implementing my second keyboard layout I found a search tool which helped me a lot in finding exotic characters. Workflow:

  1. Start a Windows with selected keyboard layout in a virtual machine. Start a Notepad.
  2. Push a key to see what character appears to the notepad. Copy and paste it to search tool.
  3. The Unicode number can be entered directly to the keyboard definition but I tried to find the symbol from the keysymdef.h whenever I could. It makes keyboard definition file more readable.
  4. Repeat with Shift+Key, AltGt+Key and Shift+AltGr+Key.

VoidSymbol

To avoid strange characters appear when you type the undefined combinations use “VoidSymbol”. So if you define keys like this:

 key <AC01> { [ a, A ] };
 key <AC02> { [ s, S ] };

and press AltGr+A or AltGt+Shift+S you might get some random characters To avoid these chars use VoidSymbol to make sure that no definions are inherited (or whatever neat feature causes this):

 key <AC01> { [ a, A, VoidSymbol, VoidSymbol ] };
 key <AC02> { [ s, S, VoidSymbol, VoidSymbol ] };