Skip to content

Layouts

Jump to bottom Edit New page
Adam Spiers edited this page Dec 7, 2024 · 15 revisions

How do I add or edit layouts in the app?

See https://github.com/Helium314/HeliBoard/wiki/Customization#layouts.

What a JSON file looks like for Heliboard?

  • The JSON file:

    • It always starts with the left square bracket [ and always ends with the right square bracket ]

  • The rows:

    • Each row of the keyboard must be written between 2 square brackets: [ and ], ; note that the last square bracket has a comma at the end, which signifies the end of editing the row
    • The last row always ends with the right square bracket ] without the comma which means no more rows added

  • The labels:

    • Each label always must be written between 2 curly brackets: { and }, ; note that the last curly bracket has a comma at the end, which signifies the end of editing the label
    • The last label always ends with the curly bracket } without the comma which means no more labels added

Note that lines starting with // are ignored.

Click to see the main structure of a JSON file 
[
// FIRST ROW
 [
  { "label": "a" },
  { "label": "b" }
 ],
// SECOND ROW
 [
  { "label": "c" },
  { "label": "d" }
 ],
// LAST ROW
 [
  { "label": "e" },
  { "label": "f" }
 ]
]

Label properties

Each label can have the following properties:

  • type: only specific values, HeliBoard mostly uses this to determine background color and type, determined automatically by default

    • normal: normal key color
    • function: functional key color
    • space: space bar color
    • action: action key color
    • unspecified: no background color
    • placeholder: no background color, no label, and pressing the key does nothing
    • numeric: normal key color, only in number layouts: sets default width to -1 and sets default label flags if none specified

  • width: width of the key in units of screen width, e.g. a key with "width": 0.1 has a width of 10% of the screen, defaults to 0

    • A special value is -1, which means the key expands to the available space not already used by other keys (e.g. the space bar)
    • 0 is interpreted as follows:
      • -1 on the space key in alphabet or symbols layouts, and for keys with "type": numeric in number layouts
      • 0.17 for number layouts
      • 0.1 for phones
      • 0.09 for tablets
    • If the sum of widths in a row is greater than 1, keys are rescaled to fit on the screen

  • popup: list of keys to add in the popup

    • Note that in popup keys, properties are ignored with the exception of $, code, codePoints, and label
    • When specifying a selector key class in a popup key, it will be evaluated correctly (e.g. for changing popups dependent on shift state)
    • If popups are added to repeating keys (e.g. delete, arrow keys), repetition will be disabled

  • code: code point that is entered when the key is pressed, determined from the label by default

    • There are special negative values available, e.g. the ones used by functional keys
    • Special notes for the modifier keys CTRL, ALT, FN, META:
      • Currently there is no special lock-treatment, so you need to hold the key and press another key at the same time (like on a hardware keyboard)
      • This means you should avoid putting popups on modifier keys (or press the other key quickly)

    Click to see available codes
    CODE NAME CODE VALUE CODE NAME CODE VALUE CODE NAME CODE VALUE CODE NAME CODE VALUE
    CURRENCY_SLOT_1 -801 ARROW_LEFT -21 SYMBOL_ALPHA -10001 MEDIA_PLAY_PAUSE -10022
    CURRENCY_SLOT_2 -802 CLIPBOARD_COPY -31 START_ONE_HANDED_MODE -10002 MEDIA_NEXT -10023
    CURRENCY_SLOT_3 -803 CLIPBOARD_PASTE -33 STOP_ONE_HANDED_MODE -10003 MEDIA_PREVIOUS -10024
    CURRENCY_SLOT_4 -804 CLIPBOARD_SELECT_ALL -35 SWITCH_ONE_HANDED_MODE -10004 VOL_UP -10025
    CURRENCY_SLOT_5 -805 CLIPBOARD_SELECT_WORD -34 SHIFT_ENTER -10005 VOL_DOWN -10026
    CURRENCY_SLOT_6 -806 TOGGLE_INCOGNITO_MODE -244 ACTION_NEXT -10006 MUTE -10027
    VOICE_INPUT -233 TOGGLE_AUTOCORRECT -245 ACTION_PREVIOUS -10007 F1 -10028
    LANGUAGE_SWITCH -227 MOVE_START_OF_LINE -27 NOT_SPECIFIED -10008 F2 -10029
    SETTINGS -301 MOVE_END_OF_LINE -28 CLIPBOARD_COPY_ALL -10009 F3 -10030
    DELETE -7 MOVE_START_OF_PAGE -25 WORD_LEFT -10015 F4 -10031
    ALPHA -201 MOVE_START_OF_PAGE -26 WORD_RIGHT -10016 F5 -10032
    SYMBOL -202 SHIFT -11 PAGE_UP -10010 F6 -10033
    CLIPBOARD -213 MULTIPLE_CODE_POINTS -902 META -10012 F8 -10035
    CLIPBOARD_CUT -32 UNSPECIFIED 0 TAB -10014 F9 -10036
    UNDO -131 CTRL -1 ESCAPE -10017 F10 -10037
    REDO -132 ALT -3 INSERT -10018 F11 -10038
    ARROW_DOWN -24 FN -5 SLEEP -10019 F12 -10039
    ARROW_UP -23 CLIPBOARD_CLEAR_HISTORY -36 MEDIA_PLAY -10020 BACK -10040
    ARROW_RIGHT -22 NUMPAD -205 MEDIA_PAUSE -10021

  • codePoints: when multiple code points should be entered; only available for multi_text_key described in the Key classes section

  • labelFlags: allows specific effects

    Click to see available flags
    FLAG NAME FLAG VALUE FLAG NAME FLAG VALUE
    alignHintLabelToBottom 2 hasShiftedLetterHint 1024
    alignIconToBottom 4 hasHintLabel 2048
    alignLabelOffCenter 8 autoXScale 16384
    fontNormal 16 autoScale 49152
    fontMonoSpace 32 preserveCase 65536
    fontDefault 48 shiftedLetterActivated 131072
    followKeyLargeLetterRatio 64 fromCustomActionLabel 262144
    followKeyLetterRatio 128 followFunctionalTextColor 524288
    followKeyLabelRatio 192 keepBackgroundAspectRatio 1048576
    followKeyHintLabelRatio 320 disableKeyHintLabel 1073741824
    hasPopupHint 512 disableAdditionalPopupKeys 2147483648

    *To find the flag values, the hex value of each labelFlags was converted to base ten by searching for 0x## in the DuckDuckGo search engine.
    The default hex values are listed here.


