luckyimnotanigger/HeliBoard
1
0
Fork 0
mirror of https://github.com/Helium314/HeliBoard.git synced 2025-05-31 11:52:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Migrate functional key layouts to json (#778)

Browse source 
Now the functional key layouts should be (mostly) compatible to FlorisBoard
Not yet customizable, this is a large step towards customizable functional key layouts
This commit is contained in:
Helium314 2024-05-11 15:41:00 +02:00 • committed by GitHub
parent 691ae017bc
commit 34d8bd16f0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
30 changed files with 931 additions and 712 deletions
Download patch file Download diff file Expand all files Collapse all files

99
layouts.md
View file

@ -1,36 +1,17 @@
A compilation of information about the layout formats usable in this app.
There are two distinct formats:
* the _simple_ format is a text file with one key per line, and two consecutive line breaks indicating a switch to the next row, [example](app/src/main/assets/layouts/qwerty.txt)
* the _simple_ format is a text file with one key label per line, and two consecutive line breaks indicating a switch to the next row, [example](app/src/main/assets/layouts/qwerty.txt)
* the _json_ format taken from [FlorisBoard](https://github.com/florisboard/florisboard/blob/master/CONTRIBUTING.md#adding-the-layout), but only "normal" keys are supported (i.e. no action keys and similar), [example](app/src/main/assets/layouts/azerty.json)
## General notes
Adding too many keys or too long texts will make the keyboard look awkward or broken, and even crash the app under some specific conditions.
Adding too many keys or too long texts will make the keyboard look awkward or broken, and even crash the app under some specific conditions (popup keys are especially prone for this).
There are some sanity checks when adding a layout to avoid such issues, but they do not cover all possible cases.
Further there is no check whether the layout actually contains characters of the selected language.
If you use an external glide typing library, you likely will have issues if your layout contains duplicate keys, or keys with text longer than a single letter.
There are special key labels that are intended for internal use only, but can (currently) be set on custom layouts too. An example is `!icon/previous_key|!code/key_action_previous`, so it's unlikely you will stumble upon issues here when not intentionally provoking it.
One special label that might be wanted though is `$$$`, which will be replaced by the local currency. `$$$1` - `$$$5` will be replaced by currencies available on long-pressing the currency key.
If you want different key label and use text, set the label to [label]|[text], e.g. `aa|bb` will show `aa`, but pressing the key will input `bb`.
Some special key labels will be implemented, most are already working in the (currently experimental) customization of number layouts (numpad and similar). Some keys have two names for compatibility to FlorisBoard layouts.
* _alpha_ / _view_characters_: switch to alphabet keyboard (or main phone keyboard in case of phone layout)
* _symbol_ / _view_symbols_: switch to symbol keyboard (or phone symbols keyboard in case of phone layout)
* _symbol_alpha_: toggle alpha / symbol keyboard
* _numpad_ / _view_numeric_advanced_: switch to numpad layout
* _emoji_: switch to emoji view
* _com_: display common TLDs (.com and similar)
* _emoji_com_: emoji key, but in URL and email fields it's a com key
* _language_switch_: language switch key
* _action_ / _enter_: 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)
If the layout has exactly 2 keys in the bottom row, these keys will replace comma and period keys. More exactly: the first key will replace the first functional key with `"groupId": 1` in the bottom row, and the second key with replace the first key with `"groupId": 2`.
## Simple format
* One key per line
@ -44,8 +25,68 @@ Some special key labels will be implemented, most are already working in the (cu
* There is no need for specifying a `code`, it will be determined from the label automatically
* You can still specify it, but it's only necessary if you want key label and code to be different (please avoid contributing layout with unnecessary codes to HeliBoard)
* Note that not all _special codes_ (negative numbers) from FlorisBoard are supported
* You can add the numeric value of a _labelFlag_ to a key for some specific effects, see [here](app/src/main/res/values/attrs.xml) in the section _keyLabelFlags_ for names and numeric values.
* More details on the formal will be provided. For now you can check other layouts, often you just need to copy lines and change the labels.
* Key classes: specified with `$`, usually you can omit them in HeliBoard
* `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, see the [dvorak layout](https://github.com/Helium314/HeliBoard/blob/main/app/src/main/assets/layouts/dvorak.json) for an example:
* `case_selector`: keys for `lower` and `upper` (both mandatory), similar to `shift_state_selector`
* `shift_state_selector`: keys for `unshifted`, `shifted`, `shiftedManual`, `shiftedAutomatic`, `capsLock`, `manualOrLocked`, `default` (all opttional)
* `variation_selector`: keys for `datetime`, `time`, `date`, `password`, `normal`, `uri`, `email`, `default` (all opttional)
* `layout_direction_selector`: keys for `ltr` and `rtl` (both mandatory)
### Properties
* A (non-selector) key can have the following properties:
* `type`: only specific values, HeliBoard mostly uses this to determine background color and type, determined automatically by default
* `character`: 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
* There are some more values, but they do nothing
* `code`: code point that is entered when the key is pressed, determined from the label by default, not available for `multi_text_key`
* There are special negative values available, e.g. the ones used by functional keys, see [KeyCode.kt](/app/src/main/java/helium314/keyboard/keyboard/internal/keyboard_parser/floris/KeyCode.kt). There are several not yet supported key codes in there, you can see in the function `checkAndConvertCode` which ones are working.
* `codePoints`: when multiple code points should be entered, only available for `multi_text_key`
* `label`: text to display on the key, determined from code if empty
* There are some special values, see the [label section](#labels)
* `groupId`: which additional popup keys to show, `0` is default and does not add anything, `1` adds the comma popup keys, and `2` adds the period popup keys
* `popup`: list of keys to add in the popup, e.g. `"label": ")", "popup": {"relevant": [{ "label": "." }]}` is a `)` key with a `.` 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)
* `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
* `0.17` for keys with `"type": numeric` in number layouts
* Otherwise the default width is used, which is `0.1` for phones and `0.09` for tablets
* If the sum of widths in a row is greater than 1, keys are rescaled to fit on the screen
* `labelFlags`: allows specific effects, see [here](app/src/main/res/values/attrs.xml) in the section _keyLabelFlags_ for names and numeric values
## Labels
In the simple format you only specify labels, in json layouts you do it explicitly via the `label` property.
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_: switch to 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)
* If you want different key label and use text, set the label to [label]|[text], e.g. `aa|bb` will show `aa`, but pressing the key will input `bb`.
You can also specify special key codes like `a|!code/key_action_previous`, but it's cleaner to use a json layout and specify the code explicitly. Note that when specifying a code in the label, and a code in a json layout, the code in the label will be ignored.
It's also possible to specify an icon together with a code `!icon/previous_key|!code/key_action_previous`, but this is not fully supported yet.
## Adding new layouts / languages
* You need a layout file in one of the formats above, and add it to [layouts](app/src/main/assets/layouts)
@ -66,3 +107,15 @@ Some special key labels will be implemented, most are already working in the (cu
* If you add a new language for which Android does not have a display name, it will be displayed using the language tag
* Avoiding this currently is more complicated than necessary: add the language tag to [LocaleUtils.getLocaleDisplayNameInSystemLocale](/app/src/main/java/helium314/keyboard/latin/common/LocaleUtils.kt#L181) to have an exception, and add a string named `subtype_<langage tag, but with _ instead of ->` to [`strings.xml`](/app/src/main/res/values/strings.xml). Further you may need to add a `subtype_in_root_locale_<language tag>` to [donottranslate.xml](/app/src/main/res/values/donottranslate.xml), and add the language tag to `subtype_locale_exception_keys` and `subtype_locale_displayed_in_root_locale`.
* If a newly added language does not use latin script, please update the default scripts method `Locale.script` in [ScriptUtils](app/src/main/java/helium314/keyboard/latin/utils/ScriptUtils.kt)
## Functional key layouts
This is not yet customizable, but will be soon!
Mostly customizing functional keys works like other layouts, with some specific adjustments:
* you can either have a single layout for functional keys (default), or separate layouts for symbols and shift symbols
* when using a single layout
* emoji and language switch keys will only show in alphabet layout and when the option is enabled
* numpad key will only show in symbols layout
* otherwise the layout will be shown as it is in the layout file
* use keys with `"type": "placeholder"` for
* separating left and right functional keys (e.g. shift and delete in default layout)
* separating top and bottom rows in case you want to have functional key rows aligned to the top of the keyboard