package org.futo.inputmethod.v2keyboard
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.builtins.serializer
import org.futo.inputmethod.keyboard.KeyConsts
import org.futo.inputmethod.keyboard.KeyboardId
import org.futo.inputmethod.keyboard.internal.KeySpecParser
import org.futo.inputmethod.keyboard.internal.KeyboardParams
import org.futo.inputmethod.keyboard.internal.MoreKeySpec
import org.futo.inputmethod.latin.common.Constants
import org.futo.inputmethod.latin.common.StringUtils
import org.futo.inputmethod.latin.settings.LongPressKeySettings
/**
* Width tokens for keys. Rather than explicitly specifying a width in percentage as is common in
* other layout systems, we instead use width tokens, which eliminates the need to explicitly
* calculate and specify width percentages for most cases.
*/
@Serializable
enum class KeyWidth {
/**
* Regular key width. Used for normal letters (QWERTY etc)
*
* ##### Width calculation
* Simply put, the width of this is calculated by dividing the total keyboard width by the
* maximum number of keys in a row. It is consistent across the entire keyboard except in some cases.
*
* For example, if a keyboard has 3 rows, with 10, 9, and 7 keys respectively,
* the regular key width will be 100% / 10 = 10% for the entire keyboard.
* The rows with 9 and 7 keys will receive padding by default to keep them centered due
* to the extra space.
*
* There are 3 cases where regular width will be inconsistent:
* 1. In the bottom row
* 2. In the split layout, to maintain middle alignment
* 3. In a row with functional keys (shift or delete), in order to maintain a minimum functional key width
*/
Regular,
/**
* Functional key width. Used for functional keys (Shift, Backspace, Enter, Symbols, etc)
*
* ##### Width calculation
* The width of this is at least the value specified in [Keyboard.minimumFunctionalKeyWidth]
* or, for the bottom row, [Keyboard.minimumBottomRowFunctionalKeyWidth].
*
* The width may be larger than the minimum if the available space is there.
* For example on the QWERTY layout, the ZXCV row has only 7 keys at a width of 10%, using up
* only 70% of space. The remaining 30% of space is divided among the shift and backspace,
* meaning the functional width is 15%.
*/
FunctionalKey,
/**
* Grow width. Takes up all remaining space divided evenly among all grow keys in the row.
* Mainly used for spacebar.
*
* Grow keys are not supported in split layouts, and their presence can complicate width
* calculation for functional keys and others. Avoid use when possible.
*/
Grow,
/**
* The Custom1 width as defined in [Keyboard.overrideWidths] (values are between 0.0 and 1.0)
*/
Custom1,
/**
* The Custom2 width as defined in [Keyboard.overrideWidths] (values are between 0.0 and 1.0)
*/
Custom2,
/**
* The Custom3 width as defined in [Keyboard.overrideWidths] (values are between 0.0 and 1.0)
*/
Custom3,
/**
* The Custom4 width as defined in [Keyboard.overrideWidths] (values are between 0.0 and 1.0)
*/
Custom4,
}
/**
* Specifies which morekeys can be automatically added to the key.
*/
@Serializable
enum class MoreKeyMode(
val autoFromKeyspec: Boolean,
val autoNumFromCoord: Boolean,
val autoSymFromCoord: Boolean,
val autoFromLanguageKey: Boolean,
) {
/**
* Automatically insert morekeys from keyspec shortcuts, as well as numbers, symbols and actions
* (if not disabled by user). These count towards KeyCoordinate.
*/
All(true, true, true, true),
/**
* Only automatically insert morekeys from keyspec shortcut or language-related accents
*/
OnlyFromLetter(true, false, false, true),
/**
* Do not automatically insert any morekeys.
*/
OnlyExplicit(false, false, false, false),
}
private fun Int.and(other: Boolean): Int {
return if(other) { this } else { 0 }
}
/**
* Flags for the key label
*/
@Serializable
data class LabelFlags(
val alignHintLabelToBottom: Boolean = false,
val alignIconToBottom: Boolean = false,
val alignLabelOffCenter: Boolean = false,
val hasHintLabel: Boolean = false,
val followKeyLabelRatio: Boolean = false,
val followKeyLetterRatio: Boolean = false,
val followKeyLargeLetterRatio: Boolean = false,
val autoXScale: Boolean = false,
) {
fun getValue(): Int =
KeyConsts.LABEL_FLAGS_ALIGN_LABEL_OFF_CENTER.and(alignLabelOffCenter) or
KeyConsts.LABEL_FLAGS_ALIGN_HINT_LABEL_TO_BOTTOM.and(alignHintLabelToBottom) or
KeyConsts.LABEL_FLAGS_ALIGN_ICON_TO_BOTTOM.and(alignIconToBottom) or
KeyConsts.LABEL_FLAGS_HAS_HINT_LABEL.and(hasHintLabel) or
KeyConsts.LABEL_FLAGS_FOLLOW_KEY_LABEL_RATIO.and(followKeyLabelRatio) or
KeyConsts.LABEL_FLAGS_FOLLOW_KEY_LETTER_RATIO.and(followKeyLetterRatio) or
KeyConsts.LABEL_FLAGS_FOLLOW_KEY_LARGE_LETTER_RATIO.and(followKeyLargeLetterRatio) or
KeyConsts.LABEL_FLAGS_AUTO_X_SCALE.and(autoXScale)
}
/**
* Attributes for keys.
*
* Values are inherited in the following order:
* `Key.attributes > Row.attributes > Keyboard.attributes > DefaultKeyAttributes`
*/
@Serializable
data class KeyAttributes(
/**
* Key width token
*/
val width: KeyWidth? = null,
/**
* Visual style (background) for the key
*/
val style: KeyVisualStyle? = null,
/**
* Whether or not to anchor the key to the edges.
*
* When a row is not wide enough to fill 100%, padding is added to the edges of the row.
* If there are anchored keys in the row, the padding will be added after the anchored
* keys, keeping the anchored keys at the edge.
*/
val anchored: Boolean? = null,
/**
* Whether or not to show the popup indicator when the key is pressed.
* This is usually desirable for letters on normal layouts (QWERTY letters), but undesirable
* for functional keys (Shift, Backspace), or certain layouts (phone layout)
*/
val showPopup: Boolean? = null,
/**
* Which moreKeys to add automatically
*/
val moreKeyMode: MoreKeyMode? = null,
/**
* Whether or not to use keyspec shortcuts.
* For example, `$` gets automatically converted to `!text/keyspec_currency`.
*
* The full list of keyspec shortcuts is defined in `KeySpecShortcuts`.
*/
val useKeySpecShortcut: Boolean? = null,
/**
* Whether or not longpress is enabled for the key
*/
val longPressEnabled: Boolean? = null,
/**
* Label flags for how the key's label (and its hint) should be presented
*/
val labelFlags: LabelFlags? = null,
/**
* Whether or not the key is repeatable, intended for backspace
*/
val repeatableEnabled: Boolean? = null,
/**
* Whether or not the key is automatically shiftable. If true, it 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].
*/
val shiftable: Boolean? = null,
) {
fun getEffectiveAttributes(row: Row, keyboard: Keyboard): KeyAttributes {
val attrs = if(row.isBottomRow) {
listOf(this, row.attributes, DefaultKeyAttributes)
} else {
listOf(this, row.attributes, keyboard.attributes, DefaultKeyAttributes)
}
val effectiveWidth = resolve(attrs) { it.width }
val defaultMoreKeyMode = if((row.isLetterRow || row.isBottomRow) && effectiveWidth == KeyWidth.Regular) {
MoreKeyMode.All
} else {
MoreKeyMode.OnlyFromLetter
}
return KeyAttributes(
width = resolve(attrs) { it.width },
style = resolve(attrs) { it.style },
anchored = resolve(attrs) { it.anchored },
showPopup = resolve(attrs) { it.showPopup },
moreKeyMode = resolve(attrs) { it.moreKeyMode } ?: defaultMoreKeyMode,
useKeySpecShortcut = resolve(attrs) { it.useKeySpecShortcut },
longPressEnabled = resolve(attrs) { it.longPressEnabled },
labelFlags = resolve(attrs) { it.labelFlags },
repeatableEnabled = resolve(attrs) { it.repeatableEnabled },
shiftable = resolve(attrs) { it.shiftable },
)
}
}
private fun<T, O> resolve(attributes: List<O>, getter: (O) -> T?): T? =
attributes.firstNotNullOfOrNull(getter)
val DefaultKeyAttributes = KeyAttributes(
width = KeyWidth.Regular,
style = KeyVisualStyle.Normal,
anchored = false,
showPopup = true,
moreKeyMode = null, // Default value is calculated in getEffectiveAttributes based on other attribute values
useKeySpecShortcut = true,
longPressEnabled = false,
labelFlags = LabelFlags(autoXScale = true),
repeatableEnabled = false,
shiftable = true,
)
object MoreKeysListSerializer: SpacedListSerializer<String>(String.serializer(), {
MoreKeySpec.splitKeySpecs(it)?.toList() ?: listOf()
})
/**
* The base key
*/
@Serializable
@SerialName("base")
data class BaseKey(
/**
* AOSP key spec. It can contain a custom label, code, icon, output text.
*
* 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 {@link KeyboardCodesSet}.
*
* 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.
*/
val spec: String,
/**
* Attributes for this key. Values defined here supersede any other values. Values which are
* not defined are inherited from the row, keyboard, or default attributes.
*/
val attributes: KeyAttributes = KeyAttributes(),
/**
* More keys for this key. In YAML, it can be defined as a list or a comma-separated string.
*
* The values here are key specs.
*/
val moreKeys: @Serializable(with = MoreKeysListSerializer::class) List<String> = listOf(),
/**
* If set, overrides a default hint from the value of moreKeys.
*/
val hint: String? = null,
) : AbstractKey {
override fun countsToKeyCoordinate(params: KeyboardParams, row: Row, keyboard: Keyboard): Boolean {
val attributes = attributes.getEffectiveAttributes(row, keyboard)
val moreKeyMode = attributes.moreKeyMode!!
return moreKeyMode.autoNumFromCoord && moreKeyMode.autoSymFromCoord
}
override fun computeData(params: KeyboardParams, row: Row, keyboard: Keyboard, coordinate: KeyCoordinate): ComputedKeyData {
val attributes = attributes.getEffectiveAttributes(row, keyboard)
val shifted = (attributes.shiftable == true) && when(params.mId.mElementId) {
KeyboardId.ELEMENT_SYMBOLS_SHIFTED -> true
KeyboardId.ELEMENT_ALPHABET_SHIFT_LOCK_SHIFTED -> true
KeyboardId.ELEMENT_ALPHABET_MANUAL_SHIFTED -> true
KeyboardId.ELEMENT_ALPHABET_SHIFT_LOCKED -> true
KeyboardId.ELEMENT_ALPHABET_AUTOMATIC_SHIFTED -> true
else -> false
}
val relevantSpecShortcut = if(attributes.useKeySpecShortcut != false || attributes.moreKeyMode?.autoFromKeyspec != false) {
resolveSpecWithOptionalShortcut(spec, params.mTextsSet, coordinate)
} else {
null
}
val expandedSpec: String? = params.mTextsSet.resolveTextReference(
if(attributes.useKeySpecShortcut != false) { relevantSpecShortcut?.get(0) } else { null }
?: spec
)
val label = expandedSpec?.let { KeySpecParser.getLabel(it) } ?: ""
val icon = expandedSpec?.let { KeySpecParser.getIconId(it) } ?: ""
val code = KeySpecParser.getCode(expandedSpec)
val outputText = KeySpecParser.getOutputText(expandedSpec)
val moreKeyMode = attributes.moreKeyMode!!
var moreKeysBuilder = MoreKeysBuilder(code = code, mode = moreKeyMode, coordinate = coordinate, row = row, keyboard = keyboard, params = params)
// 1. Add layout-defined moreKeys
moreKeysBuilder =
moreKeysBuilder.insertMoreKeys(LongPressKeySettings.joinMoreKeys(moreKeys))
// 2. Add moreKeys from keyspec
if (moreKeyMode.autoFromKeyspec) {
moreKeysBuilder =
moreKeysBuilder.insertMoreKeys(getDefaultMoreKeysForKey(code, relevantSpecShortcut))
}
// 3. Add settings-defined moreKeys (numbers, symbols, actions, language, etc) in their order
params.mId.mLongPressKeySettings.currentOrder.forEach {
moreKeysBuilder = moreKeysBuilder.insertMoreKeys(it)
}
// 4. Add special (period and comma)
if (moreKeyMode.autoSymFromCoord) {
moreKeysBuilder =
moreKeysBuilder.insertMoreKeys(getSpecialFromRow(coordinate, row))
}
val moreKeys = moreKeysBuilder.build(shifted)
return ComputedKeyData(
label = if(shifted) {
StringUtils.toTitleCaseOfKeyLabel(label, params.mId.locale) ?: label
} else {
label
},
code = if(shifted) {
StringUtils.toTitleCaseOfKeyCode(code, params.mId.locale)
} else {
code
},
outputText = outputText,
width = attributes.width!!,
icon = icon,
style = attributes.style!!,
anchored = attributes.anchored!!,
showPopup = attributes.showPopup!!,
moreKeys = moreKeys.specs,
longPressEnabled = (attributes.longPressEnabled ?: false) || moreKeys.specs.isNotEmpty(),
repeatable = attributes.repeatableEnabled ?: false,
moreKeyFlags = moreKeys.flags,
countsToKeyCoordinate = moreKeyMode.autoNumFromCoord && moreKeyMode.autoSymFromCoord,
hint = hint ?: "",
labelFlags = attributes.labelFlags?.getValue() ?: 0
)
}
}
/**
* Case selector key. Allows specifying a different type of key depending on when the layout is
* shifted or not.
*/
@Serializable
@SerialName("case")
data class CaseSelector(
/**
* Key to use normally
*/
val normal: Key,
/**
* Key to use when shifted
*/
val shifted: Key = normal,
/**
* Key to use when shifted, excluding automatic shift
*/
val shiftedManually: Key = shifted,
/**
* Key to use when shift locked (caps lock), defaults to [shiftedManually]
*/
val shiftLocked: Key = shiftedManually,
/**
* Key to use when in symbols layout, defaults to [normal]. Mainly used internally for
* [TemplateShiftKey]
*/
val symbols: Key = normal,
/**
* Key to use when in symbols layout, defaults to [normal]. Mainly used internally for
* [TemplateShiftKey]
*/
val symbolsShifted: Key = normal
) : AbstractKey {
private fun selectKeyFromElement(elementId: Int): Key =
when(elementId) {
KeyboardId.ELEMENT_ALPHABET -> normal
KeyboardId.ELEMENT_ALPHABET_AUTOMATIC_SHIFTED -> shifted
KeyboardId.ELEMENT_ALPHABET_MANUAL_SHIFTED -> shiftedManually
// KeyboardState.kt currently doesn't distinguish between these
KeyboardId.ELEMENT_ALPHABET_SHIFT_LOCKED,
KeyboardId.ELEMENT_ALPHABET_SHIFT_LOCK_SHIFTED -> shiftLocked
KeyboardId.ELEMENT_SYMBOLS -> symbols
KeyboardId.ELEMENT_SYMBOLS_SHIFTED -> symbolsShifted
else -> normal
}
override fun countsToKeyCoordinate(params: KeyboardParams, row: Row, keyboard: Keyboard): Boolean =
selectKeyFromElement(params.mId.mElementId).countsToKeyCoordinate(params, row, keyboard)
override fun computeData(
params: KeyboardParams,
row: Row,
keyboard: Keyboard,
coordinate: KeyCoordinate
): ComputedKeyData? =
selectKeyFromElement(params.mId.mElementId).computeData(params, row, keyboard, coordinate)
}
typealias Key = @Serializable(with = KeyPathSerializer::class) AbstractKey
object KeyPathSerializer : PathDependentModifier<AbstractKey>(
KeyContextualSerializer, { path, v ->
if(v is BaseKey) {
v
} else {
v
}
}
)
object KeyContextualSerializer : ClassOrScalarsSerializer<AbstractKey>(
AbstractKey.serializer(),
{ contents ->
assert(contents.isNotEmpty()) { "Key requires at least 1 element" }
if(contents[0].startsWith("$") && contents[0] != "$" && contents.size == 1) {
TemplateKeys[contents[0].trimStart('$')]
?: throw IllegalStateException("Unknown template key $contents")
} else {
if(contents.size == 1) {
BaseKey(contents[0])
} else {
val moreKeys = contents.subList(1, contents.size)
BaseKey(contents[0], moreKeys = moreKeys)
}
}
}
)
/**
* Affects the background for the key. Depending on the user theme settings, backgrounds may be
* different.
*/
@Serializable
enum class KeyVisualStyle {
/**
* Uses a normal key background, intended for all letters.
*/
Normal,
/**
* Uses no key background, intended for number row numbers.
*/
NoBackground,
/**
* Uses a slightly darker colored background, intended for functional keys (backspace, etc)
*/
Functional,
/**
* Intended for Shift when it's not shiftlocked
*/
StickyOff,
/**
* Intended for Shift to indicate it's shiftlocked. Uses a more bright background
*/
StickyOn,
/**
* Uses a bright fully rounded background, normally used for the enter key
*/
Action,
/**
* Depending on the key borders setting, this is either
* the same as [Normal] (key borders enabled) or a
* fully rounded rectangle (key borders disabled)
*/
Spacebar,
/**
* Visual style for moreKeys
*/
MoreKey,
}
/**
* An empty gap in place of a key
*/
@Serializable
@SerialName("gap")
class GapKey(val attributes: KeyAttributes = KeyAttributes()) : AbstractKey {
override fun countsToKeyCoordinate(params: KeyboardParams, row: Row, keyboard: Keyboard): Boolean = false
override fun computeData(
params: KeyboardParams,
row: Row,
keyboard: Keyboard,
coordinate: KeyCoordinate
): ComputedKeyData {
val attributes = attributes.getEffectiveAttributes(row, keyboard)
val moreKeyMode = attributes.moreKeyMode!!
return ComputedKeyData(
label = "",
code = Constants.CODE_UNSPECIFIED,
outputText = null,
width = attributes.width!!,
icon = "",
style = KeyVisualStyle.NoBackground,
anchored = attributes.anchored!!,
showPopup = false,
moreKeys = listOf(),
longPressEnabled = false,
repeatable = false,
moreKeyFlags = 0,
countsToKeyCoordinate = moreKeyMode.autoNumFromCoord && moreKeyMode.autoSymFromCoord,
hint = "",
labelFlags = 0
)
}
}