Click to see an example with several label properties 
{ "label": "a", "type": "action", "width": 0.2, "popup": { "main": { "label": "!" }, "relevant":
  [
// The `b` character is displayed in the popup but this will open the settings.
    { "label": "b|!code/-301" }
  ] }
},
// A space is added
{ "type": "placeholder",  "width": 0.2 }
// This will write the characters "a", "b" and "c" while “%” is written on the key
{ "$": "multi_text_key", "codePoints": [97, 98, 99], "label": "%", "width": 0.2 }

Special labels

Usually the label is what is displayed on the key. However, there are some special labels:

  • Currency keys

    • $$$ will be replaced by the local currency, depending on your current layout language. If you define a key with $$$ without defining popup keys, it will get the first 4 additional currencies (see below) as popup
    • $$$1 - $$$5 will be replaced by currencies available on long-pressing the currency key

    Click to see an example with currency key 
    { "label": "$$$", "type": "function", "width": 0.1 },
{ "label": "$$$3", "type": "normal", "width": 0.1 }

  • Functional keys (incomplete list)

    • alpha: switch to alphabet keyboard (or main phone keyboard in case of phone layout)
    • symbol: switch to symbol keyboard (or phone symbols keyboard in case of phone layout)
    • symbol_alpha: toggle alpha / symbol keyboard
    • numpad: toggle numpad layout
    • emoji: switch to emoji view
    • com: display common TLDs (.com and similar, currently not localized)
    • language_switch: language switch key
    • action: the action (enter) key
    • delete: delete key
    • shift: shift key, will change label when in symbols layout
    • period: . key with punctuation popups, will adapt to language-specific period
    • comma: , key with special popups, will adapt to language-specific comma, or display / in URL fields and @ in email fields
    • space: space key, with icon when using a number layout
    • zwnj: Zero-width non-joiner (automatically added next to space in alphabet layout for some languages)
    • You can also use toolbar keys, e.g. { "label": "undo", "type": "function" }

    Click to see available toolbar keys
    TOOLBAR KEYS NAMES
    voice select_all incognito right page_down
    clipboard select_word autocorrect up full_left
    numpad copy clear_clipboard down full_right
    undo cut close_history word_left page_start
    redo paste emoji word_right page_end
    settings one_handed left page_up

  • In case a label clashes with the text you want to add, put \\ in front of the text you want, e.g. { "label": "\\space" } will write the label space instead of adding a space bar.

    • Note that you need to escape the \ in json files by adding a second \.
      This means:
      • If you wish to add \ character, you must add a second \ in json files
      • The same applies to the " character: you must add a \ in json files

    Click to see example with `\` character 
    // The `\` character is displayed on the key
{ "label": "\\", "width": 0.1, "type": "normal", "popup": { "relevant":
  [
// The `"` character is displayed in the popup
    { "label": "\"" }
  ] }
},
// The word `space` is displayed on the key
{ "label": "\\space", "width": 0.1 }

  • If you want different key label and input text, set the label to [label]|[text], e.g. { "label": "aa|bb" } will show aa on the key, but pressing it will input bb.

  • You can also specify special key codes like { "label": "a|!code/key_shift" }

    Click to see available key code names
    KEY CODE NAMES KEY CODE NAMES
    key_tab key_voice_input
    key_enter key_action_next
    key_space key_action_previous
    key_shift key_shift_enter
    key_capslock key_language_switch
    key_switch_alpha_symbol key_emoji
    key_switch_alpha key_unspecified
    key_switch_symbol key_clipboard
    key_output_text key_start_onehanded
    key_delete key_stop_onehanded
    key_settings key_switch_onehanded

  • It's also possible to specify an icon, like { "label": "!icon/previous_key|!code/key_action_previous" }.

    Click to see available icons
    ICON NAMES ICON NAMES
    shift_key previous_key
    shift_key_shifted tab_key
    shift_key_locked shortcut_key_disabled
    delete_key language_switch_key
    space_key zwnj_key
    space_key_for_number_layout zwj_key
    enter_key stop_onehanded_mode_key
    go_key switch_onehanded_key
    search_key resize_onehanded_key
    send_key toolbar_key
    next_key bin
    done_key incognito

