Keyboard layouts

Keyboard layouts are .json files containing a list of keys to form the on-screen keyboard.

Keyboard layout codes

Keyboard layouts are identified by a code with the format language-REGION*, eg: en-US for American English.

A "valid" code is any provided layouts' filename (without the .json extension), and/or the name of any user-provided layout you might have copied in the userData/keyboards folder.

---

*In practice, this rule is not enforced.

Keyboard layout structure

The layout is organized by rows (see below). Each row contains an array of keys that will be parsed in order by keyboard.class.js, from left to right.

{
    "row_numbers": [],
    "row_1": [],
    "row_2": [],
    "row_3": [],
    "row_space": []
}

Each key contains name and cmd properties, and sometimes prefixed name and cmd properties. Valid prefixes are:

1. fn_
2. alt_
3. ctrl_
4. shift_

shift_ is the "less important" prefix, and fn_ the "most important".

When the keyboard is in a "special" state - when a key like Shift, Control or Alt is pressed - the correctly prefixed property is used. If that property doesn't exist, the next available property is used, following the importance order.

name is the text to display on the key, and cmd is the sequence to send to the shell.

There is an additional property useful on latin keyboards with accents: capslck_cmd. It allows for instance to type a "É" character on the French keyboard.

Since sequences for special keys like delete, enter, or control+A are invalid JSON characters, special ~~~CTRLSEQx~~~ sequences (where x is an integer from 1 to 21) are used instead. They are replaced by the correct UTF8 character by the parser. The list of all CTRLSEQ characters is on the fifth line of keyboard.class.js. You might need a special text editor to see them correctly.

Another type of parsed sequences are ESCAPED|-- commands. They are not forwarded to the shell and instead trigger special actions on the keyboard, eg: ESCAPED|-- SHIFT: LEFT.

Here is a key example:

{
    "name": "r",
    "cmd": "r",
    "shift_name": "R",
    "shift_cmd": "R",
    "ctrl_cmd": "~~~CTRLSEQ8~~~",
    "alt_cmd": "~~~CTRLSEQ1~~~r"
}

About latin diacritics

To write special latin characters such as "ô" or "Ë", the keyboard parser understand the following escape sequences:

• ESCAPED|-- CIRCUM
• ESCAPED|-- TREMA

When triggered, the next character will be converted to its diacritic variant (if there is one). Currently support for diacritics is limited to what's useful to the French keyboard.