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