Key classes

They are specified with $, usually you can omit them in HeliBoard.

Here are the different classes:

  • text_key: normal key, default
  • auto_text_key: used in FlorisBoard for a key that changes text case when shift is enabled, HeliBoard does that anyway unless disabled with a labelFlag
  • multi_text_key: key with an array of code points, e.g. { "$": "multi_text_key", "codePoints": [2509, 2480], "label": "্র" }
  • There are also selector classes, which allow to change keys conditionally:

    • case_selector: keys for lower and upper (both mandatory), similar to shift_state_selector

      Click to see example with `case_selector` 
      { "$": "case_selector", "lower": { "label": "a" }, "upper": { "label": "b" } }

    • shift_state_selector: keys for unshifted, shifted, shiftedManual, shiftedAutomatic, capsLock, manualOrLocked, default (all optional)

      Click to see example with `shift_state_selector` 
      { "$": "shift_state_selector", "unshifted": { "label": "a" }, "shifted": { "label": "b" }, "capsLock": { "label": "c" } }

    • variation_selector: keys for input types datetime, time, date, password, normal, uri, email, default (all optional)

      Click to see example with `variation_selector` 
      { "$": "variation_selector", "datetime": { "label": "a" }, "password": { "label": "b" }, "email": { "label": "c" } }

    • keyboard_state_selector: keys for emojiKeyEnabled, languageKeyEnabled, symbols, moreSymbols, alphabet, default (all optional). The keyEnabled keys will be used if the corresponding setting is enabled, symbols, moreSymbols, alphabet will be used when the said keyboard view is active

      Click to see example with `keyboard_state_selector` 
      { "$": "keyboard_state_selector", "languageKeyEnabled": { "$": "keyboard_state_selector", "alphabet": { "label": "language_switch" } } }

    • layout_direction_selector: keys for ltr and rtl (both mandatory)

      Click to see example with `layout_direction_selector` 
      { "$": "layout_direction_selector", "ltr": { "label": "a" }, "rtl": { "label": "b" } }

