Skip to content

LayoutSpec.md

Latest commit

 

History

History
1193 lines (903 loc) · 38.5 KB

LayoutSpec.md

File metadata and controls

1193 lines (903 loc) · 38.5 KB
Raw

Keyboard Layout Format

A lot of concepts are explained through examples in this document, please read through them to understand different ways of defining layouts.

A good way to learn is also to read through the existing layouts in this repository.

Starting out

The YAML file's entry point is the Keyboard data class. It only requires a name and rows.

The QWERTY layout is defined like so:

name: "QWERTY"
rows:
  - letters: q w e r t y u i o p
  - letters: a s d f g h j k l
  - letters: z x c v b n m

The name must be defined first, and letter rows are defined next.

There are many ways to define the same thing. Use which one makes most sense for your use case. All rows in the below example are functionally identical:

name: Different examples
rows:
  # Basic definition as string
  - letters: q w e r t
  
  # Basic definition as string (quoting is necessary if you use some symbols)
  - letters: "q w e r t"

  # Definition as inline list
  - letters: ["q", "w", "e", "r", "t"]

  # Definition as multiline list, and unicode escapes
  - letters:
      # U+0071: LATIN SMALL LETTER Q
      - "\u0071"
      # U+0077: LATIN SMALL LETTER W
      - "\u0077"
      # U+0065: LATIN SMALL LETTER E
      - "\u0065"
      # U+0072: LATIN SMALL LETTER R
      - "\u0072"
      # U+0074: LATIN SMALL LETTER T
      - "\u0074"

  # Defining base, explicit case, and mixing randomly
  - letters:
      - {type: base, spec: q}
      - {type: case, normal: w, shifted: W}
      - e
      - "\u0072"
      - type: case
        normal:
          type: base
          spec: "t|t" # pipe symbol is keyspec syntax: label|code
          code: 0x74  # though you can set code explicitly too
        shifted: {type: base, spec: T}

Defining layout-specific moreKeys can also be done in multiple ways:

name: MoreKeys examples
rows:
  # List syntax: [primarykey, ...morekeys]
  - letters:
      - [a, ą]
      - b
      - [c, č]
      - [d] # For consistency you can also specify a key without morekeys like this
      - [e, ė, ę]

  # You can also do it inline at the cost of readability
  - letters: [[a, ą], b, [c, č], d, [e, ė, ę]]

  # Explicit BaseKey syntax
  - letters:
      - {type: base, spec: "a", moreKeys: "ą"}
      - {type: base, spec: b}
      - type: base
        spec: "c"
        moreKeys: "č"
      - "d"
      - type: base
        spec: "e"
        moreKeys: ["ę", "ė"]

  # You can use list syntax anywhere that expects a Key, such as `case`
  - letters:
      - type: case
        normal: [a, ą]
        shifted: [A, Ą]
      - b
      - {type: case, normal: [c, č], shifted: [C, Č]}
      - d
      - [e, ę, ė]

These shortcuts for defining things are explained more in the shortcuts section. In practice you should avoid randomly mixing different ways of defining keys, you should stick to something that keeps the file readable and understandable.

With RTL languages it's advised to use unicode escapes in order to keep the file easily editable. It's good practice to include a comment explaining each unicode character:

name: Arabic
rows:
  - letters:
      # U+0636: "ض" ARABIC LETTER DAD
      - "\u0636"
      # U+0635: "ص" ARABIC LETTER SAD
      - "\u0635"
      # U+062B: "ث" ARABIC LETTER THEH
      - "\u062B"
      # U+0642: "ق" ARABIC LETTER QAF
      # U+06A8: "ڨ" ARABIC LETTER QAF WITH THREE DOTS ABOVE
      - ["\u0642", "\u06A8"]

Number row and bottom row

A default number row and bottom row will be added if they are not explicitly defined. You can override them with custom ones for more advanced layouts:

name: "PC QWERTY Example"
numberRowMode: AlwaysEnabled
rows:
  - numbers: "` 1 2 3 4 5 6 7 8 9 0 - ="
  - letters: "q w e r t y u i o p [ ] \\"
  - letters: "a s d f g h j k l ; ' $delete"
  - letters: "$shift z x c v b n m , . / $shift"
  - bottom:  "$symbols $space $enter"

