diff --git a/Layouts.md b/Layouts.md deleted file mode 100644 index 7d04341..0000000 --- a/Layouts.md +++ /dev/null @@ -1,277 +0,0 @@ -# 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