• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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      * 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      */
makeCompatible(int targetSdkVersion)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      */
dump(Printer pw, String prefix)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      */
writeToParcel(Parcel dest, int flags)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 
describeContents()380     public int describeContents() {
381         return 0;
382     }
383 
384 }
385