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
The 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
        )
    }
}