frameworks/base/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.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      * Flag of {@link #imeOptions}: used to specify that the IME does not need
  98      * to show its extracted text UI.  For input methods that may be fullscreen,
  99      * often when in landscape mode, this allows them to be smaller and let part
 100      * of the application be shown behind.  Though there will likely be limited
 101      * access to the application available from the user, it can make the
 102      * experience of a (mostly) fullscreen IME less jarring.  Note that when
 103      * this flag is specified the IME may <em>not</em> be set up to be able
 104      * to display text, so it should only be used in situations where this is
 105      * not needed.
 106      */
 107     public static final int IME_FLAG_NO_EXTRACT_UI = 0x10000000;
 108
 109     /**
 110      * Flag of {@link #imeOptions}: used in conjunction with
 111      * {@link #IME_MASK_ACTION}, this indicates that the action should not
 112      * be available as an accessory button when the input method is full-screen.
 113      * Note that by setting this flag, there can be cases where the action
 114      * is simply never available to the user.  Setting this generally means
 115      * that you think showing text being edited is more important than the
 116      * action you have supplied.
 117      */
 118     public static final int IME_FLAG_NO_ACCESSORY_ACTION = 0x20000000;
 119
 120     /**
 121      * Flag of {@link #imeOptions}: used in conjunction with
 122      * {@link #IME_MASK_ACTION}, this indicates that the action should not
 123      * be available in-line as a replacement for "enter" key.  Typically this is
 124      * because the action has such a significant impact or is not recoverable
 125      * enough that accidentally hitting it should be avoided, such as sending
 126      * a message.  Note that {@link android.widget.TextView} will automatically set this
 127      * flag for you on multi-line text views.
 128      */
 129     public static final int IME_FLAG_NO_ENTER_ACTION = 0x40000000;
 130
 131     /**
 132      * Flag of {@link #imeOptions}: used to request that the IME never go
 133      * into fullscreen mode.  Applications need to be aware that the flag is not
 134      * a guarantee, and not all IMEs will respect it.
 135      * @hide
 136      */
 137     public static final int IME_FLAG_NO_FULLSCREEN = 0x80000000;
 138
 139     /**
 140      * Generic unspecified type for {@link #imeOptions}.
 141      */
 142     public static final int IME_NULL = 0x00000000;
 143
 144     /**
 145      * Extended type information for the editor, to help the IME better
 146      * integrate with it.
 147      */
 148     public int imeOptions = IME_NULL;
 149
 150     /**
 151      * A string supplying additional information options that are
 152      * private to a particular IME implementation.  The string must be
 153      * scoped to a package owned by the implementation, to ensure there are
 154      * no conflicts between implementations, but other than that you can put
 155      * whatever you want in it to communicate with the IME.  For example,
 156      * you could have a string that supplies an argument like
 157      * <code>"com.example.myapp.SpecialMode=3"</code>.  This field is can be
 158      * filled in from the {@link android.R.attr#privateImeOptions}
 159      * attribute of a TextView.
 160      */
 161     public String privateImeOptions = null;
 162
 163     /**
 164      * In some cases an IME may be able to display an arbitrary label for
 165      * a command the user can perform, which you can specify here.  You can
 166      * not count on this being used.
 167      */
 168     public CharSequence actionLabel = null;
 169
 170     /**
 171      * If {@link #actionLabel} has been given, this is the id for that command
 172      * when the user presses its button that is delivered back with
 173      * {@link InputConnection#performEditorAction(int)
 174      * InputConnection.performEditorAction()}.
 175      */
 176     public int actionId = 0;
 177
 178     /**
 179      * The text offset of the start of the selection at the time editing
 180      * began; -1 if not known.
 181      */
 182     public int initialSelStart = -1;
 183
 184     /**
 185      * The text offset of the end of the selection at the time editing
 186      * began; -1 if not known.
 187      */
 188     public int initialSelEnd = -1;
 189
 190     /**
 191      * The capitalization mode of the first character being edited in the
 192      * text.  Values may be any combination of
 193      * {@link TextUtils#CAP_MODE_CHARACTERS TextUtils.CAP_MODE_CHARACTERS},
 194      * {@link TextUtils#CAP_MODE_WORDS TextUtils.CAP_MODE_WORDS}, and
 195      * {@link TextUtils#CAP_MODE_SENTENCES TextUtils.CAP_MODE_SENTENCES}, though
 196      * you should generally just take a non-zero value to mean start out in
 197      * caps mode.
 198      */
 199     public int initialCapsMode = 0;
 200
 201     /**
 202      * The "hint" text of the text view, typically shown in-line when the
 203      * text is empty to tell the user what to enter.
 204      */
 205     public CharSequence hintText;
 206
 207     /**
 208      * A label to show to the user describing the text they are writing.
 209      */
 210     public CharSequence label;
 211
 212     /**
 213      * Name of the package that owns this editor.
 214      */
 215     public String packageName;
 216
 217     /**
 218      * Identifier for the editor's field.  This is optional, and may be
 219      * 0.  By default it is filled in with the result of
 220      * {@link android.view.View#getId() View.getId()} on the View that
 221      * is being edited.
 222      */
 223     public int fieldId;
 224
 225     /**
 226      * Additional name for the editor's field.  This can supply additional
 227      * name information for the field.  By default it is null.  The actual
 228      * contents have no meaning.
 229      */
 230     public String fieldName;
 231
 232     /**
 233      * Any extra data to supply to the input method.  This is for extended
 234      * communication with specific input methods; the name fields in the
 235      * bundle should be scoped (such as "com.mydomain.im.SOME_FIELD") so
 236      * that they don't conflict with others.  This field is can be
 237      * filled in from the {@link android.R.attr#editorExtras}
 238      * attribute of a TextView.
 239      */
 240     public Bundle extras;
 241
 242     /**
 243      * Write debug output of this object.
 244      */
 245     public void dump(Printer pw, String prefix) {
 246         pw.println(prefix + "inputType=0x" + Integer.toHexString(inputType)
 247                 + " imeOptions=0x" + Integer.toHexString(imeOptions)
 248                 + " privateImeOptions=" + privateImeOptions);
 249         pw.println(prefix + "actionLabel=" + actionLabel
 250                 + " actionId=" + actionId);
 251         pw.println(prefix + "initialSelStart=" + initialSelStart
 252                 + " initialSelEnd=" + initialSelEnd
 253                 + " initialCapsMode=0x"
 254                 + Integer.toHexString(initialCapsMode));
 255         pw.println(prefix + "hintText=" + hintText
 256                 + " label=" + label);
 257         pw.println(prefix + "packageName=" + packageName
 258                 + " fieldId=" + fieldId
 259                 + " fieldName=" + fieldName);
 260         pw.println(prefix + "extras=" + extras);
 261     }
 262
 263     /**
 264      * Used to package this object into a {@link Parcel}.
 265      *
 266      * @param dest The {@link Parcel} to be written.
 267      * @param flags The flags used for parceling.
 268      */
 269     public void writeToParcel(Parcel dest, int flags) {
 270         dest.writeInt(inputType);
 271         dest.writeInt(imeOptions);
 272         dest.writeString(privateImeOptions);
 273         TextUtils.writeToParcel(actionLabel, dest, flags);
 274         dest.writeInt(actionId);
 275         dest.writeInt(initialSelStart);
 276         dest.writeInt(initialSelEnd);
 277         dest.writeInt(initialCapsMode);
 278         TextUtils.writeToParcel(hintText, dest, flags);
 279         TextUtils.writeToParcel(label, dest, flags);
 280         dest.writeString(packageName);
 281         dest.writeInt(fieldId);
 282         dest.writeString(fieldName);
 283         dest.writeBundle(extras);
 284     }
 285
 286     /**
 287      * Used to make this class parcelable.
 288      */
 289     public static final Parcelable.Creator<EditorInfo> CREATOR = new Parcelable.Creator<EditorInfo>() {
 290         public EditorInfo createFromParcel(Parcel source) {
 291             EditorInfo res = new EditorInfo();
 292             res.inputType = source.readInt();
 293             res.imeOptions = source.readInt();
 294             res.privateImeOptions = source.readString();
 295             res.actionLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
 296             res.actionId = source.readInt();
 297             res.initialSelStart = source.readInt();
 298             res.initialSelEnd = source.readInt();
 299             res.initialCapsMode = source.readInt();
 300             res.hintText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
 301             res.label = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
 302             res.packageName = source.readString();
 303             res.fieldId = source.readInt();
 304             res.fieldName = source.readString();
 305             res.extras = source.readBundle();
 306             return res;
 307         }
 308
 309         public EditorInfo[] newArray(int size) {
 310             return new EditorInfo[size];
 311         }
 312     };
 313
 314     public int describeContents() {
 315         return 0;
 316     }
 317
 318 }