diff --git a/Layouts.md b/Layouts.md new file mode 100644 index 0000000..8224b28 --- /dev/null +++ b/Layouts.md @@ -0,0 +1,277 @@ +# 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 +
+ +```json +[ +// 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 | | EMOJI | -212 | CAPS_LOCK | -13 | PAGE_DOWN | -10011 | F7| -10034 | + | 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 | | | + +
+ +* `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 | + +
+ +# 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 + +* 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. `undo` + +
+ 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 a `\\` 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 `\`. +* 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 | | + +
+ +# 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` +
+ + ```json + { "$": "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` +
+ + ```json + { "$": "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` +
+ + ```json + { "$": "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` +
+ + ```json + { "$": "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` +
+ + ```json + { "$": "layout_direction_selector", "ltr": { "label": "a" }, "rtl": { "label": "b" } } + ``` +
+ +# Examples of JSON files + +[Here](https://github.com/Helium314/HeliBoard/discussions/1132#discussion-7260853) are some sample JSON files that customize all the keyboard views. \ No newline at end of file