There can at most be one number row, and one bottom row. If they are explicitly defined in the layout file, then the number row must be at the top and bottom row must be at the bottom. Between 1 and 8 letter rows are permitted.

Template keys (automatic shift and backspace)

The keyboard parser automatically prepends $shift and appends $delete to the final letter row when all of the following conditions are met:

  1. No bottom row is explicitly defined
  2. None of the letter rows explicitly set $shift or $delete

What this means is that to customize the location of shift and delete, or to disable the shift key in your layout, you just need to specify $shift and/or $delete somewhere, and the automatic insertion will be disabled. If you specify an explicit bottom row, you will need to manually specify them as well.

In this example, the backspace ($delete) is relocated to the second row instead of its usual place in the third row:

name: "Alphabet"
rows:
  - letters: a b c d e f g h i j
  - letters: k l m n o p q r s $delete    # Backspace on this row instead of bottom row
  - letters: $shift t u v w x y z $shift  # Two shift keys
  - bottom:  $symbols $space $enter       # No comma or period

You can use the following template keys:

  • $shift - shift key
  • $delete - backspace key
  • $space - spacebar
  • $enter - enter/search/next/prev/go key
  • $symbols - switch to symbols menu
  • $alphabet - switch back to alphabet (only used in symbols layout)
  • $action - action key, user-defined, may be empty
  • $number - switch to numpad mode
  • $contextual - contextual key, / for URLs and date fields, @ for email fields, : for time fields
  • $zwnj - Zero-width non-joiner key, and zero-width joiner key in morekeys.
  • $optionalzwnj - same as $zwnj if useZWNJKey is true, else none
  • $gap - regular-width gap
  • $alt0 - switch to alt page 0, or back from alt page 0
  • $alt1 - switch to alt page 1, or back from alt page 1
  • $alt2 - switch to alt page 2, or back from alt page 2
  • $period - just a normal '.' key usually, but if "Quick period key" setting is enabled by user, switches to a quicker layout

You may find yourself wanting to customize the template keys to set a custom width or similar. You can how to do this in the Customizing template keys section.

List and Key definition shortcuts

There are a few shortcuts to help make it easier to define layouts. These are documented in this section.

Key as a YAML string

An example of a full BaseKey definition:

name: example
rows:
  - letters:
      - type: base
        spec: "a"

This shortcut allows you to define the exact same thing with just

name: example
rows:
  - letters:
      - a

Key as a YAML list

An example of a full BaseKey definition with moreKeys:

name: example
rows:
  - letters:
      - type: base
        spec: "a"
        moreKeys: "ayy,ahh"

This shortcut allows you to define the exact same thing with just

name: example
rows:
  - letters:
      - [a, ayy, ahh]

The first element is treated as the spec, and all subsequent elements are turned into moreKeys.

List<Key> as a YAML string

An example of a List definition, using the string shortcut for defining Key:

name: example
rows:
  - letters: [a, b, c]

This shortcut allows you to define the exact same thing with just

name: example
rows:
  - letters: a b c
  # or - letters: "a b c", necessary for yaml parsing if you use some special symbols

Key specs

Key specs work the same way they do in AOSP keyboard. For example you can define a differing label from its code, without needing to use the long format.

name: "Arabic example"
rows:
  - letters:
    - " \u0654◌|\u0654" # The label will appear as ٔ◌ but it will only type the Hamza mark, without the ◌ circle

Automatic moreKeys

moreKeys refers to the extra keys that are accessible by long-pressing a key. The layout engine automatically adds a bunch of moreKeys to keys by default - symbols, actions, numbers, and accented letters are added based on the key's location and user settings.

You can customize the behavior of automatic moreKeys by setting moreKeyMode in attributes. For example, to disable all automatic moreKeys, you can include this near the top of your layout definition:

attributes: {moreKeyMode: OnlyExplicit}

moreKey modes are documented in the More Key Mode section of API reference.

Attribute system

Attributes can be defined in multiple places: the keyboard itself, a specific row, or an individual key. Attributes which are unset get inherited in a particular order. See the Key Attributes section of the API reference for all attributes and defaults.

Different key types

The base key is fit for most cases, but case is also useful when you need the key to change based on shift state. See the Keys section of the API reference for all key types.

API Reference

Keyboard

Overview

The Keyboard data class represents a keyboard layout definition, serving as the entry point for layout YAML files.

