1 /*
2  * Copyright 2020 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.compose.ui.text.input
18 
19 import androidx.compose.runtime.Immutable
20 import androidx.compose.ui.text.intl.LocaleList
21 
22 /**
23  * The IME configuration options for [TextInputService]. It is not guaranteed if IME will comply
24  * with the options provided here.
25  *
26  * @param singleLine informs the IME that the text field is single line and IME should not show
27  *   return key.
28  * @param capitalization informs the IME whether to automatically capitalize characters, words or
29  *   sentences. Only applicable to only text based [KeyboardType]s such as [KeyboardType.Text],
30  *   [KeyboardType.Ascii]. It will not be applied to [KeyboardType]s such as [KeyboardType.Number]
31  *   or [KeyboardType.Decimal].
32  * @param autoCorrect informs the IME whether to enable auto correct. Only applicable to text based
33  *   [KeyboardType]s such as [KeyboardType.Email], [KeyboardType.Uri]. It will not be applied to
34  *   [KeyboardType]s such as [KeyboardType.Number] or [KeyboardType.Decimal]. Most of IME
35  *   implementations ignore this value for [KeyboardType]s such as [KeyboardType.Text].
36  * @param keyboardType The keyboard type to be used in this text field. Note that this input type is
37  *   honored by IME and shows corresponding keyboard but this is not guaranteed. For example, some
38  *   IME may send non-ASCII character even if you set [KeyboardType.Ascii].
39  * @param imeAction The IME action. This IME action is honored by IME and may show specific icons on
40  *   the keyboard. For example, search icon may be shown if [ImeAction.Search] is specified. When
41  *   [singleLine] is false, the IME might show return key rather than the action requested here.
42  * @param platformImeOptions defines the platform specific IME options.
43  * @param hintLocales List of the languages that the user is supposed to switch to no matter what
44  *   input method subtype is currently used. This special "hint" can be used mainly for, but not
45  *   limited to, multilingual users who want IMEs to switch language based on editor's context. Pass
46  *   [LocaleList.Empty] to express the intention that a specific hint should not be set.
47  */
48 @Immutable
49 class ImeOptions(
50     val singleLine: Boolean = false,
51     val capitalization: KeyboardCapitalization = KeyboardCapitalization.None,
52     val autoCorrect: Boolean = true,
53     val keyboardType: KeyboardType = KeyboardType.Text,
54     val imeAction: ImeAction = ImeAction.Default,
55     val platformImeOptions: PlatformImeOptions? = null,
56     val hintLocales: LocaleList = LocaleList.Empty
57 ) {
58     companion object {
59         /** Default [ImeOptions]. Please see parameter descriptions for default values. */
60         val Default = ImeOptions()
61     }
62 
63     @Deprecated(
64         "Please use the new constructor that takes optional hintLocales parameter.",
65         level = DeprecationLevel.HIDDEN
66     )
67     constructor(
68         singleLine: Boolean = false,
69         capitalization: KeyboardCapitalization = KeyboardCapitalization.None,
70         autoCorrect: Boolean = true,
71         keyboardType: KeyboardType = KeyboardType.Text,
72         imeAction: ImeAction = ImeAction.Default,
73         platformImeOptions: PlatformImeOptions? = null
74     ) : this(
75         singleLine = singleLine,
76         capitalization = capitalization,
77         autoCorrect = autoCorrect,
78         keyboardType = keyboardType,
79         imeAction = imeAction,
80         platformImeOptions = platformImeOptions,
81         hintLocales = LocaleList.Empty
82     )
83 
84     @Deprecated(
85         "Please use the new constructor that takes optional platformImeOptions parameter.",
86         level = DeprecationLevel.HIDDEN
87     )
88     constructor(
89         singleLine: Boolean = false,
90         capitalization: KeyboardCapitalization = KeyboardCapitalization.None,
91         autoCorrect: Boolean = true,
92         keyboardType: KeyboardType = KeyboardType.Text,
93         imeAction: ImeAction = ImeAction.Default,
94     ) : this(
95         singleLine = singleLine,
96         capitalization = capitalization,
97         autoCorrect = autoCorrect,
98         keyboardType = keyboardType,
99         imeAction = imeAction,
100         platformImeOptions = null
101     )
102 
copynull103     fun copy(
104         singleLine: Boolean = this.singleLine,
105         capitalization: KeyboardCapitalization = this.capitalization,
106         autoCorrect: Boolean = this.autoCorrect,
107         keyboardType: KeyboardType = this.keyboardType,
108         imeAction: ImeAction = this.imeAction,
109         platformImeOptions: PlatformImeOptions? = this.platformImeOptions,
110         hintLocales: LocaleList = this.hintLocales
111     ): ImeOptions {
112         return ImeOptions(
113             singleLine = singleLine,
114             capitalization = capitalization,
115             autoCorrect = autoCorrect,
116             keyboardType = keyboardType,
117             imeAction = imeAction,
118             platformImeOptions = platformImeOptions,
119             hintLocales = hintLocales
120         )
121     }
122 
123     @Deprecated(
124         "Please use the new copy function that takes optional hintLocales parameter.",
125         level = DeprecationLevel.HIDDEN
126     )
copynull127     fun copy(
128         singleLine: Boolean = this.singleLine,
129         capitalization: KeyboardCapitalization = this.capitalization,
130         autoCorrect: Boolean = this.autoCorrect,
131         keyboardType: KeyboardType = this.keyboardType,
132         imeAction: ImeAction = this.imeAction,
133         platformImeOptions: PlatformImeOptions? = this.platformImeOptions
134     ): ImeOptions {
135         return ImeOptions(
136             singleLine = singleLine,
137             capitalization = capitalization,
138             autoCorrect = autoCorrect,
139             keyboardType = keyboardType,
140             imeAction = imeAction,
141             platformImeOptions = platformImeOptions,
142             hintLocales = this.hintLocales
143         )
144     }
145 
146     @Deprecated(
147         "Please use the new copy function that takes optional platformImeOptions parameter.",
148         level = DeprecationLevel.HIDDEN
149     )
copynull150     fun copy(
151         singleLine: Boolean = this.singleLine,
152         capitalization: KeyboardCapitalization = this.capitalization,
153         autoCorrect: Boolean = this.autoCorrect,
154         keyboardType: KeyboardType = this.keyboardType,
155         imeAction: ImeAction = this.imeAction
156     ): ImeOptions {
157         return ImeOptions(
158             singleLine = singleLine,
159             capitalization = capitalization,
160             autoCorrect = autoCorrect,
161             keyboardType = keyboardType,
162             imeAction = imeAction,
163             platformImeOptions = this.platformImeOptions,
164             hintLocales = this.hintLocales
165         )
166     }
167 
equalsnull168     override fun equals(other: Any?): Boolean {
169         if (this === other) return true
170         if (other !is ImeOptions) return false
171 
172         if (singleLine != other.singleLine) return false
173         if (capitalization != other.capitalization) return false
174         if (autoCorrect != other.autoCorrect) return false
175         if (keyboardType != other.keyboardType) return false
176         if (imeAction != other.imeAction) return false
177         if (platformImeOptions != other.platformImeOptions) return false
178         if (hintLocales != other.hintLocales) return false
179 
180         return true
181     }
182 
hashCodenull183     override fun hashCode(): Int {
184         var result = singleLine.hashCode()
185         result = 31 * result + capitalization.hashCode()
186         result = 31 * result + autoCorrect.hashCode()
187         result = 31 * result + keyboardType.hashCode()
188         result = 31 * result + imeAction.hashCode()
189         result = 31 * result + platformImeOptions.hashCode()
190         result = 31 * result + hintLocales.hashCode()
191         return result
192     }
193 
toStringnull194     override fun toString(): String {
195         return "ImeOptions(singleLine=$singleLine, capitalization=$capitalization, " +
196             "autoCorrect=$autoCorrect, keyboardType=$keyboardType, imeAction=$imeAction, " +
197             "platformImeOptions=$platformImeOptions, hintLocales=$hintLocales)"
198     }
199 }
200