commonMain.androidx.compose.foundation.text.KeyboardOptions.kt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of foundation-desktop Show documentation
Higher level abstractions of the Compose UI primitives. This library is design system agnostic, providing the high-level building blocks for both application and design-system developers
There is a newer version: 1.8.0-alpha04
Show newest version
/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.compose.foundation.text

import androidx.compose.runtime.Immutable
import androidx.compose.runtime.Stable
import androidx.compose.ui.text.input.ImeAction
import androidx.compose.ui.text.input.ImeOptions
import androidx.compose.ui.text.input.KeyboardCapitalization
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.text.input.PlatformImeOptions
import androidx.compose.ui.text.intl.LocaleList

/**
 * The keyboard configuration options for TextFields. It is not guaranteed if software keyboard
 * will comply with the options provided here.
 *
 * @param capitalization informs the keyboard whether to automatically capitalize characters,
 * words or sentences. Only applicable to only text based [KeyboardType]s such as
 * [KeyboardType.Text], [KeyboardType.Ascii]. It will not be applied to [KeyboardType]s such as
 * [KeyboardType.Number].
 * @param autoCorrectEnabled informs the keyboard whether to enable auto correct. Only applicable to
 * text based [KeyboardType]s such as [KeyboardType.Email], [KeyboardType.Uri]. It will not be
 * applied to [KeyboardType]s such as [KeyboardType.Number]. Most of keyboard implementations ignore
 * this value for [KeyboardType]s such as [KeyboardType.Text]. A null value (the default parameter
 * value) means autocorrect will be enabled.
 * @param keyboardType The keyboard type to be used in this text field. Note that this input type
 * is honored by keyboard and shows corresponding keyboard but this is not guaranteed. For example,
 * some keyboards may send non-ASCII character even if you set [KeyboardType.Ascii].
 * @param imeAction The IME action. This IME action is honored by keyboard and may show specific
 * icons on the keyboard. For example, search icon may be shown if [ImeAction.Search] is specified.
 * When [ImeOptions.singleLine] is false, the keyboard might show return key rather than the action
 * requested here.
 * @param platformImeOptions defines the platform specific IME options.
 * @param showKeyboardOnFocus when true, software keyboard will show on focus gain. When
 * false, the user must interact (e.g. tap) before the keyboard is shown. A null value (the default
 * parameter value) means the keyboard will be shown on focus.
 * @param hintLocales List of the languages that the user is supposed to switch to no matter what
 * input method subtype is currently used. This special "hint" can be used mainly for, but not
 * limited to, multilingual users who want IMEs to switch language based on editor's context.
 * Pass null to express the intention that a specific hint should not be set.
 */