Properties

name

  • Description: The human-readable name of the layout. If the layout is for a specific language, this should be written in the relevant language.
  • Type: String
  • Optional: No

rows

  • Description: The rows defined for the layout. Defining the number row, bottom row, or the functional keys (shift/backspace) is optional here. If they are missing, defaults will automatically be added to effectiveRows.
  • Type: List<Row>
  • Optional: No

languages

  • Description: (optional) List of languages this layout is intended for. It will be displayed as an option for the specified languages.
  • Type: List<String>
  • Optional: Yes
  • Default Value: empty list

description

  • Description: (optional) A human-readable description of the layout. Authorship/origin information may be added here. This is intended to be displayed to the user when they are selecting layouts.
  • Type: String
  • Optional: Yes
  • Default Value: empty string

layoutSetOverrides

  • Description: (optional) Override the symbols layout or other layouts for this layout set.
  • Type: LayoutSetOverrides
  • Optional: Yes
  • Default Value: A default instance of LayoutSetOverrides

numberRowMode

  • Description: (optional) Whether the number row should be user-configurable, always displayed, or never.
  • Type: NumberRowMode
  • Optional: Yes
  • Default Value: UserConfigurable

bottomRowHeightMode

  • Description: (optional) Whether the bottom row should always maintain a consistent height, or whether it should grow and shrink.
  • Type: BottomRowHeightMode
  • Optional: Yes
  • Default Value: Fixed

bottomRowWidthMode

  • Description: (optional) Whether the bottom row should follow key widths of other rows, or should maintain separate widths for consistency.
  • Type: BottomRowWidthMode
  • Optional: Yes
  • Default Value: SeparateFunctional

attributes

  • Description: (optional) Default attributes to use for all rows
  • Type: KeyAttributes
  • Optional: Yes
  • Default Value: A default instance of KeyAttributes

overrideWidths

  • Description: (optional) Definitions of custom key widths. Values are between 0.0 and 1.0, with 1.0 representing 100% of the keyboard width.
  • Type: Map<KeyWidth, Float>
  • Optional: Yes
  • Default Value: empty map

rowHeightMode

  • Description: (optional) Whether or not rows should fill the vertical space, or have vertical gaps added.
  • Type: RowHeightMode
  • Optional: Yes
  • Default Value: ClampHeight

useZWNJKey

  • Description: (optional) Whether or not the ZWNJ key should be shown in place of the contextual key.
  • Type: Boolean
  • Optional: Yes
  • Default Value: false

minimumFunctionalKeyWidth

  • Description: (optional) Minimum width for functional keys.
  • Type: Float
  • Optional: Yes
  • Default Value: 0.125f

minimumBottomRowFunctionalKeyWidth

  • Description: (optional) Minimum width for functional keys in the bottom row.
  • Type: Float
  • Optional: Yes
  • Default Value: 0.15f

altPages

  • Description: (optional) Alternative pages for this layout, use in conjunction with $alt0, $alt1, $alt2.
  • Type: List<List<Row>>
  • Optional: Yes
  • Default Value: empty list

autoShift

  • Description: (optional) Whether or not automatic shifting should apply for this keyboard, when input starts or a sentence is finished.
  • Type: boolean
  • Optional: Yes
  • Default Value: true

imeHint

  • Description: (optional) Hint for the IME engine to request specific behavior. Only has effect if the language is set to Chinese or Japanese.
  • Type: string?
  • Optional: Yes
  • Default Value: null

Valid values for Japanese are "12key" or "qwerty" to specify how the keys should be interpreted.

Valid values for Chinese are "stroke" or "qwerty" to specify which schema should be used.

When the imeHint is not qwerty, the key codes are remapped to something else. For example, "1" will type "あ" in 12key Japanese, and "a" will type "き", despite no phonetic relation between these letters. Whereas in Chinese, "h" types "一" in stroke input. You will need to heavily reference these layouts if you want to use a non-qwerty imeHint:

Row

Overview

The Row data class represents a single row in a keyboard layout. It allows for customization of various aspects, including the type of keys, row height, splittability, and behavior with respect to the number row.

One of numbers, letters or bottom must be defined.

