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.view.inputmethod; 18 19 import android.annotation.Nullable; 20 import android.os.Bundle; 21 import android.os.LocaleList; 22 import android.os.Parcel; 23 import android.os.Parcelable; 24 import android.text.InputType; 25 import android.text.TextUtils; 26 import android.util.Printer; 27 28 /** 29 * An EditorInfo describes several attributes of a text editing object 30 * that an input method is communicating with (typically an EditText), most 31 * importantly the type of text content it contains and the current cursor position. 32 */ 33 public class EditorInfo implements InputType, Parcelable { 34 /** 35 * The content type of the text box, whose bits are defined by 36 * {@link InputType}. 37 * 38 * @see InputType 39 * @see #TYPE_MASK_CLASS 40 * @see #TYPE_MASK_VARIATION 41 * @see #TYPE_MASK_FLAGS 42 */ 43 public int inputType = TYPE_NULL; 44 45 /** 46 * Set of bits in {@link #imeOptions} that provide alternative actions 47 * associated with the "enter" key. This both helps the IME provide 48 * better feedback about what the enter key will do, and also allows it 49 * to provide alternative mechanisms for providing that command. 50 */ 51 public static final int IME_MASK_ACTION = 0x000000ff; 52 53 /** 54 * Bits of {@link #IME_MASK_ACTION}: no specific action has been 55 * associated with this editor, let the editor come up with its own if 56 * it can. 57 */ 58 public static final int IME_ACTION_UNSPECIFIED = 0x00000000; 59 60 /** 61 * Bits of {@link #IME_MASK_ACTION}: there is no available action. 62 */ 63 public static final int IME_ACTION_NONE = 0x00000001; 64 65 /** 66 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "go" 67 * operation to take the user to the target of the text they typed. 68 * Typically used, for example, when entering a URL. 69 */ 70 public static final int IME_ACTION_GO = 0x00000002; 71 72 /** 73 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "search" 74 * operation, taking the user to the results of searching for the text 75 * they have typed (in whatever context is appropriate). 76 */ 77 public static final int IME_ACTION_SEARCH = 0x00000003; 78 79 /** 80 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "send" 81 * operation, delivering the text to its target. This is typically used 82 * when composing a message in IM or SMS where sending is immediate. 83 */ 84 public static final int IME_ACTION_SEND = 0x00000004; 85 86 /** 87 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "next" 88 * operation, taking the user to the next field that will accept text. 89 */ 90 public static final int IME_ACTION_NEXT = 0x00000005; 91 92 /** 93 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "done" 94 * operation, typically meaning there is nothing more to input and the 95 * IME will be closed. 96 */ 97 public static final int IME_ACTION_DONE = 0x00000006; 98 99 /** 100 * Bits of {@link #IME_MASK_ACTION}: like {@link #IME_ACTION_NEXT}, but 101 * for moving to the previous field. This will normally not be used to 102 * specify an action (since it precludes {@link #IME_ACTION_NEXT}), but 103 * can be returned to the app if it sets {@link #IME_FLAG_NAVIGATE_PREVIOUS}. 104 */ 105 public static final int IME_ACTION_PREVIOUS = 0x00000007; 106 107 /** 108 * Flag of {@link #imeOptions}: used to request that the IME never go 109 * into fullscreen mode. 110 * By default, IMEs may go into full screen mode when they think 111 * it's appropriate, for example on small screens in landscape 112 * orientation where displaying a software keyboard may occlude 113 * such a large portion of the screen that the remaining part is 114 * too small to meaningfully display the application UI. 115 * If this flag is set, compliant IMEs will never go into full screen mode, 116 * and always leave some space to display the application UI. 117 * Applications need to be aware that the flag is not a guarantee, and 118 * some IMEs may ignore it. 119 */ 120 public static final int IME_FLAG_NO_FULLSCREEN = 0x2000000; 121 122 /** 123 * Flag of {@link #imeOptions}: like {@link #IME_FLAG_NAVIGATE_NEXT}, but 124 * specifies there is something interesting that a backward navigation 125 * can focus on. If the user selects the IME's facility to backward 126 * navigate, this will show up in the application as an {@link #IME_ACTION_PREVIOUS} 127 * at {@link InputConnection#performEditorAction(int) 128 * InputConnection.performEditorAction(int)}. 129 */ 130 public static final int IME_FLAG_NAVIGATE_PREVIOUS = 0x4000000; 131 132 /** 133 * Flag of {@link #imeOptions}: used to specify that there is something 134 * interesting that a forward navigation can focus on. This is like using 135 * {@link #IME_ACTION_NEXT}, except allows the IME to be multiline (with 136 * an enter key) as well as provide forward navigation. Note that some 137 * IMEs may not be able to do this, especially when running on a small 138 * screen where there is little space. In that case it does not need to 139 * present a UI for this option. Like {@link #IME_ACTION_NEXT}, if the 140 * user selects the IME's facility to forward navigate, this will show up 141 * in the application at {@link InputConnection#performEditorAction(int) 142 * InputConnection.performEditorAction(int)}. 143 */ 144 public static final int IME_FLAG_NAVIGATE_NEXT = 0x8000000; 145 146 /** 147 * Flag of {@link #imeOptions}: used to specify that the IME does not need 148 * to show its extracted text UI. For input methods that may be fullscreen, 149 * often when in landscape mode, this allows them to be smaller and let part 150 * of the application be shown behind, through transparent UI parts in the 151 * fullscreen IME. The part of the UI visible to the user may not be responsive 152 * to touch because the IME will receive touch events, which may confuse the 153 * user; use {@link #IME_FLAG_NO_FULLSCREEN} instead for a better experience. 154 * Using this flag is discouraged and it may become deprecated in the future. 155 * Its meaning is unclear in some situations and it may not work appropriately 156 * on older versions of the platform. 157 */ 158 public static final int IME_FLAG_NO_EXTRACT_UI = 0x10000000; 159 160 /** 161 * Flag of {@link #imeOptions}: used in conjunction with one of the actions 162 * masked by {@link #IME_MASK_ACTION}, this indicates that the action 163 * should not be available as an accessory button on the right of the extracted 164 * text when the input method is full-screen. Note that by setting this flag, 165 * there can be cases where the action is simply never available to the 166 * user. Setting this generally means that you think that in fullscreen mode, 167 * where there is little space to show the text, it's not worth taking some 168 * screen real estate to display the action and it should be used instead 169 * to show more text. 170 */ 171 public static final int IME_FLAG_NO_ACCESSORY_ACTION = 0x20000000; 172 173 /** 174 * Flag of {@link #imeOptions}: used in conjunction with one of the actions 175 * masked by {@link #IME_MASK_ACTION}. If this flag is not set, IMEs will 176 * normally replace the "enter" key with the action supplied. This flag 177 * indicates that the action should not be available in-line as a replacement 178 * for the "enter" key. Typically this is because the action has such a 179 * significant impact or is not recoverable enough that accidentally hitting 180 * it should be avoided, such as sending a message. Note that 181 * {@link android.widget.TextView} will automatically set this flag for you 182 * on multi-line text views. 183 */ 184 public static final int IME_FLAG_NO_ENTER_ACTION = 0x40000000; 185 186 /** 187 * Flag of {@link #imeOptions}: used to request an IME that is capable of 188 * inputting ASCII characters. The intention of this flag is to ensure that 189 * the user can type Roman alphabet characters in a {@link android.widget.TextView}. 190 * It is typically used for an account ID or password input. A lot of the time, 191 * IMEs are already able to input ASCII even without being told so (such IMEs 192 * already respect this flag in a sense), but there are cases when this is not 193 * the default. For instance, users of languages using a different script like 194 * Arabic, Greek, Hebrew or Russian typically have a keyboard that can't 195 * input ASCII characters by default. Applications need to be 196 * aware that the flag is not a guarantee, and some IMEs may not respect it. 197 * However, it is strongly recommended for IME authors to respect this flag 198 * especially when their IME could end up with a state where only languages 199 * using non-ASCII are enabled. 200 */ 201 public static final int IME_FLAG_FORCE_ASCII = 0x80000000; 202 203 /** 204 * Generic unspecified type for {@link #imeOptions}. 205 */ 206 public static final int IME_NULL = 0x00000000; 207 208 /** 209 * Extended type information for the editor, to help the IME better 210 * integrate with it. 211 */ 212 public int imeOptions = IME_NULL; 213 214 /** 215 * A string supplying additional information options that are 216 * private to a particular IME implementation. The string must be 217 * scoped to a package owned by the implementation, to ensure there are 218 * no conflicts between implementations, but other than that you can put 219 * whatever you want in it to communicate with the IME. For example, 220 * you could have a string that supplies an argument like 221 * <code>"com.example.myapp.SpecialMode=3"</code>. This field is can be 222 * filled in from the {@link android.R.attr#privateImeOptions} 223 * attribute of a TextView. 224 */ 225 public String privateImeOptions = null; 226 227 /** 228 * In some cases an IME may be able to display an arbitrary label for 229 * a command the user can perform, which you can specify here. This is 230 * typically used as the label for the action to use in-line as a replacement 231 * for the "enter" key (see {@link #actionId}). Remember the key where 232 * this will be displayed is typically very small, and there are significant 233 * localization challenges to make this fit in all supported languages. Also 234 * you can not count absolutely on this being used, as some IMEs may 235 * ignore this. 236 */ 237 public CharSequence actionLabel = null; 238 239 /** 240 * If {@link #actionLabel} has been given, this is the id for that command 241 * when the user presses its button that is delivered back with 242 * {@link InputConnection#performEditorAction(int) 243 * InputConnection.performEditorAction()}. 244 */ 245 public int actionId = 0; 246 247 /** 248 * The text offset of the start of the selection at the time editing 249 * begins; -1 if not known. Keep in mind that, without knowing the cursor 250 * position, many IMEs will not be able to offer their full feature set and 251 * may even behave in unpredictable ways: pass the actual cursor position 252 * here if possible at all. 253 * 254 * <p>Also, this needs to be the cursor position <strong>right now</strong>, 255 * not at some point in the past, even if input is starting in the same text field 256 * as before. When the app is filling this object, input is about to start by 257 * definition, and this value will override any value the app may have passed to 258 * {@link InputMethodManager#updateSelection(android.view.View, int, int, int, int)} 259 * before.</p> 260 */ 261 public int initialSelStart = -1; 262 263 /** 264 * <p>The text offset of the end of the selection at the time editing 265 * begins; -1 if not known. Keep in mind that, without knowing the cursor 266 * position, many IMEs will not be able to offer their full feature set and 267 * may behave in unpredictable ways: pass the actual cursor position 268 * here if possible at all.</p> 269 * 270 * <p>Also, this needs to be the cursor position <strong>right now</strong>, 271 * not at some point in the past, even if input is starting in the same text field 272 * as before. When the app is filling this object, input is about to start by 273 * definition, and this value will override any value the app may have passed to 274 * {@link InputMethodManager#updateSelection(android.view.View, int, int, int, int)} 275 * before.</p> 276 */ 277 public int initialSelEnd = -1; 278 279 /** 280 * The capitalization mode of the first character being edited in the 281 * text. Values may be any combination of 282 * {@link TextUtils#CAP_MODE_CHARACTERS TextUtils.CAP_MODE_CHARACTERS}, 283 * {@link TextUtils#CAP_MODE_WORDS TextUtils.CAP_MODE_WORDS}, and 284 * {@link TextUtils#CAP_MODE_SENTENCES TextUtils.CAP_MODE_SENTENCES}, though 285 * you should generally just take a non-zero value to mean "start out in 286 * caps mode". 287 */ 288 public int initialCapsMode = 0; 289 290 /** 291 * The "hint" text of the text view, typically shown in-line when the 292 * text is empty to tell the user what to enter. 293 */ 294 public CharSequence hintText; 295 296 /** 297 * A label to show to the user describing the text they are writing. 298 */ 299 public CharSequence label; 300 301 /** 302 * Name of the package that owns this editor. 303 * 304 * <p><strong>IME authors:</strong> In API level 22 305 * {@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1} and prior, do not trust this package 306 * name. The system had not verified the consistency between the package name here and 307 * application's uid. Consider to use {@link InputBinding#getUid()}, which is trustworthy. 308 * Starting from {@link android.os.Build.VERSION_CODES#M}, the system verifies the consistency 309 * between this package name and application uid before {@link EditorInfo} is passed to the 310 * input method.</p> 311 * 312 * <p><strong>Editor authors:</strong> Starting from {@link android.os.Build.VERSION_CODES#M}, 313 * the application is no longer 314 * able to establish input connections if the package name provided here is inconsistent with 315 * application's uid.</p> 316 */ 317 public String packageName; 318 319 /** 320 * Identifier for the editor's field. This is optional, and may be 321 * 0. By default it is filled in with the result of 322 * {@link android.view.View#getId() View.getId()} on the View that 323 * is being edited. 324 */ 325 public int fieldId; 326 327 /** 328 * Additional name for the editor's field. This can supply additional 329 * name information for the field. By default it is null. The actual 330 * contents have no meaning. 331 */ 332 public String fieldName; 333 334 /** 335 * Any extra data to supply to the input method. This is for extended 336 * communication with specific input methods; the name fields in the 337 * bundle should be scoped (such as "com.mydomain.im.SOME_FIELD") so 338 * that they don't conflict with others. This field can be 339 * filled in from the {@link android.R.attr#editorExtras} 340 * attribute of a TextView. 341 */ 342 public Bundle extras; 343 344 /** 345 * List of the languages that the user is supposed to switch to no matter what input method 346 * subtype is currently used. This special "hint" can be used mainly for, but not limited to, 347 * multilingual users who want IMEs to switch language context automatically. 348 * 349 * <p>{@code null} means that no special language "hint" is needed.</p> 350 * 351 * <p><strong>Editor authors:</strong> Specify this only when you are confident that the user 352 * will switch to certain languages in this context no matter what input method subtype is 353 * currently selected. Otherwise, keep this {@code null}. Explicit user actions and/or 354 * preferences would be good signals to specify this special "hint", For example, a chat 355 * application may be able to put the last used language at the top of {@link #hintLocales} 356 * based on whom the user is going to talk, by remembering what language is used in the last 357 * conversation. Do not specify {@link android.widget.TextView#getTextLocales()} only because 358 * it is used for text rendering.</p> 359 * 360 * @see android.widget.TextView#setImeHintLocales(LocaleList) 361 * @see android.widget.TextView#getImeHintLocales() 362 */ 363 @Nullable 364 public LocaleList hintLocales = null; 365 366 /** 367 * Ensure that the data in this EditorInfo is compatible with an application 368 * that was developed against the given target API version. This can 369 * impact the following input types: 370 * {@link InputType#TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS}, 371 * {@link InputType#TYPE_TEXT_VARIATION_WEB_PASSWORD}, 372 * {@link InputType#TYPE_NUMBER_VARIATION_NORMAL}, 373 * {@link InputType#TYPE_NUMBER_VARIATION_PASSWORD}. 374 * 375 * <p>This is called by the framework for input method implementations; 376 * you should not generally need to call it yourself. 377 * 378 * @param targetSdkVersion The API version number that the compatible 379 * application was developed against. 380 */ makeCompatible(int targetSdkVersion)381 public final void makeCompatible(int targetSdkVersion) { 382 if (targetSdkVersion < android.os.Build.VERSION_CODES.HONEYCOMB) { 383 switch (inputType&(TYPE_MASK_CLASS|TYPE_MASK_VARIATION)) { 384 case TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS: 385 inputType = TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_EMAIL_ADDRESS 386 | (inputType&TYPE_MASK_FLAGS); 387 break; 388 case TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_WEB_PASSWORD: 389 inputType = TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_PASSWORD 390 | (inputType&TYPE_MASK_FLAGS); 391 break; 392 case TYPE_CLASS_NUMBER|TYPE_NUMBER_VARIATION_NORMAL: 393 case TYPE_CLASS_NUMBER|TYPE_NUMBER_VARIATION_PASSWORD: 394 inputType = TYPE_CLASS_NUMBER 395 | (inputType&TYPE_MASK_FLAGS); 396 break; 397 } 398 } 399 } 400 401 /** 402 * Write debug output of this object. 403 */ dump(Printer pw, String prefix)404 public void dump(Printer pw, String prefix) { 405 pw.println(prefix + "inputType=0x" + Integer.toHexString(inputType) 406 + " imeOptions=0x" + Integer.toHexString(imeOptions) 407 + " privateImeOptions=" + privateImeOptions); 408 pw.println(prefix + "actionLabel=" + actionLabel 409 + " actionId=" + actionId); 410 pw.println(prefix + "initialSelStart=" + initialSelStart 411 + " initialSelEnd=" + initialSelEnd 412 + " initialCapsMode=0x" 413 + Integer.toHexString(initialCapsMode)); 414 pw.println(prefix + "hintText=" + hintText 415 + " label=" + label); 416 pw.println(prefix + "packageName=" + packageName 417 + " fieldId=" + fieldId 418 + " fieldName=" + fieldName); 419 pw.println(prefix + "extras=" + extras); 420 pw.println(prefix + "hintLocales=" + hintLocales); 421 } 422 423 /** 424 * Used to package this object into a {@link Parcel}. 425 * 426 * @param dest The {@link Parcel} to be written. 427 * @param flags The flags used for parceling. 428 */ writeToParcel(Parcel dest, int flags)429 public void writeToParcel(Parcel dest, int flags) { 430 dest.writeInt(inputType); 431 dest.writeInt(imeOptions); 432 dest.writeString(privateImeOptions); 433 TextUtils.writeToParcel(actionLabel, dest, flags); 434 dest.writeInt(actionId); 435 dest.writeInt(initialSelStart); 436 dest.writeInt(initialSelEnd); 437 dest.writeInt(initialCapsMode); 438 TextUtils.writeToParcel(hintText, dest, flags); 439 TextUtils.writeToParcel(label, dest, flags); 440 dest.writeString(packageName); 441 dest.writeInt(fieldId); 442 dest.writeString(fieldName); 443 dest.writeBundle(extras); 444 if (hintLocales != null) { 445 hintLocales.writeToParcel(dest, flags); 446 } else { 447 LocaleList.getEmptyLocaleList().writeToParcel(dest, flags); 448 } 449 } 450 451 /** 452 * Used to make this class parcelable. 453 */ 454 public static final Parcelable.Creator<EditorInfo> CREATOR = 455 new Parcelable.Creator<EditorInfo>() { 456 public EditorInfo createFromParcel(Parcel source) { 457 EditorInfo res = new EditorInfo(); 458 res.inputType = source.readInt(); 459 res.imeOptions = source.readInt(); 460 res.privateImeOptions = source.readString(); 461 res.actionLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source); 462 res.actionId = source.readInt(); 463 res.initialSelStart = source.readInt(); 464 res.initialSelEnd = source.readInt(); 465 res.initialCapsMode = source.readInt(); 466 res.hintText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source); 467 res.label = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source); 468 res.packageName = source.readString(); 469 res.fieldId = source.readInt(); 470 res.fieldName = source.readString(); 471 res.extras = source.readBundle(); 472 LocaleList hintLocales = LocaleList.CREATOR.createFromParcel(source); 473 res.hintLocales = hintLocales.isEmpty() ? null : hintLocales; 474 return res; 475 } 476 477 public EditorInfo[] newArray(int size) { 478 return new EditorInfo[size]; 479 } 480 }; 481 describeContents()482 public int describeContents() { 483 return 0; 484 } 485 486 } 487