-
-
Notifications
You must be signed in to change notification settings - Fork 95
Layouts
-
The JSON file:
- It always starts with the left square bracket
[
and always ends with the right square bracket]
- It always starts with the left 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
- Each row of the keyboard must be written between 2 square brackets:
-
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
- Each label always must be written between 2 curly brackets:
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" }
]
]
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 to0
- 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 thespace
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
- A special value is
-
popup
: list of keys to add in the popup- Note that in popup keys, properties are ignored with the exception of
$
,code
,codePoints
, andlabel
- 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
- Note that in popup keys, properties are ignored with the exception of
-
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 formulti_text_key
described in the Key classes section -
labelFlags
: allows specific effectsClick 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 }
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 labelspace
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
- If you wish to add
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 }
- Note that you need to escape the
-
If you want different key label and input text, set the label to [label]|[text], e.g.
{ "label": "aa|bb" }
will showaa
on the key, but pressing it will inputbb
. -
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
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 alabelFlag
-
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 forlower
andupper
(both mandatory), similar toshift_state_selector
Click to see example with `case_selector`
{ "$": "case_selector", "lower": { "label": "a" }, "upper": { "label": "b" } }
-
shift_state_selector
: keys forunshifted
,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 typesdatetime
,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 foremojiKeyEnabled
,languageKeyEnabled
,symbols
,moreSymbols
,alphabet
,default
(all optional). ThekeyEnabled
keys will be used if the corresponding setting is enabled,symbols
,moreSymbols
,alphabet
will be used when the said keyboard view is activeClick to see example with `keyboard_state_selector`
{ "$": "keyboard_state_selector", "languageKeyEnabled": { "$": "keyboard_state_selector", "alphabet": { "label": "language_switch" } } }
-
layout_direction_selector
: keys forltr
andrtl
(both mandatory)Click to see example with `layout_direction_selector`
{ "$": "layout_direction_selector", "ltr": { "label": "a" }, "rtl": { "label": "b" } }
-
-
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 settingsClick 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 lettera
- Read the HTML value of the desired character; in our example,
 
for thespace
anda
for thea
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 whereX
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 filesClick 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": "\"" } ] } }
Here are some sample JSON files that customize all the keyboard views.