core/java/android/view/inputmethod/EditorInfo.java

   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      */
 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      */
 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      */
 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
 482     public int describeContents() {
 483         return 0;
 484     }
 485
 486 }