numbers

  • Description: Defines this as a number row.
  • Type: List<Key>?
  • Optional: One of numbers, letters or bottom must be defined.
  • Default Value: null
  • Behavior:
    • If defined, will be treated as a number row by default.
    • Number rows are given grow keys, no background, and smaller height by default.

letters

  • Description: Defines this as a letters row.
  • Type: List<Key>?
  • Optional: One of numbers, letters or bottom must be defined.
  • Default Value: null
  • Behavior:
    • If defined, will be treated as a letters row by default.
    • Letter rows are splittable by default.

bottom

  • Description: Defines this as a bottom row.
  • Type: List<Key>?
  • Optional: One of numbers, letters or bottom must be defined.
  • Default Value: null
  • Behavior:
    • If defined, this is a bottom row. Bottom row should typically contain: $symbols , $action $space $optionalzwnj . $enter
    • Bottom row does not inherit the keyboard's attributes by default, so the global moreKeyMode will be ignored there. Attributes must be specified either for the individual key or for the bottom row itself.

The default bottom row is the following:

- bottom:
    - $symbols
    - type: contextual
      fallbackKey: ","
    - $action
    - $space
    - $optionalzwnj
    - $period
    - $enter

rowHeight

  • Description: The height multiplier for this row.
  • Type: Double
  • Optional: Yes
  • Default Value: 1.0 for letters and bottom rows, 0.8 for number rows.
  • Behavior:
    • Can be used to customize the row height with respect to other rows.

splittable

  • Description: Whether this row is splittable.
  • Type: Boolean
  • Optional: Yes
  • Default Value: true if defined as a letters row, false otherwise
  • Behavior:
    • If true, allows the row to be split when the user prefers a split layout (e.g. landscape)

numRowMode

  • Description: How this row should behave with respect to the number row.
  • Type: RowNumberRowMode
  • Optional: Yes
  • Default Value: Default
  • Behavior:
    • Can be customized to control when the row is displayed in relation to the number row.

attributes

  • Description: Default key attributes for this row.
  • Type: KeyAttributes
  • Optional: Yes
  • Default Value: a default set of attributes
  • Behavior:
    • Allows customization of key styles, widths, and other attributes.

Layout Set Overrides

Overview

The LayoutSetOverrides data class represents a set of overrides for specific layouts. All layouts currently leave this default.

Properties

symbols

  • Description: The layout used when the keyboard is in symbols mode.
  • Type: String
  • Default Value: "symbols"

symbolsShifted

  • Description: The layout used when the keyboard is in shifted symbols mode.
  • Type: String
  • Default Value: "symbols_shift"

number

  • Description: The layout used when the keyboard is in numpad mode.
  • Type: String
  • Default Value: "number"

phone

  • Description: The layout used when the keyboard is in phone mode.
  • Type: String
  • Default Value: "phone"

phoneShifted

  • Description: The layout used when the keyboard is in shifted phone mode.
  • Type: String
  • Default Value: "phone_shift"

Label Flags

Overview

The LabelFlags data class represents flags for customizing the behavior of key labels on a key.

Properties

alignHintLabelToBottom

  • Description: Aligns the hint label to the bottom of the key.
  • Type: Boolean
  • Default Value: false

alignIconToBottom

  • Description: Aligns icon to the bottom of the key.
  • Type: Boolean
  • Default Value: false

alignLabelOffCenter

  • Description: Aligns label off-center in the key.
  • Type: Boolean
  • Default Value: false

hasHintLabel

  • Description: Indicates whether the key has a hint label.
  • Type: Boolean
  • Default Value: false

followKeyLabelRatio

  • Description: Follows the key label ratio for text size.
  • Type: Boolean
  • Default Value: false

followKeyLetterRatio

  • Description: Follows the key letter ratio for text size.
  • Type: Boolean
  • Default Value: false

followKeyLargeLetterRatio

  • Description: Follows the key large letter ratio for text size.
  • Type: Boolean
  • Default Value: false

autoXScale

  • Description: Enables automatic x-axis scaling to fit label within key.
  • Type: Boolean
  • Default Value: false

Key Attributes

Overview

The KeyAttributes data class represents various attributes for keys in a keyboard layout. These attributes control how keys are displayed and behave.

Properties

width

  • Description: The width token for the key.
  • Type: KeyWidth?
  • DefaultKeyAttributes Value: Regular
  • Behavior:
    • Specifies the width of the key using a width token.

