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
17package android.view.inputmethod;
18
19import android.os.Bundle;
20import android.os.Parcel;
21import android.os.Parcelable;
22import android.text.InputType;
23import android.text.TextUtils;
24import 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 */
31public 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     * Generic unspecified type for {@link #imeOptions}.
172     */
173    public static final int IME_NULL = 0x00000000;
174
175    /**
176     * Extended type information for the editor, to help the IME better
177     * integrate with it.
178     */
179    public int imeOptions = IME_NULL;
180
181    /**
182     * A string supplying additional information options that are
183     * private to a particular IME implementation.  The string must be
184     * scoped to a package owned by the implementation, to ensure there are
185     * no conflicts between implementations, but other than that you can put
186     * whatever you want in it to communicate with the IME.  For example,
187     * you could have a string that supplies an argument like
188     * <code>"com.example.myapp.SpecialMode=3"</code>.  This field is can be
189     * filled in from the {@link android.R.attr#privateImeOptions}
190     * attribute of a TextView.
191     */
192    public String privateImeOptions = null;
193
194    /**
195     * In some cases an IME may be able to display an arbitrary label for
196     * a command the user can perform, which you can specify here.  You can
197     * not count on this being used.
198     */
199    public CharSequence actionLabel = null;
200
201    /**
202     * If {@link #actionLabel} has been given, this is the id for that command
203     * when the user presses its button that is delivered back with
204     * {@link InputConnection#performEditorAction(int)
205     * InputConnection.performEditorAction()}.
206     */
207    public int actionId = 0;
208
209    /**
210     * The text offset of the start of the selection at the time editing
211     * began; -1 if not known.
212     */
213    public int initialSelStart = -1;
214
215    /**
216     * The text offset of the end of the selection at the time editing
217     * began; -1 if not known.
218     */
219    public int initialSelEnd = -1;
220
221    /**
222     * The capitalization mode of the first character being edited in the
223     * text.  Values may be any combination of
224     * {@link TextUtils#CAP_MODE_CHARACTERS TextUtils.CAP_MODE_CHARACTERS},
225     * {@link TextUtils#CAP_MODE_WORDS TextUtils.CAP_MODE_WORDS}, and
226     * {@link TextUtils#CAP_MODE_SENTENCES TextUtils.CAP_MODE_SENTENCES}, though
227     * you should generally just take a non-zero value to mean start out in
228     * caps mode.
229     */
230    public int initialCapsMode = 0;
231
232    /**
233     * The "hint" text of the text view, typically shown in-line when the
234     * text is empty to tell the user what to enter.
235     */
236    public CharSequence hintText;
237
238    /**
239     * A label to show to the user describing the text they are writing.
240     */
241    public CharSequence label;
242
243    /**
244     * Name of the package that owns this editor.
245     */
246    public String packageName;
247
248    /**
249     * Identifier for the editor's field.  This is optional, and may be
250     * 0.  By default it is filled in with the result of
251     * {@link android.view.View#getId() View.getId()} on the View that
252     * is being edited.
253     */
254    public int fieldId;
255
256    /**
257     * Additional name for the editor's field.  This can supply additional
258     * name information for the field.  By default it is null.  The actual
259     * contents have no meaning.
260     */
261    public String fieldName;
262
263    /**
264     * Any extra data to supply to the input method.  This is for extended
265     * communication with specific input methods; the name fields in the
266     * bundle should be scoped (such as "com.mydomain.im.SOME_FIELD") so
267     * that they don't conflict with others.  This field is can be
268     * filled in from the {@link android.R.attr#editorExtras}
269     * attribute of a TextView.
270     */
271    public Bundle extras;
272
273    /**
274     * Ensure that the data in this EditorInfo is compatible with an application
275     * that was developed against the given target API version.  This can
276     * impact the following input types:
277     * {@link InputType#TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS},
278     * {@link InputType#TYPE_TEXT_VARIATION_WEB_PASSWORD},
279     * {@link InputType#TYPE_NUMBER_VARIATION_NORMAL},
280     * {@link InputType#TYPE_NUMBER_VARIATION_PASSWORD}.
281     *
282     * <p>This is called by the framework for input method implementations;
283     * you should not generally need to call it yourself.
284     *
285     * @param targetSdkVersion The API version number that the compatible
286     * application was developed against.
287     */
288    public final void makeCompatible(int targetSdkVersion) {
289        if (targetSdkVersion < android.os.Build.VERSION_CODES.HONEYCOMB) {
290            switch (inputType&(TYPE_MASK_CLASS|TYPE_MASK_VARIATION)) {
291                case TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS:
292                    inputType = TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_EMAIL_ADDRESS
293                            | (inputType&TYPE_MASK_FLAGS);
294                    break;
295                case TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_WEB_PASSWORD:
296                    inputType = TYPE_CLASS_TEXT|TYPE_TEXT_VARIATION_PASSWORD
297                            | (inputType&TYPE_MASK_FLAGS);
298                    break;
299                case TYPE_CLASS_NUMBER|TYPE_NUMBER_VARIATION_NORMAL:
300                case TYPE_CLASS_NUMBER|TYPE_NUMBER_VARIATION_PASSWORD:
301                    inputType = TYPE_CLASS_NUMBER
302                            | (inputType&TYPE_MASK_FLAGS);
303                    break;
304            }
305        }
306    }
307
308    /**
309     * Write debug output of this object.
310     */
311    public void dump(Printer pw, String prefix) {
312        pw.println(prefix + "inputType=0x" + Integer.toHexString(inputType)
313                + " imeOptions=0x" + Integer.toHexString(imeOptions)
314                + " privateImeOptions=" + privateImeOptions);
315        pw.println(prefix + "actionLabel=" + actionLabel
316                + " actionId=" + actionId);
317        pw.println(prefix + "initialSelStart=" + initialSelStart
318                + " initialSelEnd=" + initialSelEnd
319                + " initialCapsMode=0x"
320                + Integer.toHexString(initialCapsMode));
321        pw.println(prefix + "hintText=" + hintText
322                + " label=" + label);
323        pw.println(prefix + "packageName=" + packageName
324                + " fieldId=" + fieldId
325                + " fieldName=" + fieldName);
326        pw.println(prefix + "extras=" + extras);
327    }
328
329    /**
330     * Used to package this object into a {@link Parcel}.
331     *
332     * @param dest The {@link Parcel} to be written.
333     * @param flags The flags used for parceling.
334     */
335    public void writeToParcel(Parcel dest, int flags) {
336        dest.writeInt(inputType);
337        dest.writeInt(imeOptions);
338        dest.writeString(privateImeOptions);
339        TextUtils.writeToParcel(actionLabel, dest, flags);
340        dest.writeInt(actionId);
341        dest.writeInt(initialSelStart);
342        dest.writeInt(initialSelEnd);
343        dest.writeInt(initialCapsMode);
344        TextUtils.writeToParcel(hintText, dest, flags);
345        TextUtils.writeToParcel(label, dest, flags);
346        dest.writeString(packageName);
347        dest.writeInt(fieldId);
348        dest.writeString(fieldName);
349        dest.writeBundle(extras);
350    }
351
352    /**
353     * Used to make this class parcelable.
354     */
355    public static final Parcelable.Creator<EditorInfo> CREATOR = new Parcelable.Creator<EditorInfo>() {
356        public EditorInfo createFromParcel(Parcel source) {
357            EditorInfo res = new EditorInfo();
358            res.inputType = source.readInt();
359            res.imeOptions = source.readInt();
360            res.privateImeOptions = source.readString();
361            res.actionLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
362            res.actionId = source.readInt();
363            res.initialSelStart = source.readInt();
364            res.initialSelEnd = source.readInt();
365            res.initialCapsMode = source.readInt();
366            res.hintText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
367            res.label = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
368            res.packageName = source.readString();
369            res.fieldId = source.readInt();
370            res.fieldName = source.readString();
371            res.extras = source.readBundle();
372            return res;
373        }
374
375        public EditorInfo[] newArray(int size) {
376            return new EditorInfo[size];
377        }
378    };
379
380    public int describeContents() {
381        return 0;
382    }
383
384}
385