„US International” keymap with Esperanto characters support for Haiku operating system

Esperanto is the most popular planned language, with, according to different estimations, from 2 to 10 millions of users worldwide. Haiku operating system comes „out of the box” with the special Esperanto keymap, which supports all Esperanto’s six accented letters — five combined with „circumflex” (ĉ, ĝ, ĵ, ĥ, ŝ) and one combined with „breve” (ŭ). This Esperanto keymap can be used as the primary system keymap, or it can be added with several others into the Keymap Switcher:

This Esperanto keymap is provided with the Haiku operating system

However, it has a serious flaw — in order to type letters that present in English alphabet, but not in Esperanto one, (like q, w, x), „Option” key („Windows” key at the Win-oriented keyboards) has to be pressed:

With the „Option” key pressed, the user can enter additional Latin letters like x, y, q and other useful symbols.

Alas, English is much more popular and useful than Esperanto. Therefore, in order to chat in Esperanto from Haiku, the user would have to set up one of the standard keymaps based on the English language, and additionally use the Esperanto keymap as a backup, alternative, useful only in rare circumstances. Now, I personally use also the Russian keymap, which expands the list of keymaps to three, one of which is going to be used significantly less often.

In the Windows world, the solution was found. It’s a small freeware utility named Tajpi. When Tajpi is active, typing the „caret” symbol („^”) after a letter which can be accented in Esperanto replaces both the unaccented letter and the caret with the accented letter: c+^ will become ĉ, g+^ — ĝ, u+^ — ŭ etc.. This easy and simple solution is convenient enough, therefore I decided to implement something like this in Haiku.

Well, Haiku allows creating a straightforward analog of Tajpi; this is a so-called „input method”. An input method is a special plug-in for the input subsystem of Haiku which constantly monitors all user’s input and has the ability to replace parts of the text the user enters, based on the characters’ sequence typed by the user. However, this task promises to be tricky and underestimated, and I needed a quick solution, therefore I decided to use the „dead keys” instead. „Dead keys” are keys which don’t produce a character on their own; instead, they modify the character that follows them.

„Dead keys” were invented especially for typing out characters with diacritical marks. On mechanical typewriters, a „dead key” typed the diacritical mark, but left the carriage in place (hence the „dead”). The next letter is typed at the same place where the diacritical mark already exists. As a result, the paper is bearing the letter with combined diacritical mark.

The difference between the Tajpi method and the „dead keys” method is in the sequence of actions: in Tajpi one first types the letter, and then the modifier; in „dead keys” the modifier precedes the letter. In other words, Tajpi feels more like writing with pen and paper, and „dead keys” gives feel of using a typewriter. I personally prefer Tajpi’s modus operandi; however, beggars can’t be choosers.

Well, I’ve decided to create a keymap for Haiku which should be based on US International keymap, but should also support special Esperanto accented letters by the means of „dead keys”.

Creation of the modified keymap

First things first, I used the command-line utility keymap and transformed the original „US International” keymap into a text file:

Here is the command that dumps the keymap into a text file, and the contents of this text file.

As you can see, the text file consists of the key map (d’uh, that’s how „keymap” got its name) and keys’ scancodes. I am not going to touch anything but of the „dead keys” sections, so let’s take a look at it:

Here is the list of keys that can be modified using the circumflex, and scancodes of the results. The text highlighted in pink means that in order to activate the circumflex „dead key” one must hold Option and type caret symbol, which is Shift+6; which means that two modifier keys are being pressed simultaneously, Option and Shift.

Since no other letter which can be accented with the circumflex interests me, I delete this entire section and replace it with a new one. I’m using the „Character Map” program in order to obtain the correct scancodes:

„Character Map” program UI. One of the Esperanto accented letters is highlighted, and its scancode appears in the last line, right after the words “UTF-8”. I’ll just throw away both \x-s and add 0x in front of the scancode.

Yes, I remember that one of the letters („u”) is accented not with a circumflex but with breve, but I still add it to the circumflex section.

I must add two variants for every letter, uppercase and lowercase. Therefore, additional support of six letters means adding twelve lines to the file. Finally, the file looks like this:

The „circumflex” section contains only Esperanto letters. The first letter in that section is capital Ĉ with circumflex; its code is 0xc488, just what the previous screenshot shows.

When the editing is over, the text file has to be compiled back into a keymap file. This is what the command-line utility keymap is for:

The keymap utility took the modified text file with the key mapping ~/keymap.txt and compiled it into a binary, which was finally placed in /boot/home/config/settings/Keymap/US-Esperanto.

Actually, Haiku searches for the keymaps in only two folders:

  1. /boot/system/data/Keymaps — at this place all system keymaps are stored. This is the source from where I obtained the US International keymap in the beginning of this article.
  2. /boot/home/config/settings/Keymap — this is the place for the user to store his modified keymaps.

Please note that the first entry has „Keymaps” in plural, and the second has „Keymap” in singular!

Since the user doesn’t have the write access to the system folders anyway, consequences are obvious: the newly created „US-Esperanto” keymap will go to the second folder. Now, let’s check the results of this experiment!

Testing and verification

There is a new option in the bottom-left part of the already familiar GUI utility Keymap: the „User” keymaps list contains the US-Esperanto keymap. Let’s click it once in order to activate it. Now, if we press simultaneously „Option” and „Shift”, the possible „dead keys” will be highlighted in blue:

While simultaneously holding Option and Shift keys, the user can press one of three different characters in order to activate one of the „dead keys”: tilde, caret and diaeresis. The two other „dead keys” are invoked without „Shift”.

Now, let’s open a text editor, invoke the caret „dead key” by pressing Option+Shift+^ and type one of the six letters added to the keymap, either upper or lowercase. The result is satisfying:

The Esperanto sentence contains accented letters with circumflex (colored dark blue) that I’ve typed without switching from the modified US International keymap.

Hooray! Now, I’m adding this modified keymap as the primary system’s keymap in the Keymap Switcher by dragging it from the bottom of the lower list of available keymaps into the top of the upper list of selected keymaps:

From now on the US International keymap with Esperanto characters support will be the primary, and the Russian keymap will be the secondary. Switching is performed via Ctrl+Shift.

In the following article I’ll describe the process of creating a package of this keymap in order to distribute it through the Haiku’s package management system.

Source code available here: https://github.com/ahitech/US_International_Esperanto-keymap/releases