Tips

  • To hide a hint for a specific key, add the code { "type": "placeholder" } to the first position when editing popup labels. The hint will not appear regardless of Heliboard settings

    Click to see example to hide key hint 
    { "label": "a", "width": 0.1, "type": "normal", "popup": { "relevant":
  [
// The comma will not be displayed on the key
    { "type": "placeholder" },
    { "label": "," },
    { "label": "?" },
    { "label": "!" },
    { "label": "#" }
  ] }
}

  • To find specific code point:

    • Go to the UnicodePlus website
    • Search for the desired character, e.g. a space or the letter a
    • Read the HTML value of the desired character; in our example,   for the space and a for the a character
    • Simply remove the &, # and ; characters from the HTML value to find the code point

    Click to see example with code point values 
    // Keyboard view space bar with numpad view space bar icon
{ "label": "!icon/space_key_for_number_layout|!code/32", "labelFlags": 4, "width": -1 },
// @ is displayed on the key, but the letter `a` will be written
{ "label": "@|!code/97", "width": 0.1 }

  • In popups, to define a precise number of columns for displaying characters, you need to use the { "label": "!autoColumnOrder!X" }, code where X is the number of columns.

    Click to see example with `!autoColumnOrder!X` 
    { "label": ".", "width": 0.1, "type": "function", "popup": { "relevant":
    [
        { "label": "!autoColumnOrder!4" },
        { "label": "," },
        { "label": "?" },
        { "label": "!" },
        { "label": "#" },
        { "label": "(" },
        { "label": ")" },
        { "label": "/" },
        { "label": ";" },
        { "label": "@" },
        { "label": "'" },
        { "label": ":" },
        { "label": "-" },
        { "label": "\"" },
        { "label": "+" },
        { "label": "%" },
        { "label": "&" }
    ] }
},

  • If you don't want to enable the Number row setting (in this case the keyboard view has 4 rows) but want to have 5 rows in the Symbol or More Symbols view, you need to add an empty row with the code [ { "type": "placeholder" } ], at the beginning of the row editing.

    Click to see example with `[ { "type": "placeholder" } ],` 
    // Start of file
[
// EMPTY ROW
  [
    { "type": "placeholder" }
  ],
// ROW 1
  [
  ],
// etc.
]

  • Reminder:
    If you wish to add \ character, you must add a second \ in json files
    The same applies to the " character: you must add a \ in json files

    Click to see example with `\` character 
    // The `\` character is displayed on the key
{ "label": "\\", "width": 0.1, "type": "normal", "popup": { "relevant":
  [
// The `"` character is displayed in the popup
    { "label": "\"" }
  ] }
}

  • If you want to add a key that does nothing (may be useful in a popup for example), you must write: { "label": " |!code/-1" },

Examples of JSON files

Here are some sample JSON files that customize all the keyboard views.

Add a custom footer
Add a custom sidebar
Clone this wiki locally