Keyboard layouts

Keyboard layouts are .json files containing a list of keys to form the on-screen keyboard. You can quickly switch layouts by navigating to the userData/keyboards folder and clicking/tapping a layout file on the filesystem display, but you will need to edit your settings file to make any change permanent.

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. altshift_
3. alt_
4. ctrl_
5. shift_

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

When a special key (Shift,Control,Alt...) is in use, the matching prefixed cmd property will be used. If multiple special keys are active and the key has multiple matching prefixed properties, the "most important" one will be used.

There is also and additional prefix capslck_ that will replace the shift_ property if the shift command is locked (caps-lock). It is mostly used to allow typing uppercase diacritics like "É".

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

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"
}

Modifiers

To write special latin characters such as "ô" or "Ë", greek letters or other specific characters, the keyboard parser understand some escape sequences as "modifiers" that will trigger the next key to be mapped to a different character subset:

• ESCAPED|-- CIRCUM
• ESCAPED|-- TREMA
• ESCAPED|-- ACUTE
• ESCAPED|-- BREVE
• ESCAPED|-- CARON
• etc... (about 13 modifiers available at time of writing)

Please refer to the source file to see available modifiers.

Icons

The layout parser supports placing icons instead of text on the keys, by using an ESCAPED|-- ICON: (icon name) command in the key's name property.

Currently icon support is limited to arrows (ARROW_UP, ARROW_DOWN, ARROW_LEFT and ARROW_RIGHT).

Icons are hard-coded into the parser.