@Immutable
class KeyboardOptions(
    val capitalization: KeyboardCapitalization = KeyboardCapitalization.Unspecified,
    @Suppress("AutoBoxing")
    @get:Suppress("AutoBoxing")
    val autoCorrectEnabled: Boolean? = null,
    val keyboardType: KeyboardType = KeyboardType.Unspecified,
    val imeAction: ImeAction = ImeAction.Unspecified,
    val platformImeOptions: PlatformImeOptions? = null,
    @Suppress("AutoBoxing")
    @get:Suppress("AutoBoxing")
    val showKeyboardOnFocus: Boolean? = null,
    @get:Suppress("NullableCollection")
    val hintLocales: LocaleList? = null,
) {

    companion object {
        /**
         * Default [KeyboardOptions]. Please see parameter descriptions for default values.
         */
        @Stable
        val Default = KeyboardOptions()

        /**
         * Default [KeyboardOptions] for [BasicSecureTextField].
         */
        @Stable
        internal val SecureTextField = KeyboardOptions(
            autoCorrectEnabled = false,
            keyboardType = KeyboardType.Password
        )
    }

    @Deprecated(
        "Please use the new constructor that takes optional autoCorrectEnabled parameter.",
        level = DeprecationLevel.WARNING,
        replaceWith = ReplaceWith(
            "KeyboardOptions(" +
                "capitalization = capitalization, " +
                "autoCorrectEnabled = autoCorrect, " +
                "keyboardType = keyboardType, " +
                "imeAction = imeAction," +
                "platformImeOptions = platformImeOptions, " +
                "showKeyboardOnFocus = showKeyboardOnFocus," +
                "hintLocales = hintLocales" +
                ")"
        )
    )
    constructor(
        capitalization: KeyboardCapitalization = KeyboardCapitalization.Unspecified,
        autoCorrect: Boolean,
        keyboardType: KeyboardType = KeyboardType.Unspecified,
        imeAction: ImeAction = ImeAction.Unspecified,
        platformImeOptions: PlatformImeOptions? = null,
        @Suppress("AutoBoxing")
        showKeyboardOnFocus: Boolean? = null,
        @Suppress("NullableCollection")
        hintLocales: LocaleList? = null,
    ) : this(
        capitalization = capitalization,
        autoCorrectEnabled = autoCorrect,
        keyboardType = keyboardType,
        imeAction = imeAction,
        platformImeOptions = platformImeOptions,
        showKeyboardOnFocus = showKeyboardOnFocus,
        hintLocales = hintLocales,
    )

    @Deprecated(
        "Please use the new constructor that takes optional platformImeOptions parameter.",
        level = DeprecationLevel.HIDDEN
    )
    constructor(
        capitalization: KeyboardCapitalization = KeyboardCapitalization.Unspecified,
        autoCorrect: Boolean = Default.autoCorrectOrDefault,
        keyboardType: KeyboardType = KeyboardType.Unspecified,
        imeAction: ImeAction = ImeAction.Default
    ) : this(
        capitalization = capitalization,
        autoCorrectEnabled = autoCorrect,
        keyboardType = keyboardType,
        imeAction = imeAction,
        platformImeOptions = null
    )

    @Deprecated("Maintained for binary compat", level = DeprecationLevel.HIDDEN)
    constructor(
        capitalization: KeyboardCapitalization = KeyboardCapitalization.None,
        autoCorrect: Boolean = Default.autoCorrectOrDefault,
        keyboardType: KeyboardType = KeyboardType.Text,
        imeAction: ImeAction = ImeAction.Default,
        platformImeOptions: PlatformImeOptions? = null
    ) : this(
        capitalization = capitalization,
        autoCorrectEnabled = autoCorrect,
        keyboardType = keyboardType,
        imeAction = imeAction,
        platformImeOptions = platformImeOptions,
        showKeyboardOnFocus = Default.showKeyboardOnFocusOrDefault
    )

    @Deprecated(
        "Please use the autoCorrectEnabled property.",
        level = DeprecationLevel.WARNING
    )
    val autoCorrect: Boolean get() = autoCorrectOrDefault

    // Suppress GetterSetterNames because this is how the property was named previously.
    @Suppress("unused", "GetterSetterNames")
    @get:Suppress("GetterSetterNames")
    @Deprecated(
        "Included for binary compatibility. Use showKeyboardOnFocus.",
        level = DeprecationLevel.HIDDEN
    )
    val shouldShowKeyboardOnFocus: Boolean get() = showKeyboardOnFocus ?: true

    private val autoCorrectOrDefault: Boolean
        get() = autoCorrectEnabled
            ?: true
    private val capitalizationOrDefault: KeyboardCapitalization
        get() = capitalization.takeUnless { it == KeyboardCapitalization.Unspecified }
            ?: KeyboardCapitalization.None
    private val keyboardTypeOrDefault: KeyboardType
        get() = keyboardType.takeUnless { it == KeyboardType.Unspecified }
            ?: KeyboardType.Text
    internal val imeActionOrDefault: ImeAction
        get() = imeAction.takeUnless { it == ImeAction.Unspecified }
            ?: ImeAction.Default
    internal val showKeyboardOnFocusOrDefault: Boolean
        get() = showKeyboardOnFocus
            ?: true
    private val hintLocalesOrDefault: LocaleList
        get() = hintLocales ?: LocaleList.Empty

    private val isCompletelyUnspecified: Boolean
        get() = capitalization == KeyboardCapitalization.Unspecified &&
            autoCorrectEnabled == null &&
            keyboardType == KeyboardType.Unspecified &&
            imeAction == ImeAction.Unspecified &&
            platformImeOptions == null &&
            showKeyboardOnFocus == null &&
            hintLocales == null

    /**
     * Returns a new [ImeOptions] with the values that are in this [KeyboardOptions] and provided
     * params.
     *
     * @param singleLine see [ImeOptions.singleLine]
     */
    internal fun toImeOptions(singleLine: Boolean = ImeOptions.Default.singleLine) = ImeOptions(
        singleLine = singleLine,
        capitalization = capitalizationOrDefault,
        autoCorrect = autoCorrectOrDefault,
        keyboardType = keyboardTypeOrDefault,
        imeAction = imeActionOrDefault,
        platformImeOptions = platformImeOptions,
        hintLocales = hintLocalesOrDefault
    )

    /**
     * Returns a copy of this object with the values passed to this method.
     *
     * Note that if an unspecified (null) value is passed explicitly to this method, it will replace
     * any actually-specified value. This differs from the behavior of [merge], which will never
     * take an unspecified value over a specified one.
     */
    fun copy(
        capitalization: KeyboardCapitalization = this.capitalization,
        @Suppress("AutoBoxing")
        autoCorrectEnabled: Boolean? = this.autoCorrectEnabled,
        keyboardType: KeyboardType = this.keyboardType,
        imeAction: ImeAction = this.imeAction,
        platformImeOptions: PlatformImeOptions? = this.platformImeOptions,
        @Suppress("AutoBoxing")
        showKeyboardOnFocus: Boolean? = null,
        hintLocales: LocaleList? = null
    ): KeyboardOptions {
        return KeyboardOptions(
            capitalization = capitalization,
            autoCorrectEnabled = autoCorrectEnabled,
            keyboardType = keyboardType,
            imeAction = imeAction,
            platformImeOptions = platformImeOptions,
            showKeyboardOnFocus = showKeyboardOnFocus,
            hintLocales = hintLocales
        )
    }

    @Deprecated(
        "Please use the copy function that takes an autoCorrectEnabled parameter.",
        level = DeprecationLevel.HIDDEN,
        replaceWith = ReplaceWith(
            "copy(" +
                "capitalization = capitalization, " +
                "autoCorrectEnabled = autoCorrect, " +
                "keyboardType = keyboardType, " +
                "imeAction = imeAction," +
                "platformImeOptions = platformImeOptions, " +
                "showKeyboardOnFocus = showKeyboardOnFocus ?: true," +
                "hintLocales = hintLocales" +
                ")"
        )
    )
    fun copy(
        capitalization: KeyboardCapitalization = this.capitalization,
        autoCorrect: Boolean = this.autoCorrectOrDefault,
        keyboardType: KeyboardType = this.keyboardType,
        imeAction: ImeAction = this.imeAction,
        platformImeOptions: PlatformImeOptions? = this.platformImeOptions,
        @Suppress("AutoBoxing")
        showKeyboardOnFocus: Boolean? = this.showKeyboardOnFocusOrDefault,
        hintLocales: LocaleList? = this.hintLocales
    ): KeyboardOptions {
        return KeyboardOptions(
            capitalization = capitalization,
            autoCorrectEnabled = autoCorrect,
            keyboardType = keyboardType,
            imeAction = imeAction,
            platformImeOptions = platformImeOptions,
            showKeyboardOnFocus = showKeyboardOnFocus,
            hintLocales = hintLocales
        )
    }

    @Deprecated(
        "Maintained for binary compatibility",
        level = DeprecationLevel.HIDDEN
    )
    fun copy(
        capitalization: KeyboardCapitalization = this.capitalization,
        autoCorrect: Boolean = this.autoCorrectOrDefault,
        keyboardType: KeyboardType = this.keyboardType,
        imeAction: ImeAction = this.imeAction,
        platformImeOptions: PlatformImeOptions? = this.platformImeOptions
    ): KeyboardOptions {
        return KeyboardOptions(
            capitalization = capitalization,
            autoCorrectEnabled = autoCorrect,
            keyboardType = keyboardType,
            imeAction = imeAction,
            platformImeOptions = platformImeOptions,
            showKeyboardOnFocus = this.showKeyboardOnFocus,
            hintLocales = this.hintLocales
            // New properties must be added here even though this is deprecated. The deprecated copy
            // constructors should still work on instances created with newer library versions.
        )
    }

    @Deprecated(
        "Please use the new copy function that takes optional platformImeOptions parameter.",
        level = DeprecationLevel.HIDDEN
    )
    fun copy(
        capitalization: KeyboardCapitalization = this.capitalization,
        autoCorrect: Boolean = this.autoCorrectOrDefault,
        keyboardType: KeyboardType = this.keyboardType,
        imeAction: ImeAction = this.imeAction
    ): KeyboardOptions {
        return KeyboardOptions(
            capitalization = capitalization,
            autoCorrectEnabled = autoCorrect,
            keyboardType = keyboardType,
            imeAction = imeAction,
            platformImeOptions = this.platformImeOptions,
            showKeyboardOnFocus = this.showKeyboardOnFocus,
            hintLocales = this.hintLocales
            // New properties must be added here even though this is deprecated. The deprecated copy
            // constructors should still work on instances created with newer library versions.
        )
    }

    override fun equals(other: Any?): Boolean {
        if (this === other) return true
        if (other !is KeyboardOptions) return false

        if (capitalization != other.capitalization) return false
        if (autoCorrectEnabled != other.autoCorrectEnabled) return false
        if (keyboardType != other.keyboardType) return false
        if (imeAction != other.imeAction) return false
        if (platformImeOptions != other.platformImeOptions) return false
        if (showKeyboardOnFocus != other.showKeyboardOnFocus) return false
        if (hintLocales != other.hintLocales) return false

        return true
    }

    override fun hashCode(): Int {
        var result = capitalization.hashCode()
        result = 31 * result + autoCorrectEnabled.hashCode()
        result = 31 * result + keyboardType.hashCode()
        result = 31 * result + imeAction.hashCode()
        result = 31 * result + platformImeOptions.hashCode()
        result = 31 * result + showKeyboardOnFocus.hashCode()
        result = 31 * result + hintLocales.hashCode()
        return result
    }

    override fun toString(): String {
        return "KeyboardOptions(" +
            "capitalization=$capitalization, " +
            "autoCorrectEnabled=$autoCorrectEnabled, " +
            "keyboardType=$keyboardType, " +
            "imeAction=$imeAction, " +
            "platformImeOptions=$platformImeOptions" +
            "showKeyboardOnFocus=$showKeyboardOnFocus, " +
            "hintLocales=$hintLocales" +
            ")"
    }

    /**
     * Returns a new [KeyboardOptions] that is a combination of this options and a given [other]
     * options.
     *
     * [other]s null or `Unspecified` properties are replaced with the non-null properties of
     * this object.
     *
     * If the either this or [other] is null, returns the non-null one.
     */
    // TODO(b/331222000) Rename to be more clear about precedence.
    fun merge(other: KeyboardOptions?): KeyboardOptions =
        other?.fillUnspecifiedValuesWith(this) ?: this

    /**
     * Returns a new [KeyboardOptions] that is a combination of this options and a given [other]
     * options.
     *
     * This object's null or `Unspecified` properties are replaced with the non-null properties of
     * [other]. This differs from the behavior of [copy], which always takes the
     * passed value over the current one, even if an unspecified value is passed.
     *
     * If the either this or [other] is null, returns the non-null one.
     */
    @Stable
    internal fun fillUnspecifiedValuesWith(other: KeyboardOptions?): KeyboardOptions {
        // Don't allocate unless necessary.
        if (other == null || other.isCompletelyUnspecified || other == this) return this
        if (this.isCompletelyUnspecified) return other

        return KeyboardOptions(
            capitalization = this.capitalization
                .takeUnless { it == KeyboardCapitalization.Unspecified }
                ?: other.capitalization,
            autoCorrectEnabled = this.autoCorrectEnabled
                ?: other.autoCorrectEnabled,
            keyboardType = this.keyboardType
                .takeUnless { it == KeyboardType.Unspecified }
                ?: other.keyboardType,
            imeAction = this.imeAction
                .takeUnless { it == ImeAction.Unspecified }
                ?: other.imeAction,
            platformImeOptions = this.platformImeOptions
                ?: other.platformImeOptions,
            showKeyboardOnFocus = this.showKeyboardOnFocus
                ?: other.showKeyboardOnFocus,
            hintLocales = this.hintLocales
                ?: other.hintLocales
        )
    }
}