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. 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 * the 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. 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 the IME will be closed. 93 */ 94 public static final int IME_ACTION_DONE = 0x00000006; 95 96 /** 97 * Bits of {@link #IME_MASK_ACTION}: Like {@link #IME_ACTION_NEXT}, but 98 * for moving to the previous field. This will normally not be used to 99 * specify an action (since it precludes {@link #IME_ACTION_NEXT}, but 100 * can be returned to the app if it sets {@link #IME_FLAG_NAVIGATE_PREVIOUS}. 101 */ 102 public static final int IME_ACTION_PREVIOUS = 0x00000007; 103 104 /** 105 * Flag of {@link #imeOptions}: used to request that the IME never go 106 * into fullscreen mode. Applications need to be aware that the flag is not 107 * a guarantee, and not all IMEs will respect it. 108 */ 109 public static final int IME_FLAG_NO_FULLSCREEN = 0x2000000; 110 111 /** 112 * Flag of {@link #imeOptions}: like {@link #IME_FLAG_NAVIGATE_NEXT}, but 113 * specifies there is something interesting that a backward navigation 114 * can focus on. If the user selects the IME's facility to backward 115 * navigate, this will show up in the application as an {@link #IME_ACTION_PREVIOUS} 116 * at {@link InputConnection#performEditorAction(int) 117 * InputConnection.performEditorAction(int)}. 118 */ 119 public static final int IME_FLAG_NAVIGATE_PREVIOUS = 0x4000000; 120 121 /** 122 * Flag of {@link #imeOptions}: used to specify that there is something 123 * interesting that a forward navigation can focus on. This is like using 124 * {@link #IME_ACTION_NEXT}, except allows the IME to be multiline (with 125 * an enter key) as well as provide forward navigation. Note that some 126 * IMEs may not be able to do this, especially when running on a small 127 * screen where there is little space. In that case it does not need to 128 * present a UI for this option. Like {@link #IME_ACTION_NEXT}, if the 129 * user selects the IME's facility to forward navigate, this will show up 130 * in the application at {@link InputConnection#performEditorAction(int) 131 * InputConnection.performEditorAction(int)}. 132 */ 133 public static final int IME_FLAG_NAVIGATE_NEXT = 0x8000000; 134 135 /** 136 * Flag of {@link #imeOptions}: used to specify that the IME does not need 137 * to show its extracted text UI. For input methods that may be fullscreen, 138 * often when in landscape mode, this allows them to be smaller and let part 139 * of the application be shown behind. Though there will likely be limited 140 * access to the application available from the user, it can make the 141 * experience of a (mostly) fullscreen IME less jarring. Note that when 142 * this flag is specified the IME may <em>not</em> be set up to be able 143 * to display text, so it should only be used in situations where this is 144 * not needed. 145 */ 146 public static final int IME_FLAG_NO_EXTRACT_UI = 0x10000000; 147 148 /** 149 * Flag of {@link #imeOptions}: used in conjunction with 150 * {@link #IME_MASK_ACTION}, this indicates that the action should not 151 * be available as an accessory button when the input method is full-screen. 152 * Note that by setting this flag, there can be cases where the action 153 * is simply never available to the user. Setting this generally means 154 * that you think showing text being edited is more important than the 155 * action you have supplied. 156 */ 157 public static final int IME_FLAG_NO_ACCESSORY_ACTION = 0x20000000; 158 159 /** 160 * Flag of {@link #imeOptions}: used in conjunction with 161 * {@link #IME_MASK_ACTION}, this indicates that the action should not 162 * be available in-line as a replacement for "enter" key. Typically this is 163 * because the action has such a significant impact or is not recoverable 164 * enough that accidentally hitting it should be avoided, such as sending 165 * a message. Note that {@link android.widget.TextView} will automatically set this 166 * flag for you on multi-line text views. 167 */ 168 public static final int IME_FLAG_NO_ENTER_ACTION = 0x40000000; 169 170 /** 171 * Flag of {@link #imeOptions}: used to request that the IME is capable of 172 * inputting ASCII characters. The intention of this flag is to ensure that 173 * the user can type Roman alphabet characters in a {@link android.widget.TextView} 174 * used for, typically, account ID or password input. It is expected that IMEs 175 * normally are able to input ASCII even without being told so (such IMEs 176 * already respect this flag in a sense), but there could be some cases they 177 * aren't when, for instance, only non-ASCII input languagaes like Arabic, 178 * Greek, Hebrew, Russian are enabled in the IME. Applications need to be 179 * aware that the flag is not a guarantee, and not all IMEs will respect it. 180 * However, it is strongly recommended for IME authors to respect this flag 181 * especially when their IME could end up with a state that has only non-ASCII 182 * input languages enabled. 183 */ 184 public static final int IME_FLAG_FORCE_ASCII = 0x80000000; 185 186 /** 187 * Generic unspecified type for {@link #imeOptions}. 188 */ 189 public static final int IME_NULL = 0x00000000; 190 191 /** 192 * Extended type information for the editor, to help the IME better 193 * integrate with it. 194 */ 195 public int imeOptions = IME_NULL; 196 197 /** 198 * A string supplying additional information options that are 199 * private to a particular IME implementation. The string must be 200 * scoped to a package owned by the implementation, to ensure there are 201 * no conflicts between implementations, but other than that you can put 202 * whatever you want in it to communicate with the IME. For example, 203 * you could have a string that supplies an argument like 204 * <code>"com.example.myapp.SpecialMode=3"</code>. This field is can be 205 * filled in from the {@link android.R.attr#privateImeOptions} 206 * attribute of a TextView. 207 */ 208 public String privateImeOptions = null; 209 210 /** 211 * In some cases an IME may be able to display an arbitrary label for 212 * a command the user can perform, which you can specify here. You can 213 * not count on this being used. 214 */ 215 public CharSequence actionLabel = null; 216 217 /** 218 * If {@link #actionLabel} has been given, this is the id for that command 219 * when the user presses its button that is delivered back with 220 * {@link InputConnection#performEditorAction(int) 221 * InputConnection.performEditorAction()}. 222 */ 223 public int actionId = 0; 224 225 /** 226 * The text offset of the start of the selection at the time editing 227 * began; -1 if not known. 228 */ 229 public int initialSelStart = -1; 230 231 /** 232 * The text offset of the end of the selection at the time editing 233 * began; -1 if not known. 234 */ 235 public int initialSelEnd = -1; 236 237 /** 238 * The capitalization mode of the first character being edited in the 239 * text. Values may be any combination of 240 * {@link TextUtils#CAP_MODE_CHARACTERS TextUtils.CAP_MODE_CHARACTERS}, 241 * {@link TextUtils#CAP_MODE_WORDS TextUtils.CAP_MODE_WORDS}, and 242 * {@link TextUtils#CAP_MODE_SENTENCES TextUtils.CAP_MODE_SENTENCES}, though 243 * you should generally just take a non-zero value to mean start out in 244 * caps mode. 245 */ 246 public int initialCapsMode = 0; 247 248 /** 249 * The "hint" text of the text view, typically shown in-line when the 250 * text is empty to tell the user what to enter. 251 */ 252 public CharSequence hintText; 253 254 /** 255 * A label to show to the user describing the text they are writing. 256 */ 257 public CharSequence label; 258 259 /** 260 * Name of the package that owns this editor. 261 */ 262 public String packageName; 263 264 /** 265 * Identifier for the editor's field. This is optional, and may be 266 * 0. By default it is filled in with the result of 267 * {@link android.view.View#getId() View.getId()} on the View that 268 * is being edited. 269 */ 270 public int fieldId; 271 272 /** 273 * Additional name for the editor's field. This can supply additional 274 * name information for the field. By default it is null. The actual 275 * contents have no meaning. 276 */ 277 public String fieldName; 278 279 /** 280 * Any extra data to supply to the input method. This is for extended 281 * communication with specific input methods; the name fields in the 282 * bundle should be scoped (such as "com.mydomain.im.SOME_FIELD") so 283 * that they don't conflict with others. This field is can be 284 * filled in from the {@link android.R.attr#editorExtras} 285 * attribute of a TextView. 286 */ 287 public Bundle extras; 288 289 /** 290 * Ensure that the data in this EditorInfo is compatible with an application 291 * that was developed against the given target API version. This can 292 * impact the following input types: 293 * {@link InputType#TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS}, 294 * {@link InputType#TYPE_TEXT_VARIATION_WEB_PASSWORD}, 295 * {@link InputType#TYPE_NUMBER_VARIATION_NORMAL}, 296 * {@link InputType#TYPE_NUMBER_VARIATION_PASSWORD}. 297 * 298 * <p>This is called by the framework for input method implementations; 299 * you should not generally need to call it yourself. 300 * 301 * @param targetSdkVersion The API version number that the compatible 302 * application was developed against. 303 */ 304 public final void makeCompatible(int targetSdkVersion) { 305 if (targetSdkVersion < android.os.Build.VERSION_CODES.HONEYCOMB) { 306 switch (inputType&(TYPE_MASK_CLASS|TYPE_MASK_VARIATION)) { 307 case TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS: 308 inputType = TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_EMAIL_ADDRESS 309 | (inputType&TYPE_MASK_FLAGS); 310 break; 311 case TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_WEB_PASSWORD: 312 inputType = TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_PASSWORD 313 | (inputType&TYPE_MASK_FLAGS); 314 break; 315 case TYPE_CLASS_NUMBER|TYPE_NUMBER_VARIATION_NORMAL: 316 case TYPE_CLASS_NUMBER|TYPE_NUMBER_VARIATION_PASSWORD: 317 inputType = TYPE_CLASS_NUMBER 318 | (inputType&TYPE_MASK_FLAGS); 319 break; 320 } 321 } 322 } 323 324 /** 325 * Write debug output of this object. 326 */ 327 public void dump(Printer pw, String prefix) { 328 pw.println(prefix + "inputType=0x" + Integer.toHexString(inputType) 329 + " imeOptions=0x" + Integer.toHexString(imeOptions) 330 + " privateImeOptions=" + privateImeOptions); 331 pw.println(prefix + "actionLabel=" + actionLabel 332 + " actionId=" + actionId); 333 pw.println(prefix + "initialSelStart=" + initialSelStart 334 + " initialSelEnd=" + initialSelEnd 335 + " initialCapsMode=0x" 336 + Integer.toHexString(initialCapsMode)); 337 pw.println(prefix + "hintText=" + hintText 338 + " label=" + label); 339 pw.println(prefix + "packageName=" + packageName 340 + " fieldId=" + fieldId 341 + " fieldName=" + fieldName); 342 pw.println(prefix + "extras=" + extras); 343 } 344 345 /** 346 * Used to package this object into a {@link Parcel}. 347 * 348 * @param dest The {@link Parcel} to be written. 349 * @param flags The flags used for parceling. 350 */ 351 public void writeToParcel(Parcel dest, int flags) { 352 dest.writeInt(inputType); 353 dest.writeInt(imeOptions); 354 dest.writeString(privateImeOptions); 355 TextUtils.writeToParcel(actionLabel, dest, flags); 356 dest.writeInt(actionId); 357 dest.writeInt(initialSelStart); 358 dest.writeInt(initialSelEnd); 359 dest.writeInt(initialCapsMode); 360 TextUtils.writeToParcel(hintText, dest, flags); 361 TextUtils.writeToParcel(label, dest, flags); 362 dest.writeString(packageName); 363 dest.writeInt(fieldId); 364 dest.writeString(fieldName); 365 dest.writeBundle(extras); 366 } 367 368 /** 369 * Used to make this class parcelable. 370 */ 371 public static final Parcelable.Creator<EditorInfo> CREATOR = new Parcelable.Creator<EditorInfo>() { 372 public EditorInfo createFromParcel(Parcel source) { 373 EditorInfo res = new EditorInfo(); 374 res.inputType = source.readInt(); 375 res.imeOptions = source.readInt(); 376 res.privateImeOptions = source.readString(); 377 res.actionLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source); 378 res.actionId = source.readInt(); 379 res.initialSelStart = source.readInt(); 380 res.initialSelEnd = source.readInt(); 381 res.initialCapsMode = source.readInt(); 382 res.hintText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source); 383 res.label = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source); 384 res.packageName = source.readString(); 385 res.fieldId = source.readInt(); 386 res.fieldName = source.readString(); 387 res.extras = source.readBundle(); 388 return res; 389 } 390 391 public EditorInfo[] newArray(int size) { 392 return new EditorInfo[size]; 393 } 394 }; 395 396 public int describeContents() { 397 return 0; 398 } 399 400 } 401