style

  • Description: The visual style (background) for the key.
  • Type: KeyVisualStyle?
  • DefaultKeyAttributes Value: Normal
  • Behavior:
    • Defines the background appearance of the key.

anchored

  • Description: Whether or not to anchor the key to the edges.
  • Type: Boolean?
  • DefaultKeyAttributes Value: false
  • Behavior:
    • If true, anchors the key to the edges, adding padding as needed.

showPopup

  • Description: Whether or not to show the popup indicator when the key is pressed.
  • Type: Boolean?
  • DefaultKeyAttributes Value: true
  • Behavior:
    • If true, displays a popup indicator for letters, but this may be undesirable for functional or large keys.

moreKeyMode

  • Description: Which moreKeys to add automatically.
  • Type: MoreKeyMode?
  • getEffectiveAttributes Default Value: All if the row is a letter or bottom row, and the effective width is Regular, else OnlyFromLetter
  • Behavior:
    • Specifies the mode for adding more keys automatically.

useKeySpecShortcut

  • Description: Whether or not to use keyspec shortcuts.
  • Type: Boolean?
  • DefaultKeyAttributes Value: true
  • Behavior:
    • If true, enables automatic conversion of certain characters using keyspec shortcuts.

longPressEnabled

  • Description: Whether or not longpress is enabled for the key.
  • Type: Boolean?
  • DefaultKeyAttributes Value: false
  • Behavior:
    • If true, enables long press functionality for the key.

labelFlags

  • Description: Label flags for how the key's label (and its hint) should be presented.
  • Type: LabelFlags?
  • DefaultKeyAttributes Value: { autoXScale: true }
  • Behavior:
    • Specifies how to display the key's label and hint.

repeatableEnabled

  • Description: Whether or not the key is repeatable, intended for backspace or arrow keys.
  • Type: Boolean?
  • DefaultKeyAttributes Value: false
  • Behavior:
    • If true, enables repeat functionality for the key.

shiftable

  • Description: Whether or not the key is automatically shiftable.
  • Type: Boolean?
  • DefaultKeyAttributes Value: true
  • Behavior:
    • If true, the code and label automatically becomes uppercased when the layout is shifted. If this is not desired, this can be set to false. Shift behavior can be customized by using a CaseSelector.

fastMoreKeys

  • Description: Whether or not the key can be "flicked" to access morekeys instantly, without needing to wait for long press timeout. This does not behave like actual flick keys in terms of allowing flicking in all directions, rather it just triggers the morekey popup.
  • Type: Boolean?
  • DefaultKeyAttributes Value: false
  • Behavior:
    • When true, the longpress time will be cut in half
    • In addition, it will implicitly add the base key as the first element in moreKeys (you should avoid using fixedColumnOrder)

rowSpan

  • Description: How many rows this key should span (the height of this key). Extra care needs to be taken to ensure there is a gap in the row below, or else you may have overlapping keys.
  • Type: Int?
  • DefaultKeyAttributes Value: 1
  • Behavior:
    • When greater than 1, the key will expand to the row below.

Inheritance

The attributes are inherited in the following order:

  1. Key.attributes
  2. Row.attributes
  3. Keyboard.attributes
  4. DefaultKeyAttributes

Keys

Base

Overview

The BaseKey data class is the main one used to define keys in a keyboard layout. It contains various attributes and settings for customization.

Explicit definition in yaml is done with type: base.

You can automatically define a BaseKey with default settings by simply specifying the spec in place of the BaseKey object:

# Instead of
  - letters:
     - type: base
       spec: "a"

# You can do the same thing like this
  - letters:
      - "a"

# But customizing attributes requires the long-form definition
  - letters:
      - type: base
        spec: "a"
        attributes: { style: NoBackground }

Properties

spec

  • Description: AOSP key spec.
  • Type: String
  • Behavior:
    • Specifies the key specification, which can contain custom label, code, icon, or output text.

attributes

  • Description: Attributes for this key.
  • Type: KeyAttributes
  • Default Value: blank
  • Behavior:
    • Specifies various attributes for the key, such as width, style, and more.
    • Values defined here supersede any other values inherited from row, keyboard, or default attributes.

moreKeys

  • Description: More keys for this key.
  • Type: List<String>
  • Default Value: empty list
  • Behavior:
    • Specifies more keys that should be added.
    • Can be defined as a list or comma-separated string in YAML (e.g. a,b,c)

