1 /* 2 * Copyright (C) 2008 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 android.text; 18 19 import android.view.inputmethod.InputConnection; 20 import android.view.inputmethod.TextAttribute; 21 import android.view.inputmethod.TextAttribute.Builder; 22 23 import java.util.List; 24 25 /** 26 * Bit definitions for an integer defining the basic content type of text 27 * held in an {@link Editable} object. Supported classes may be combined 28 * with variations and flags to indicate desired behaviors. 29 * 30 * <h3>Examples</h3> 31 * 32 * <dl> 33 * <dt>A password field with the password visible to the user: 34 * <dd>inputType = TYPE_CLASS_TEXT | 35 * TYPE_TEXT_VARIATION_VISIBLE_PASSWORD 36 * 37 * <dt>A multi-line postal address with automatic capitalization: 38 * <dd>inputType = TYPE_CLASS_TEXT | 39 * TYPE_TEXT_VARIATION_POSTAL_ADDRESS | 40 * TYPE_TEXT_FLAG_MULTI_LINE 41 * 42 * <dt>A time field: 43 * <dd>inputType = TYPE_CLASS_DATETIME | 44 * TYPE_DATETIME_VARIATION_TIME 45 * </dl> 46 */ 47 @android.ravenwood.annotation.RavenwoodKeepWholeClass 48 public interface InputType { 49 /** 50 * Mask of bits that determine the overall class 51 * of text being given. Currently supported classes are: 52 * {@link #TYPE_CLASS_TEXT}, {@link #TYPE_CLASS_NUMBER}, 53 * {@link #TYPE_CLASS_PHONE}, {@link #TYPE_CLASS_DATETIME}. 54 * <p>IME authors: If the class is not one you 55 * understand, assume {@link #TYPE_CLASS_TEXT} with NO variation 56 * or flags.<p> 57 */ 58 public static final int TYPE_MASK_CLASS = 0x0000000f; 59 60 /** 61 * Mask of bits that determine the variation of 62 * the base content class. 63 */ 64 public static final int TYPE_MASK_VARIATION = 0x00000ff0; 65 66 /** 67 * Mask of bits that provide addition bit flags 68 * of options. 69 */ 70 public static final int TYPE_MASK_FLAGS = 0x00fff000; 71 72 /** 73 * Special content type for when no explicit type has been specified. 74 * This should be interpreted to mean that the target input connection 75 * is not rich, it can not process and show things like candidate text nor 76 * retrieve the current text, so the input method will need to run in a 77 * limited "generate key events" mode, if it supports it. Note that some 78 * input methods may not support it, for example a voice-based input 79 * method will likely not be able to generate key events even if this 80 * flag is set. 81 */ 82 public static final int TYPE_NULL = 0x00000000; 83 84 // ---------------------------------------------------------------------- 85 // ---------------------------------------------------------------------- 86 // ---------------------------------------------------------------------- 87 88 /** 89 * Class for normal text. This class supports the following flags (only 90 * one of which should be set): 91 * {@link #TYPE_TEXT_FLAG_CAP_CHARACTERS}, 92 * {@link #TYPE_TEXT_FLAG_CAP_WORDS}, and. 93 * {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}. It also supports the 94 * following variations: 95 * {@link #TYPE_TEXT_VARIATION_NORMAL}, and 96 * {@link #TYPE_TEXT_VARIATION_URI}. If you do not recognize the 97 * variation, normal should be assumed. 98 */ 99 public static final int TYPE_CLASS_TEXT = 0x00000001; 100 101 /** 102 * Flag for {@link #TYPE_CLASS_TEXT}: capitalize all characters. Overrides 103 * {@link #TYPE_TEXT_FLAG_CAP_WORDS} and 104 * {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}. This value is explicitly defined 105 * to be the same as {@link TextUtils#CAP_MODE_CHARACTERS}. Of course, 106 * this only affects languages where there are upper-case and lower-case letters. 107 */ 108 public static final int TYPE_TEXT_FLAG_CAP_CHARACTERS = 0x00001000; 109 110 /** 111 * Flag for {@link #TYPE_CLASS_TEXT}: capitalize the first character of 112 * every word. Overrides {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}. This 113 * value is explicitly defined 114 * to be the same as {@link TextUtils#CAP_MODE_WORDS}. Of course, 115 * this only affects languages where there are upper-case and lower-case letters. 116 */ 117 public static final int TYPE_TEXT_FLAG_CAP_WORDS = 0x00002000; 118 119 /** 120 * Flag for {@link #TYPE_CLASS_TEXT}: capitalize the first character of 121 * each sentence. This value is explicitly defined 122 * to be the same as {@link TextUtils#CAP_MODE_SENTENCES}. For example 123 * in English it means to capitalize after a period and a space (note that other 124 * languages may have different characters for period, or not use spaces, 125 * or use different grammatical rules). Of course, 126 * this only affects languages where there are upper-case and lower-case letters. 127 */ 128 public static final int TYPE_TEXT_FLAG_CAP_SENTENCES = 0x00004000; 129 130 /** 131 * Flag for {@link #TYPE_CLASS_TEXT}: the user is entering free-form 132 * text that should have auto-correction applied to it. Without this flag, 133 * the IME will not try to correct typos. You should always set this flag 134 * unless you really expect users to type non-words in this field, for 135 * example to choose a name for a character in a game. 136 * Contrast this with {@link #TYPE_TEXT_FLAG_AUTO_COMPLETE} and 137 * {@link #TYPE_TEXT_FLAG_NO_SUGGESTIONS}: 138 * {@code TYPE_TEXT_FLAG_AUTO_CORRECT} means that the IME will try to 139 * auto-correct typos as the user is typing, but does not define whether 140 * the IME offers an interface to show suggestions. 141 */ 142 public static final int TYPE_TEXT_FLAG_AUTO_CORRECT = 0x00008000; 143 144 /** 145 * Flag for {@link #TYPE_CLASS_TEXT}: the text editor (which means 146 * the application) is performing auto-completion of the text being entered 147 * based on its own semantics, which it will present to the user as they type. 148 * This generally means that the input method should not be showing 149 * candidates itself, but can expect the editor to supply its own 150 * completions/candidates from 151 * {@link android.view.inputmethod.InputMethodSession#displayCompletions 152 * InputMethodSession.displayCompletions()} as a result of the editor calling 153 * {@link android.view.inputmethod.InputMethodManager#displayCompletions 154 * InputMethodManager.displayCompletions()}. 155 * Note the contrast with {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} and 156 * {@link #TYPE_TEXT_FLAG_NO_SUGGESTIONS}: 157 * {@code TYPE_TEXT_FLAG_AUTO_COMPLETE} means the editor should show an 158 * interface for displaying suggestions, but instead of supplying its own 159 * it will rely on the Editor to pass completions/corrections. 160 */ 161 public static final int TYPE_TEXT_FLAG_AUTO_COMPLETE = 0x00010000; 162 163 /** 164 * Flag for {@link #TYPE_CLASS_TEXT}: multiple lines of text can be 165 * entered into the field. If this flag is not set, the text field 166 * will be constrained to a single line. The IME may also choose not to 167 * display an enter key when this flag is not set, as there should be no 168 * need to create new lines. 169 */ 170 public static final int TYPE_TEXT_FLAG_MULTI_LINE = 0x00020000; 171 172 /** 173 * Flag for {@link #TYPE_CLASS_TEXT}: the regular text view associated 174 * with this should not be multi-line, but when a fullscreen input method 175 * is providing text it should use multiple lines if it can. 176 */ 177 public static final int TYPE_TEXT_FLAG_IME_MULTI_LINE = 0x00040000; 178 179 /** 180 * Flag for {@link #TYPE_CLASS_TEXT}: the input method does not need to 181 * display any dictionary-based candidates. This is useful for text views that 182 * do not contain words from the language and do not benefit from any 183 * dictionary-based completions or corrections. It overrides the 184 * {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} value when set. 185 * Please avoid using this unless you are certain this is what you want. 186 * Many input methods need suggestions to work well, for example the ones 187 * based on gesture typing. Consider clearing 188 * {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} instead if you just do not 189 * want the IME to correct typos. 190 * Note the contrast with {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} and 191 * {@link #TYPE_TEXT_FLAG_AUTO_COMPLETE}: 192 * {@code TYPE_TEXT_FLAG_NO_SUGGESTIONS} means the IME does not need to 193 * show an interface to display suggestions. Most IMEs will also take this to 194 * mean they do not need to try to auto-correct what the user is typing. 195 */ 196 public static final int TYPE_TEXT_FLAG_NO_SUGGESTIONS = 0x00080000; 197 198 /** 199 * Flag for {@link #TYPE_CLASS_TEXT}: Let the IME know the text conversion suggestions are 200 * required by the application. Text conversion suggestion is for the transliteration languages 201 * which has pronunciation characters and target characters. When the user is typing the 202 * pronunciation charactes, the IME could provide the possible target characters to the user. 203 * When this flag is set, the IME should insert the text conversion suggestions through 204 * {@link Builder#setTextConversionSuggestions(List)} and 205 * the {@link TextAttribute} with initialized with the text conversion suggestions is provided 206 * by the IME to the application. To receive the additional information, the application needs 207 * to implement {@link InputConnection#setComposingText(CharSequence, int, TextAttribute)}, 208 * {@link InputConnection#setComposingRegion(int, int, TextAttribute)}, and 209 * {@link InputConnection#commitText(CharSequence, int, TextAttribute)}. 210 */ 211 public static final int TYPE_TEXT_FLAG_ENABLE_TEXT_CONVERSION_SUGGESTIONS = 0x00100000; 212 213 // ---------------------------------------------------------------------- 214 215 /** 216 * Default variation of {@link #TYPE_CLASS_TEXT}: plain old normal text. 217 */ 218 public static final int TYPE_TEXT_VARIATION_NORMAL = 0x00000000; 219 220 /** 221 * Variation of {@link #TYPE_CLASS_TEXT}: entering a URI. 222 */ 223 public static final int TYPE_TEXT_VARIATION_URI = 0x00000010; 224 225 /** 226 * Variation of {@link #TYPE_CLASS_TEXT}: entering an e-mail address. 227 */ 228 public static final int TYPE_TEXT_VARIATION_EMAIL_ADDRESS = 0x00000020; 229 230 /** 231 * Variation of {@link #TYPE_CLASS_TEXT}: entering the subject line of 232 * an e-mail. 233 */ 234 public static final int TYPE_TEXT_VARIATION_EMAIL_SUBJECT = 0x00000030; 235 236 /** 237 * Variation of {@link #TYPE_CLASS_TEXT}: entering a short, possibly informal 238 * message such as an instant message or a text message. 239 */ 240 public static final int TYPE_TEXT_VARIATION_SHORT_MESSAGE = 0x00000040; 241 242 /** 243 * Variation of {@link #TYPE_CLASS_TEXT}: entering the content of a long, possibly 244 * formal message such as the body of an e-mail. 245 */ 246 public static final int TYPE_TEXT_VARIATION_LONG_MESSAGE = 0x00000050; 247 248 /** 249 * Variation of {@link #TYPE_CLASS_TEXT}: entering the name of a person. 250 */ 251 public static final int TYPE_TEXT_VARIATION_PERSON_NAME = 0x00000060; 252 253 /** 254 * Variation of {@link #TYPE_CLASS_TEXT}: entering a postal mailing address. 255 */ 256 public static final int TYPE_TEXT_VARIATION_POSTAL_ADDRESS = 0x00000070; 257 258 /** 259 * Variation of {@link #TYPE_CLASS_TEXT}: entering a password. 260 */ 261 public static final int TYPE_TEXT_VARIATION_PASSWORD = 0x00000080; 262 263 /** 264 * Variation of {@link #TYPE_CLASS_TEXT}: entering a password, which should 265 * be visible to the user. 266 */ 267 public static final int TYPE_TEXT_VARIATION_VISIBLE_PASSWORD = 0x00000090; 268 269 /** 270 * Variation of {@link #TYPE_CLASS_TEXT}: entering text inside of a web form. 271 */ 272 public static final int TYPE_TEXT_VARIATION_WEB_EDIT_TEXT = 0x000000a0; 273 274 /** 275 * Variation of {@link #TYPE_CLASS_TEXT}: entering text to filter contents 276 * of a list etc. 277 */ 278 public static final int TYPE_TEXT_VARIATION_FILTER = 0x000000b0; 279 280 /** 281 * Variation of {@link #TYPE_CLASS_TEXT}: entering text for phonetic 282 * pronunciation, such as a phonetic name field in contacts. This is mostly 283 * useful for languages where one spelling may have several phonetic 284 * readings, like Japanese. 285 */ 286 public static final int TYPE_TEXT_VARIATION_PHONETIC = 0x000000c0; 287 288 /** 289 * Variation of {@link #TYPE_CLASS_TEXT}: entering e-mail address inside 290 * of a web form. This was added in 291 * {@link android.os.Build.VERSION_CODES#HONEYCOMB}. An IME must target 292 * this API version or later to see this input type; if it doesn't, a request 293 * for this type will be seen as {@link #TYPE_TEXT_VARIATION_EMAIL_ADDRESS} 294 * when passed through {@link android.view.inputmethod.EditorInfo#makeCompatible(int) 295 * EditorInfo.makeCompatible(int)}. 296 */ 297 public static final int TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS = 0x000000d0; 298 299 /** 300 * Variation of {@link #TYPE_CLASS_TEXT}: entering password inside 301 * of a web form. This was added in 302 * {@link android.os.Build.VERSION_CODES#HONEYCOMB}. An IME must target 303 * this API version or later to see this input type; if it doesn't, a request 304 * for this type will be seen as {@link #TYPE_TEXT_VARIATION_PASSWORD} 305 * when passed through {@link android.view.inputmethod.EditorInfo#makeCompatible(int) 306 * EditorInfo.makeCompatible(int)}. 307 */ 308 public static final int TYPE_TEXT_VARIATION_WEB_PASSWORD = 0x000000e0; 309 310 // ---------------------------------------------------------------------- 311 // ---------------------------------------------------------------------- 312 // ---------------------------------------------------------------------- 313 314 /** 315 * Class for numeric text. This class supports the following flags: 316 * {@link #TYPE_NUMBER_FLAG_SIGNED} and 317 * {@link #TYPE_NUMBER_FLAG_DECIMAL}. It also supports the following 318 * variations: {@link #TYPE_NUMBER_VARIATION_NORMAL} and 319 * {@link #TYPE_NUMBER_VARIATION_PASSWORD}. 320 * <p>IME authors: If you do not recognize 321 * the variation, normal should be assumed.</p> 322 */ 323 public static final int TYPE_CLASS_NUMBER = 0x00000002; 324 325 /** 326 * Flag of {@link #TYPE_CLASS_NUMBER}: the number is signed, allowing 327 * a positive or negative sign at the start. 328 */ 329 public static final int TYPE_NUMBER_FLAG_SIGNED = 0x00001000; 330 331 /** 332 * Flag of {@link #TYPE_CLASS_NUMBER}: the number is decimal, allowing 333 * a decimal point to provide fractional values. 334 */ 335 public static final int TYPE_NUMBER_FLAG_DECIMAL = 0x00002000; 336 337 // ---------------------------------------------------------------------- 338 339 /** 340 * Default variation of {@link #TYPE_CLASS_NUMBER}: plain normal 341 * numeric text. This was added in 342 * {@link android.os.Build.VERSION_CODES#HONEYCOMB}. An IME must target 343 * this API version or later to see this input type; if it doesn't, a request 344 * for this type will be dropped when passed through 345 * {@link android.view.inputmethod.EditorInfo#makeCompatible(int) 346 * EditorInfo.makeCompatible(int)}. 347 */ 348 public static final int TYPE_NUMBER_VARIATION_NORMAL = 0x00000000; 349 350 /** 351 * Variation of {@link #TYPE_CLASS_NUMBER}: entering a numeric password. 352 * This was added in {@link android.os.Build.VERSION_CODES#HONEYCOMB}. An 353 * IME must target this API version or later to see this input type; if it 354 * doesn't, a request for this type will be dropped when passed 355 * through {@link android.view.inputmethod.EditorInfo#makeCompatible(int) 356 * EditorInfo.makeCompatible(int)}. 357 */ 358 public static final int TYPE_NUMBER_VARIATION_PASSWORD = 0x00000010; 359 360 // ---------------------------------------------------------------------- 361 // ---------------------------------------------------------------------- 362 // ---------------------------------------------------------------------- 363 364 /** 365 * Class for a phone number. This class currently supports no variations 366 * or flags. 367 */ 368 public static final int TYPE_CLASS_PHONE = 0x00000003; 369 370 // ---------------------------------------------------------------------- 371 // ---------------------------------------------------------------------- 372 // ---------------------------------------------------------------------- 373 374 /** 375 * Class for dates and times. It supports the 376 * following variations: 377 * {@link #TYPE_DATETIME_VARIATION_NORMAL} 378 * {@link #TYPE_DATETIME_VARIATION_DATE}, and 379 * {@link #TYPE_DATETIME_VARIATION_TIME}. 380 */ 381 public static final int TYPE_CLASS_DATETIME = 0x00000004; 382 383 /** 384 * Default variation of {@link #TYPE_CLASS_DATETIME}: allows entering 385 * both a date and time. 386 */ 387 public static final int TYPE_DATETIME_VARIATION_NORMAL = 0x00000000; 388 389 /** 390 * Default variation of {@link #TYPE_CLASS_DATETIME}: allows entering 391 * only a date. 392 */ 393 public static final int TYPE_DATETIME_VARIATION_DATE = 0x00000010; 394 395 /** 396 * Default variation of {@link #TYPE_CLASS_DATETIME}: allows entering 397 * only a time. 398 */ 399 public static final int TYPE_DATETIME_VARIATION_TIME = 0x00000020; 400 } 401