Adding new keyboard layouts

Warning: I'm currently in the middle of a refactoring that will replace the current complex XML layout definitions with simple text files. If you're thinking about starting work on a layout based on the instructions below, you may want to wait for the new system - see issue 13.

It's very difficult for me to create and test keyboard layouts for languages I can't read or write. Help in improving support for additional languages would be very much appreciated.

Please let me know if you can contribute a keyboard layout for a not-yet-supported language. Feel free to contact me before starting work on it to avoid duplicated effort.

Limitations

• Currently Hacker's Keyboard doesn't support dead keys (this is on my TODO list, see  issue 39 ).
• It treats "shift" as equivalent to "caps lock" (some layouts expect different mappings for these two modes).
• There's no support for languages needing more glyphs than can be fit reasonably on a keyboard, such as Chinese. I don't plan to add complex input methods, that's beyond the scope of this project.

Overview

There are three parts needed for fully supporting a new layout:

• a 4-row layout, used on phones in portrait mode
• "alternates" definitions used to populate the long-press popup mini-keyboard contents
• a 5-row layout, used for tablets, or in landscape mode

The 4-row keyboards each have a kbd_qwerty.xml file defining the key configuration and characters, for example kbd_qwerty.xml for the German QWERTZ layout. If a language doesn't currently have a 4-row layout, that would need to be adapted and added.

The per-letter alternate characters shown in long-press popups are based on a language-specific donottranslate-altchars.xml file. This includes the digits shown in the top row of the 4-row keyboard.

The 5-row keyboard layouts are configured separately from the standard Gingerbread 4-row keyboards.

The core 5-row layout is defined in the kbd_full.xml file, it defines key sizes and positions but not the characters shown on each key, so it should not need to be modified by language. The character mappings are defined per language in the donottranslate-keymap.xmlfile, assigning characters for each key position.

Examples for the language-specific mappings:

• English QWERTY 4-row layout, 5-row keymap and altchars
• German QWERTZ 4-row layout, keymap and altchars
• Russian 4-row layout, keymap

Editing the keymap.xml file

To create a 5-row keyboard layout, assign the main, shifted, and alternate characters for each key location. You can define the alternate characters directly in the file, or (recommended for Latin alphabet languages) indirectly via the altchars file.

Example for a key definition:

    <string name="key_ae04_main">4</string>
    <string name="key_ae04_shift">$</string>
    <string name="key_ae04_alt">4$£€¥</string>

The result is as follows:

    Main map:  "4", alternates "$£#¥"
    Shift map: "$", alternates "4£#¥"

Key "ae04" is the 4th key from the left in the 5th row ("e") of a typical PC layout.

Here's an example for a letter with indirectly specified alternates:

    <string name="key_ad03_main">e</string>
    <string name="key_ad03_shift">E</string>
    <string name="key_ad03_alt">@string/alternates_for_e</string>

The alternates_for_e string reference uses this entry in donottranslate-altchars.xml:

    <string name="alternates_for_e">3éèêëē€</string>

The first alternate character gets drawn as a hint on the key if that's configured in settings.Repeat the main and shift characters as the first two alt characters, this helps ensure that the long-press popups contain consistent equivalents in both the main and shifted layouts. Redundant characters get removed automatically when initializing the layout, including removing digits from alternates for 5-row layouts which have a separate number row.

After the first two characters, list the remaining alternate characters (if any) in order from most frequent to least frequent. They will be reversed and drawn right to left on keys in the right half of the keyboard. (This is different from the original Gingerbread AOSP behavior.)

For letters, you can use @string/alternates_for_X to refer to predefined lists from values/donottranslate-altchars.xml or your localized values-ZZ/donottranslate-altchars.xml as appropriate. This is optional, if it's a non-Latin layout it's easier to just include the alternates directly for each key.

Use backslash escapes and XML entities as follows:

     &  ->  &
     <  ->  &lt;
     >  ->  &gt;
     \  ->  \\
     @  ->  \@
     ?  ->  \?
     '  ->  \'
     "  ->  \"

Don't include dead keys intended for accents or other diacritics, they don't work in the keyboard's input logic. This includes ´ ACUTE ACCENT, ¨ DIAERESIS, ¸ CEDILLA. Instead, add the precomposed letters such as è where appropriate.