2 * Copyright (C) 2008 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 package android.view.inputmethod;
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;
28 import java.util.Arrays;
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.
35 public class EditorInfo implements InputType, Parcelable {
37 * Masks for {@link inputType}
40 * |-------|-------|-------|-------|
41 * 1111 TYPE_MASK_CLASS
42 * 11111111 TYPE_MASK_VARIATION
43 * 111111111111 TYPE_MASK_FLAGS
44 * |-------|-------|-------|-------|
46 * |-------|-------|-------|-------|
48 * 1 TYPE_TEXT_VARIATION_URI
49 * 1 TYPE_TEXT_VARIATION_EMAIL_ADDRESS
50 * 11 TYPE_TEXT_VARIATION_EMAIL_SUBJECT
51 * 1 TYPE_TEXT_VARIATION_SHORT_MESSAGE
52 * 1 1 TYPE_TEXT_VARIATION_LONG_MESSAGE
53 * 11 TYPE_TEXT_VARIATION_PERSON_NAME
54 * 111 TYPE_TEXT_VARIATION_POSTAL_ADDRESS
55 * 1 TYPE_TEXT_VARIATION_PASSWORD
56 * 1 1 TYPE_TEXT_VARIATION_VISIBLE_PASSWORD
57 * 1 1 TYPE_TEXT_VARIATION_WEB_EDIT_TEXT
58 * 1 11 TYPE_TEXT_VARIATION_FILTER
59 * 11 TYPE_TEXT_VARIATION_PHONETIC
60 * 11 1 TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS
61 * 111 TYPE_TEXT_VARIATION_WEB_PASSWORD
62 * 1 TYPE_TEXT_FLAG_CAP_CHARACTERS
63 * 1 TYPE_TEXT_FLAG_CAP_WORDS
64 * 1 TYPE_TEXT_FLAG_CAP_SENTENCES
65 * 1 TYPE_TEXT_FLAG_AUTO_CORRECT
66 * 1 TYPE_TEXT_FLAG_AUTO_COMPLETE
67 * 1 TYPE_TEXT_FLAG_MULTI_LINE
68 * 1 TYPE_TEXT_FLAG_IME_MULTI_LINE
69 * 1 TYPE_TEXT_FLAG_NO_SUGGESTIONS
70 * |-------|-------|-------|-------|
72 * 1 TYPE_NUMBER_VARIATION_PASSWORD
73 * 1 TYPE_NUMBER_FLAG_SIGNED
74 * 1 TYPE_NUMBER_FLAG_DECIMAL
75 * |-------|-------|-------|-------|
77 * |-------|-------|-------|-------|
78 * 1 TYPE_CLASS_DATETIME
79 * 1 TYPE_DATETIME_VARIATION_DATE
80 * 1 TYPE_DATETIME_VARIATION_TIME
81 * |-------|-------|-------|-------|</pre>
85 * The content type of the text box, whose bits are defined by
89 * @see #TYPE_MASK_CLASS
90 * @see #TYPE_MASK_VARIATION
91 * @see #TYPE_MASK_FLAGS
93 public int inputType = TYPE_NULL;
96 * Set of bits in {@link #imeOptions} that provide alternative actions
97 * associated with the "enter" key. This both helps the IME provide
98 * better feedback about what the enter key will do, and also allows it
99 * to provide alternative mechanisms for providing that command.
101 public static final int IME_MASK_ACTION = 0x000000ff;
104 * Bits of {@link #IME_MASK_ACTION}: no specific action has been
105 * associated with this editor, let the editor come up with its own if
108 public static final int IME_ACTION_UNSPECIFIED = 0x00000000;
111 * Bits of {@link #IME_MASK_ACTION}: there is no available action.
113 public static final int IME_ACTION_NONE = 0x00000001;
116 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "go"
117 * operation to take the user to the target of the text they typed.
118 * Typically used, for example, when entering a URL.
120 public static final int IME_ACTION_GO = 0x00000002;
123 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "search"
124 * operation, taking the user to the results of searching for the text
125 * they have typed (in whatever context is appropriate).
127 public static final int IME_ACTION_SEARCH = 0x00000003;
130 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "send"
131 * operation, delivering the text to its target. This is typically used
132 * when composing a message in IM or SMS where sending is immediate.
134 public static final int IME_ACTION_SEND = 0x00000004;
137 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "next"
138 * operation, taking the user to the next field that will accept text.
140 public static final int IME_ACTION_NEXT = 0x00000005;
143 * Bits of {@link #IME_MASK_ACTION}: the action key performs a "done"
144 * operation, typically meaning there is nothing more to input and the
145 * IME will be closed.
147 public static final int IME_ACTION_DONE = 0x00000006;
150 * Bits of {@link #IME_MASK_ACTION}: like {@link #IME_ACTION_NEXT}, but
151 * for moving to the previous field. This will normally not be used to
152 * specify an action (since it precludes {@link #IME_ACTION_NEXT}), but
153 * can be returned to the app if it sets {@link #IME_FLAG_NAVIGATE_PREVIOUS}.
155 public static final int IME_ACTION_PREVIOUS = 0x00000007;
158 * Flag of {@link #imeOptions}: used to request that the IME never go
159 * into fullscreen mode.
160 * By default, IMEs may go into full screen mode when they think
161 * it's appropriate, for example on small screens in landscape
162 * orientation where displaying a software keyboard may occlude
163 * such a large portion of the screen that the remaining part is
164 * too small to meaningfully display the application UI.
165 * If this flag is set, compliant IMEs will never go into full screen mode,
166 * and always leave some space to display the application UI.
167 * Applications need to be aware that the flag is not a guarantee, and
168 * some IMEs may ignore it.
170 public static final int IME_FLAG_NO_FULLSCREEN = 0x2000000;
173 * Flag of {@link #imeOptions}: like {@link #IME_FLAG_NAVIGATE_NEXT}, but
174 * specifies there is something interesting that a backward navigation
175 * can focus on. If the user selects the IME's facility to backward
176 * navigate, this will show up in the application as an {@link #IME_ACTION_PREVIOUS}
177 * at {@link InputConnection#performEditorAction(int)
178 * InputConnection.performEditorAction(int)}.
180 public static final int IME_FLAG_NAVIGATE_PREVIOUS = 0x4000000;
183 * Flag of {@link #imeOptions}: used to specify that there is something
184 * interesting that a forward navigation can focus on. This is like using
185 * {@link #IME_ACTION_NEXT}, except allows the IME to be multiline (with
186 * an enter key) as well as provide forward navigation. Note that some
187 * IMEs may not be able to do this, especially when running on a small
188 * screen where there is little space. In that case it does not need to
189 * present a UI for this option. Like {@link #IME_ACTION_NEXT}, if the
190 * user selects the IME's facility to forward navigate, this will show up
191 * in the application at {@link InputConnection#performEditorAction(int)
192 * InputConnection.performEditorAction(int)}.
194 public static final int IME_FLAG_NAVIGATE_NEXT = 0x8000000;
197 * Flag of {@link #imeOptions}: used to specify that the IME does not need
198 * to show its extracted text UI. For input methods that may be fullscreen,
199 * often when in landscape mode, this allows them to be smaller and let part
200 * of the application be shown behind, through transparent UI parts in the
201 * fullscreen IME. The part of the UI visible to the user may not be responsive
202 * to touch because the IME will receive touch events, which may confuse the
203 * user; use {@link #IME_FLAG_NO_FULLSCREEN} instead for a better experience.
204 * Using this flag is discouraged and it may become deprecated in the future.
205 * Its meaning is unclear in some situations and it may not work appropriately
206 * on older versions of the platform.
208 public static final int IME_FLAG_NO_EXTRACT_UI = 0x10000000;
211 * Flag of {@link #imeOptions}: used in conjunction with one of the actions
212 * masked by {@link #IME_MASK_ACTION}, this indicates that the action
213 * should not be available as an accessory button on the right of the extracted
214 * text when the input method is full-screen. Note that by setting this flag,
215 * there can be cases where the action is simply never available to the
216 * user. Setting this generally means that you think that in fullscreen mode,
217 * where there is little space to show the text, it's not worth taking some
218 * screen real estate to display the action and it should be used instead
221 public static final int IME_FLAG_NO_ACCESSORY_ACTION = 0x20000000;
224 * Flag of {@link #imeOptions}: used in conjunction with one of the actions
225 * masked by {@link #IME_MASK_ACTION}. If this flag is not set, IMEs will
226 * normally replace the "enter" key with the action supplied. This flag
227 * indicates that the action should not be available in-line as a replacement
228 * for the "enter" key. Typically this is because the action has such a
229 * significant impact or is not recoverable enough that accidentally hitting
230 * it should be avoided, such as sending a message. Note that
231 * {@link android.widget.TextView} will automatically set this flag for you
232 * on multi-line text views.
234 public static final int IME_FLAG_NO_ENTER_ACTION = 0x40000000;
237 * Flag of {@link #imeOptions}: used to request an IME that is capable of
238 * inputting ASCII characters. The intention of this flag is to ensure that
239 * the user can type Roman alphabet characters in a {@link android.widget.TextView}.
240 * It is typically used for an account ID or password input. A lot of the time,
241 * IMEs are already able to input ASCII even without being told so (such IMEs
242 * already respect this flag in a sense), but there are cases when this is not
243 * the default. For instance, users of languages using a different script like
244 * Arabic, Greek, Hebrew or Russian typically have a keyboard that can't
245 * input ASCII characters by default. Applications need to be
246 * aware that the flag is not a guarantee, and some IMEs may not respect it.
247 * However, it is strongly recommended for IME authors to respect this flag
248 * especially when their IME could end up with a state where only languages
249 * using non-ASCII are enabled.
251 public static final int IME_FLAG_FORCE_ASCII = 0x80000000;
254 * Generic unspecified type for {@link #imeOptions}.
256 public static final int IME_NULL = 0x00000000;
259 * Masks for {@link imeOptions}
262 * |-------|-------|-------|-------|
263 * 1111 IME_MASK_ACTION
264 * |-------|-------|-------|-------|
265 * IME_ACTION_UNSPECIFIED
268 * 11 IME_ACTION_SEARCH
270 * 1 1 IME_ACTION_NEXT
272 * 111 IME_ACTION_PREVIOUS
273 * 1 IME_FLAG_NO_FULLSCREEN
274 * 1 IME_FLAG_NAVIGATE_PREVIOUS
275 * 1 IME_FLAG_NAVIGATE_NEXT
276 * 1 IME_FLAG_NO_EXTRACT_UI
277 * 1 IME_FLAG_NO_ACCESSORY_ACTION
278 * 1 IME_FLAG_NO_ENTER_ACTION
279 * 1 IME_FLAG_FORCE_ASCII
280 * |-------|-------|-------|-------|</pre>
284 * Extended type information for the editor, to help the IME better
287 public int imeOptions = IME_NULL;
290 * A string supplying additional information options that are
291 * private to a particular IME implementation. The string must be
292 * scoped to a package owned by the implementation, to ensure there are
293 * no conflicts between implementations, but other than that you can put
294 * whatever you want in it to communicate with the IME. For example,
295 * you could have a string that supplies an argument like
296 * <code>"com.example.myapp.SpecialMode=3"</code>. This field is can be
297 * filled in from the {@link android.R.attr#privateImeOptions}
298 * attribute of a TextView.
300 public String privateImeOptions = null;
303 * In some cases an IME may be able to display an arbitrary label for
304 * a command the user can perform, which you can specify here. This is
305 * typically used as the label for the action to use in-line as a replacement
306 * for the "enter" key (see {@link #actionId}). Remember the key where
307 * this will be displayed is typically very small, and there are significant
308 * localization challenges to make this fit in all supported languages. Also
309 * you can not count absolutely on this being used, as some IMEs may
312 public CharSequence actionLabel = null;
315 * If {@link #actionLabel} has been given, this is the id for that command
316 * when the user presses its button that is delivered back with
317 * {@link InputConnection#performEditorAction(int)
318 * InputConnection.performEditorAction()}.
320 public int actionId = 0;
323 * The text offset of the start of the selection at the time editing
324 * begins; -1 if not known. Keep in mind that, without knowing the cursor
325 * position, many IMEs will not be able to offer their full feature set and
326 * may even behave in unpredictable ways: pass the actual cursor position
327 * here if possible at all.
329 * <p>Also, this needs to be the cursor position <strong>right now</strong>,
330 * not at some point in the past, even if input is starting in the same text field
331 * as before. When the app is filling this object, input is about to start by
332 * definition, and this value will override any value the app may have passed to
333 * {@link InputMethodManager#updateSelection(android.view.View, int, int, int, int)}
336 public int initialSelStart = -1;
339 * <p>The text offset of the end of the selection at the time editing
340 * begins; -1 if not known. Keep in mind that, without knowing the cursor
341 * position, many IMEs will not be able to offer their full feature set and
342 * may behave in unpredictable ways: pass the actual cursor position
343 * here if possible at all.</p>
345 * <p>Also, this needs to be the cursor position <strong>right now</strong>,
346 * not at some point in the past, even if input is starting in the same text field
347 * as before. When the app is filling this object, input is about to start by
348 * definition, and this value will override any value the app may have passed to
349 * {@link InputMethodManager#updateSelection(android.view.View, int, int, int, int)}
352 public int initialSelEnd = -1;
355 * The capitalization mode of the first character being edited in the
356 * text. Values may be any combination of
357 * {@link TextUtils#CAP_MODE_CHARACTERS TextUtils.CAP_MODE_CHARACTERS},
358 * {@link TextUtils#CAP_MODE_WORDS TextUtils.CAP_MODE_WORDS}, and
359 * {@link TextUtils#CAP_MODE_SENTENCES TextUtils.CAP_MODE_SENTENCES}, though
360 * you should generally just take a non-zero value to mean "start out in
363 public int initialCapsMode = 0;
366 * The "hint" text of the text view, typically shown in-line when the
367 * text is empty to tell the user what to enter.
369 public CharSequence hintText;
372 * A label to show to the user describing the text they are writing.
374 public CharSequence label;
377 * Name of the package that owns this editor.
379 * <p><strong>IME authors:</strong> In API level 22
380 * {@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1} and prior, do not trust this package
381 * name. The system had not verified the consistency between the package name here and
382 * application's uid. Consider to use {@link InputBinding#getUid()}, which is trustworthy.
383 * Starting from {@link android.os.Build.VERSION_CODES#M}, the system verifies the consistency
384 * between this package name and application uid before {@link EditorInfo} is passed to the
387 * <p><strong>Editor authors:</strong> Starting from {@link android.os.Build.VERSION_CODES#M},
388 * the application is no longer
389 * able to establish input connections if the package name provided here is inconsistent with
390 * application's uid.</p>
392 public String packageName;
395 * Identifier for the editor's field. This is optional, and may be
396 * 0. By default it is filled in with the result of
397 * {@link android.view.View#getId() View.getId()} on the View that
403 * Additional name for the editor's field. This can supply additional
404 * name information for the field. By default it is null. The actual
405 * contents have no meaning.
407 public String fieldName;
410 * Any extra data to supply to the input method. This is for extended
411 * communication with specific input methods; the name fields in the
412 * bundle should be scoped (such as "com.mydomain.im.SOME_FIELD") so
413 * that they don't conflict with others. This field can be
414 * filled in from the {@link android.R.attr#editorExtras}
415 * attribute of a TextView.
417 public Bundle extras;
420 * List of the languages that the user is supposed to switch to no matter what input method
421 * subtype is currently used. This special "hint" can be used mainly for, but not limited to,
422 * multilingual users who want IMEs to switch language context automatically.
424 * <p>{@code null} means that no special language "hint" is needed.</p>
426 * <p><strong>Editor authors:</strong> Specify this only when you are confident that the user
427 * will switch to certain languages in this context no matter what input method subtype is
428 * currently selected. Otherwise, keep this {@code null}. Explicit user actions and/or
429 * preferences would be good signals to specify this special "hint", For example, a chat
430 * application may be able to put the last used language at the top of {@link #hintLocales}
431 * based on whom the user is going to talk, by remembering what language is used in the last
432 * conversation. Do not specify {@link android.widget.TextView#getTextLocales()} only because
433 * it is used for text rendering.</p>
435 * @see android.widget.TextView#setImeHintLocales(LocaleList)
436 * @see android.widget.TextView#getImeHintLocales()
439 public LocaleList hintLocales = null;
443 * List of acceptable MIME types for
444 * {@link InputConnection#commitContent(InputContentInfo, int, Bundle)}.
446 * <p>{@code null} or an empty array means that
447 * {@link InputConnection#commitContent(InputContentInfo, int, Bundle)} is not supported in this
451 public String[] contentMimeTypes = null;
454 * Ensure that the data in this EditorInfo is compatible with an application
455 * that was developed against the given target API version. This can
456 * impact the following input types:
457 * {@link InputType#TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS},
458 * {@link InputType#TYPE_TEXT_VARIATION_WEB_PASSWORD},
459 * {@link InputType#TYPE_NUMBER_VARIATION_NORMAL},
460 * {@link InputType#TYPE_NUMBER_VARIATION_PASSWORD}.
462 * <p>This is called by the framework for input method implementations;
463 * you should not generally need to call it yourself.
465 * @param targetSdkVersion The API version number that the compatible
466 * application was developed against.
468 public final void makeCompatible(int targetSdkVersion) {
469 if (targetSdkVersion < android.os.Build.VERSION_CODES.HONEYCOMB) {
470 switch (inputType&(TYPE_MASK_CLASS|TYPE_MASK_VARIATION)) {
471 case TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS:
472 inputType = TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_EMAIL_ADDRESS
473 | (inputType&TYPE_MASK_FLAGS);
475 case TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_WEB_PASSWORD:
476 inputType = TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_PASSWORD
477 | (inputType&TYPE_MASK_FLAGS);
479 case TYPE_CLASS_NUMBER|TYPE_NUMBER_VARIATION_NORMAL:
480 case TYPE_CLASS_NUMBER|TYPE_NUMBER_VARIATION_PASSWORD:
481 inputType = TYPE_CLASS_NUMBER
482 | (inputType&TYPE_MASK_FLAGS);
489 * Write debug output of this object.
491 public void dump(Printer pw, String prefix) {
492 pw.println(prefix + "inputType=0x" + Integer.toHexString(inputType)
493 + " imeOptions=0x" + Integer.toHexString(imeOptions)
494 + " privateImeOptions=" + privateImeOptions);
495 pw.println(prefix + "actionLabel=" + actionLabel
496 + " actionId=" + actionId);
497 pw.println(prefix + "initialSelStart=" + initialSelStart
498 + " initialSelEnd=" + initialSelEnd
499 + " initialCapsMode=0x"
500 + Integer.toHexString(initialCapsMode));
501 pw.println(prefix + "hintText=" + hintText
502 + " label=" + label);
503 pw.println(prefix + "packageName=" + packageName
504 + " fieldId=" + fieldId
505 + " fieldName=" + fieldName);
506 pw.println(prefix + "extras=" + extras);
507 pw.println(prefix + "hintLocales=" + hintLocales);
508 pw.println(prefix + "contentMimeTypes=" + Arrays.toString(contentMimeTypes));
512 * Used to package this object into a {@link Parcel}.
514 * @param dest The {@link Parcel} to be written.
515 * @param flags The flags used for parceling.
517 public void writeToParcel(Parcel dest, int flags) {
518 dest.writeInt(inputType);
519 dest.writeInt(imeOptions);
520 dest.writeString(privateImeOptions);
521 TextUtils.writeToParcel(actionLabel, dest, flags);
522 dest.writeInt(actionId);
523 dest.writeInt(initialSelStart);
524 dest.writeInt(initialSelEnd);
525 dest.writeInt(initialCapsMode);
526 TextUtils.writeToParcel(hintText, dest, flags);
527 TextUtils.writeToParcel(label, dest, flags);
528 dest.writeString(packageName);
529 dest.writeInt(fieldId);
530 dest.writeString(fieldName);
531 dest.writeBundle(extras);
532 if (hintLocales != null) {
533 hintLocales.writeToParcel(dest, flags);
535 LocaleList.getEmptyLocaleList().writeToParcel(dest, flags);
537 dest.writeStringArray(contentMimeTypes);
541 * Used to make this class parcelable.
543 public static final Parcelable.Creator<EditorInfo> CREATOR =
544 new Parcelable.Creator<EditorInfo>() {
545 public EditorInfo createFromParcel(Parcel source) {
546 EditorInfo res = new EditorInfo();
547 res.inputType = source.readInt();
548 res.imeOptions = source.readInt();
549 res.privateImeOptions = source.readString();
550 res.actionLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
551 res.actionId = source.readInt();
552 res.initialSelStart = source.readInt();
553 res.initialSelEnd = source.readInt();
554 res.initialCapsMode = source.readInt();
555 res.hintText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
556 res.label = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
557 res.packageName = source.readString();
558 res.fieldId = source.readInt();
559 res.fieldName = source.readString();
560 res.extras = source.readBundle();
561 LocaleList hintLocales = LocaleList.CREATOR.createFromParcel(source);
562 res.hintLocales = hintLocales.isEmpty() ? null : hintLocales;
563 res.contentMimeTypes = source.readStringArray();
567 public EditorInfo[] newArray(int size) {
568 return new EditorInfo[size];
572 public int describeContents() {