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