hint

  • Description: Hint for the key.
  • Type: String?
  • Default Value: null
  • Behavior:
    • If set, overrides a default hint from the value of moreKeys.
    • Specifies a custom hint for the key.

Key Spec

Each key specification is one of the following:

  • Label optionally followed by keyOutputText (keyLabel|keyOutputText).
  • Label optionally followed by code point (keyLabel|!code/code_name).
  • Icon followed by keyOutputText (!icon/icon_name|keyOutputText).
  • Icon followed by code point (!icon/icon_name|!code/code_name).

Label and keyOutputText are one of the following:

  • Literal string.
  • Label reference represented by (!text/label_name), see {@link KeyboardTextsSet}.
  • String resource reference represented by (!text/resource_name), see {@link KeyboardTextsSet}.

Icon is represented by (!icon/icon_name), see {@link KeyboardIconsSet}.

Code is one of the following:

  • Code point presented by hexadecimal string prefixed with "0x"
  • Code reference represented by (!code/code_name), see Codes and Icons.

Special character, comma ',' backslash '', and bar '|' can be escaped by '' character. Note that the '' is also parsed by XML parser and {@link MoreKeySpec#splitKeySpecs(String)} as well.

See valid icon names and code names in Codes and Icons

Note: In moreKeys, % tells where to put the automatic morekeys (e.g. the numbers in the top row). If no % is present, they are automatically put at the end, so you can use % to put them in the middle. If you want a literal % symbol, use %|%

moreKeys flags

You can customize the order that moreKeys appear, as well as the column count.

  • !autoColumnOrder!3 or !fixedColumnOrder!3 - force 3 columns, you can put a different number too; auto will lay them out in automatic order, fixed will use the specific order as defined
  • !hasLabels! - affects the font size of moreKeys
  • !needsDividers! - currently has no effect
  • !noPanelAutoMoreKey! - long pressing will type the first morekey instead of opening panel

Example:

- letters:
    - ["q", "!fixedColumnOrder!2", "a", "b", "c", "d"] # will lay out 2x2 - a, b; c, d
    - ["w", "!autoColumnOrder!3", "!hasLabels!", "1", "2", "3", "4", "5", "6"] # 3, 1, 2; 6, 4, 5

Case Selector

Overview

The CaseSelector data class represents a case selector key in a keyboard layout. It allows specifying different types of keys depending on when the layout is shifted or not.

Defined in yaml using type: case

Note: You can specify a different type of Key in different cases. For example, normal can be a base key, and shifted can be a gap.

Properties

normal

  • Description: Key to use normally. Required.
  • Type: Key
  • Behavior:
    • Specifies the key to use when the layout is not shifted.

shifted

  • Description: Key to use when shifted.
  • Type: Key
  • Default Value: same as normal
  • Behavior:
    • Specifies the key to use when the layout is shifted.

shiftedManually

  • Description: Key to use when shifted, excluding automatic shift.
  • Type: Key
  • Default Value: same as shifted
  • Behavior:
    • Specifies the key to use when the layout is shifted manually.

shiftLocked

  • Description: Key to use when shift locked (caps lock).
  • Type: Key
  • Default Value: same as shiftedManually
  • Behavior:
    • Specifies the key to use when the shift lock is enabled.

symbols

  • Description: Key to use when in symbols layout.
  • Type: Key
  • Default Value: same as normal
  • Behavior:
    • Specifies the key to use when the layout is in symbols mode.

symbolsShifted

  • Description: Key to use when in symbols layout and shifted.
  • Type: Key
  • Default Value: same as normal
  • Behavior:
    • Specifies the key to use when the layout is in symbols mode and shifted.

Customizing template keys

If you want to customize $shift, $delete, etc. with custom attributes, you can use most of them as a type with a custom attributes set.

Example:

letters:
  # Instead of this...
  - $shift

  # You can do this
  - type: shift
    attributes: { width: Custom1 }

This is possible for the following templates. All of the following accept an attributes parameter:

  • $shift = type: shift
  • $delete = type: delete
  • $space = type: space
  • $enter = type: enter
  • $action = type: action, also takes a fallbackKey parameter for when the action key is disabled
  • $symbols = type: symbols
  • $alphabet = type: alphabet
  • $number = type: number
  • $contextual = type: contextual, also takes a fallbackKey parameter
  • $optionalzwnj = type: optionalzwnj, also takes a fallbackKey parameter
  • $gap
  • $alt0, $alt1, $alt2 = { type: alt, idx: 0 } or 1 or 2

The following cannot be customized:

  • $zwnj
  • $period - use type: base, spec: "." or just . instead

Gap

The GapKey data class represents a gap in the keyboard layout. Instead of a key, a gap will be placed in its place.

Defined in yaml using type: gap, or just use the $gap shortcut.

Enter

The EnterKey data class represents an enter key. Its icon and moreKeys will depend on the input field.

Defined in yaml using type: enter, or just use the $enter shortcut.

Action

The ActionKey data class represents the user-configurable action key. If an action key is not set, then the key will be skipped.

Defined in yaml using type: action, or just use the $action shortcut.

fallbackKey

  • Description: Default key to use in normal text fields that are not listed above
  • Type: Key?
  • Default Value: null

Contextual

The ContextualKey data class represents a contextual key. In specific text field types, it displays a key useful for that text field type, as defined here:

        KeyboardId.MODE_EMAIL    to BaseKey(spec = "@", attributes = attributes),
        KeyboardId.MODE_URL      to BaseKey(spec = "/", attributes = attributes),
        KeyboardId.MODE_DATETIME to BaseKey(spec = "/", moreKeys = listOf(":"), attributes = attributes),
        KeyboardId.MODE_DATE     to BaseKey(spec = "/", attributes = attributes),
        KeyboardId.MODE_TIME     to BaseKey(spec = ":", attributes = attributes),

If the current text field does not match any of the types (e.g. it's a normal text field), it uses the fallbackKey. If fallbackKey is null, or if you use $contextual, then this key will be skipped.

Defined in yaml using type: contextual, or just use the $contextual shortcut.

fallbackKey

  • Description: Default key to use in normal text fields that are not listed above
  • Type: Key?
  • Default Value: null

Enums

Key Widths

The KeyWidth enum represents various width tokens for keys in a keyboard layout. It simplifies the process of specifying key widths by using tokens instead of explicit percentages.

Regular

  • Description: Regular key width, used for normal letters.
  • Behavior:
    • Calculated based on the total keyboard width and maximum number of keys in a row.
    • Consistent across the entire keyboard except in some cases (bottom row, split layout, or rows with functional keys).

FunctionalKey

  • Description: Functional key width, used for functional keys like Shift, Backspace, Enter, and Symbols.
  • Behavior:
    • Has a minimum width specified by the minimumFunctionalKeyWidth property.
    • May be larger than the minimum if there is available space.

Grow

  • Description: Grow width, used for keys that take up remaining space divided evenly among all grow keys in the row.
  • Behavior:
    • Currently not supported in splittable rows.
    • Can complicate width calculation for functional keys and others.
    • Mainly used for spacebar.

Custom1, Custom2, Custom3, Custom4

  • Description: Custom width tokens, defined in the overrideWidths property of the keyboard configuration.
  • Behavior:
    • Values are between 0.0 and 1.0.
    • Used to specify custom widths for specific keys or layouts.

Key Visual Style

The KeyVisualStyle enum represents the visual style of a key in a keyboard layout. It affects the background of the key based on user theme settings.

Normal

  • Description: Uses a normal key background, intended for all letters.
  • Behavior: This may be a rounded rectangle or no background depending on user settings.

NoBackground

  • Description: Uses no key background, intended for number row numbers.
  • Behavior: No background will be shown for this key.

Functional

  • Description: Uses a slightly darker colored background, intended for functional keys (backspace, etc).
  • Behavior: A more visually distinct background is used, it may be dimmer or more saturated.

StickyOff

  • Description: Intended for Shift when it's not shiftlocked.
  • Behavior: Specifies a background for Shift when it's not shiftlocked.

StickyOn

  • Description: Intended for Shift to indicate it's shiftlocked. Uses a more bright background.
  • Behavior: Specifies a brighter background for Shift when it's shiftlocked.

Action

  • Description: Uses a bright fully rounded background, normally used for the enter key.
  • Behavior: Specifies a bright, fully rounded background for the enter key.

Spacebar

  • Description: Depending on the key borders setting, this is either the same as Normal (key borders enabled) or a fully rounded rectangle (key borders disabled).
  • Behavior: Specifies a background for the spacebar key, which may be the same as Normal or a fully rounded rectangle depending on key borders settings.

MoreKey

  • Description: Visual style for moreKeys. Not intended for use in layout definitions.
  • Behavior: Specifies a background for more keys.

More Key Mode

The MoreKeyMode enum specifies which morekeys can be automatically added to the key.

All

  • Description: Insert all possible automatic moreKeys
  • Behavior:
    • Inserts moreKeys from keyspec shortcut.
    • Inserts moreKeys for numbers, symbols, actions, and language letters based on user settings and based on the key's coordinate.
    • Counts towards keyCoordinate.

OnlyFromLetter

  • Description: Only automatically insert morekeys from keyspec shortcut or language-related accents
  • Behavior:
    • Inserts moreKeys from keyspec shortcut, and for language letters based on user settings.
    • Does not count towards keyCoordinate.

OnlyExplicit

  • Description: Do not automatically insert any morekeys.
  • Behavior:
    • Does not count towards keyCoordinate
    • Only moreKeys explicitly defined for the key are included.

BottomRowHeightMode

Represents the height mode of the bottom row in a layout.

Fixed

  • Description: The bottom row height is fixed.

Flexible

  • Description: The bottom row height can vary based on row count.

BottomRowWidthMode

Represents the key width mode of keys in the bottom row.

SeparateFunctional

Identical

  • Description: The functional keys (symbols, enter) follow the functional width from other rows.

RowHeightMode

Represents the height mode of rows in this layout.

ClampHeight

  • Description: The row height is clamped to a reasonable height, row spacing is added to fill the space.

FillHeight

  • Description: The row height fills available height.

NumberRowMode

Represents the behavior of the number row in a layout.

UserConfigurable

  • Description: The number row can be enabled or disabled by the user in typing settings.

AlwaysEnabled

  • Description: The number row is always enabled and visible.

AlwaysDisabled

  • Description: The number row is never enabled or visible.

RowNumberRowMode

Represents the behavior of a row's visibility with respect to the number row in a layout.

Default

  • Description: The row is unaffected by the state of the number row

Filler

  • Description: This row only displays when the number row is active.

Hideable

  • Description: This row only displays when the number row is inactive.

Codes and icons

Codes: (e.g. !code/key_tab)

  • key_tab
  • key_enter
  • key_space
  • key_shift
  • key_capslock
  • key_switch_alpha_symbol
  • key_output_text
  • key_delete
  • key_settings
  • key_shortcut
  • key_action_next
  • key_action_previous
  • key_shift_enter
  • key_language_switch
  • key_emoji
  • key_alpha_from_emoji
  • key_to_number_layout
  • key_to_alt_0_layout
  • key_to_alt_1_layout
  • key_to_alt_2_layout
  • key_unspecified
  • action_{...} (e.g. !code/action_emoji)

Icons: (e.g. !icon/go_key)

  • shift_key
  • shift_key_shifted
  • delete_key
  • settings_key
  • space_key
  • space_key_for_number_layout
  • enter_key
  • go_key
  • search_key
  • send_key
  • next_key
  • done_key
  • previous_key
  • tab_key
  • zwnj_key
  • zwj_key
  • emoji_action_key
  • emoji_normal_key
  • numpad
  • action_{...} (e.g. !icon/action_emoji)

There is no blank icon, but you can set a key's label to a space.

Actions:

  • emoji
  • settings
  • paste
  • text_edit
  • themes
  • undo
  • redo
  • voice_input
  • system_voice_input
  • switch_language
  • clipboard_history
  • mem_dbg
  • cut
  • copy
  • select_all
  • more
  • bugs
  • keyboard_modes
  • up
  • down
  • left
  • right

Combine icon and code with |, e.g. !icon/delete_key|!code/key_delete or !icon/action_emoji|!code/action_emoji.

Example usage:

name: Arrow keys with a and b
rows:
  - letters:
    - "!icon/action_up|!code/action_up"
    - "!icon/action_down|!code/action_down"
    - "!icon/action_left|!code/action_left"
    - "!icon/action_right|!code/action_right"
  - letters:
    - "a"
    - "b"