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.text;
18
19import android.text.TextUtils;
20
21/**
22 * Bit definitions for an integer defining the basic content type of text
23 * held in an {@link Editable} object. Supported classes may be combined
24 * with variations and flags to indicate desired behaviors.
25 *
26 * <h3>Examples</h3>
27 *
28 * <dl>
29 * <dt>A password field with with the password visible to the user:
30 * <dd>inputType = TYPE_CLASS_TEXT |
31 *     TYPE_TEXT_VARIATION_VISIBLE_PASSWORD
32 *
33 * <dt>A multi-line postal address with automatic capitalization:
34 * <dd>inputType = TYPE_CLASS_TEXT |
35 *     TYPE_TEXT_VARIATION_POSTAL_ADDRESS |
36 *     TYPE_TEXT_FLAG_MULTI_LINE
37 *
38 * <dt>A time field:
39 * <dd>inputType = TYPE_CLASS_DATETIME |
40 *     TYPE_DATETIME_VARIATION_TIME
41 * </dl>
42 */
43public interface InputType {
44    /**
45     * Mask of bits that determine the overall class
46     * of text being given.  Currently supported classes are:
47     * {@link #TYPE_CLASS_TEXT}, {@link #TYPE_CLASS_NUMBER},
48     * {@link #TYPE_CLASS_PHONE}, {@link #TYPE_CLASS_DATETIME}.
49     * If the class is not one you
50     * understand, assume {@link #TYPE_CLASS_TEXT} with NO variation
51     * or flags.
52     */
53    public static final int TYPE_MASK_CLASS = 0x0000000f;
54
55    /**
56     * Mask of bits that determine the variation of
57     * the base content class.
58     */
59    public static final int TYPE_MASK_VARIATION = 0x00000ff0;
60
61    /**
62     * Mask of bits that provide addition bit flags
63     * of options.
64     */
65    public static final int TYPE_MASK_FLAGS = 0x00fff000;
66
67    /**
68     * Special content type for when no explicit type has been specified.
69     * This should be interpreted to mean that the target input connection
70     * is not rich, it can not process and show things like candidate text nor
71     * retrieve the current text, so the input method will need to run in a
72     * limited "generate key events" mode.
73     */
74    public static final int TYPE_NULL = 0x00000000;
75
76    // ----------------------------------------------------------------------
77    // ----------------------------------------------------------------------
78    // ----------------------------------------------------------------------
79
80    /**
81     * Class for normal text.  This class supports the following flags (only
82     * one of which should be set):
83     * {@link #TYPE_TEXT_FLAG_CAP_CHARACTERS},
84     * {@link #TYPE_TEXT_FLAG_CAP_WORDS}, and.
85     * {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}.  It also supports the
86     * following variations:
87     * {@link #TYPE_TEXT_VARIATION_NORMAL}, and
88     * {@link #TYPE_TEXT_VARIATION_URI}.  If you do not recognize the
89     * variation, normal should be assumed.
90     */
91    public static final int TYPE_CLASS_TEXT = 0x00000001;
92
93    /**
94     * Flag for {@link #TYPE_CLASS_TEXT}: capitalize all characters.  Overrides
95     * {@link #TYPE_TEXT_FLAG_CAP_WORDS} and
96     * {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}.  This value is explicitly defined
97     * to be the same as {@link TextUtils#CAP_MODE_CHARACTERS}.
98     */
99    public static final int TYPE_TEXT_FLAG_CAP_CHARACTERS = 0x00001000;
100
101    /**
102     * Flag for {@link #TYPE_CLASS_TEXT}: capitalize first character of
103     * all words.  Overrides {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}.  This
104     * value is explicitly defined
105     * to be the same as {@link TextUtils#CAP_MODE_WORDS}.
106     */
107    public static final int TYPE_TEXT_FLAG_CAP_WORDS = 0x00002000;
108
109    /**
110     * Flag for {@link #TYPE_CLASS_TEXT}: capitalize first character of
111     * each sentence.  This value is explicitly defined
112     * to be the same as {@link TextUtils#CAP_MODE_SENTENCES}.
113     */
114    public static final int TYPE_TEXT_FLAG_CAP_SENTENCES = 0x00004000;
115
116    /**
117     * Flag for {@link #TYPE_CLASS_TEXT}: the user is entering free-form
118     * text that should have auto-correction applied to it.
119     */
120    public static final int TYPE_TEXT_FLAG_AUTO_CORRECT = 0x00008000;
121
122    /**
123     * Flag for {@link #TYPE_CLASS_TEXT}: the text editor is performing
124     * auto-completion of the text being entered based on its own semantics,
125     * which it will present to the user as they type.  This generally means
126     * that the input method should not be showing candidates itself, but can
127     * expect for the editor to supply its own completions/candidates from
128     * {@link android.view.inputmethod.InputMethodSession#displayCompletions
129     * InputMethodSession.displayCompletions()} as a result of the editor calling
130     * {@link android.view.inputmethod.InputMethodManager#displayCompletions
131     * InputMethodManager.displayCompletions()}.
132     */
133    public static final int TYPE_TEXT_FLAG_AUTO_COMPLETE = 0x00010000;
134
135    /**
136     * Flag for {@link #TYPE_CLASS_TEXT}: multiple lines of text can be
137     * entered into the field.  If this flag is not set, the text field
138     * will be constrained to a single line.
139     */
140    public static final int TYPE_TEXT_FLAG_MULTI_LINE = 0x00020000;
141
142    /**
143     * Flag for {@link #TYPE_CLASS_TEXT}: the regular text view associated
144     * with this should not be multi-line, but when a fullscreen input method
145     * is providing text it should use multiple lines if it can.
146     */
147    public static final int TYPE_TEXT_FLAG_IME_MULTI_LINE = 0x00040000;
148
149    /**
150     * Flag for {@link #TYPE_CLASS_TEXT}: the input method does not need to
151     * display any dictionary-based candidates. This is useful for text views that
152     * do not contain words from the language and do not benefit from any
153     * dictionary-based completions or corrections. It overrides the
154     * {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} value when set.
155     */
156    public static final int TYPE_TEXT_FLAG_NO_SUGGESTIONS = 0x00080000;
157
158    // ----------------------------------------------------------------------
159
160    /**
161     * Default variation of {@link #TYPE_CLASS_TEXT}: plain old normal text.
162     */
163    public static final int TYPE_TEXT_VARIATION_NORMAL = 0x00000000;
164
165    /**
166     * Variation of {@link #TYPE_CLASS_TEXT}: entering a URI.
167     */
168    public static final int TYPE_TEXT_VARIATION_URI = 0x00000010;
169
170    /**
171     * Variation of {@link #TYPE_CLASS_TEXT}: entering an e-mail address.
172     */
173    public static final int TYPE_TEXT_VARIATION_EMAIL_ADDRESS = 0x00000020;
174
175    /**
176     * Variation of {@link #TYPE_CLASS_TEXT}: entering the subject line of
177     * an e-mail.
178     */
179    public static final int TYPE_TEXT_VARIATION_EMAIL_SUBJECT = 0x00000030;
180
181    /**
182     * Variation of {@link #TYPE_CLASS_TEXT}: entering a short, possibly informal
183     * message such as an instant message or a text message.
184     */
185    public static final int TYPE_TEXT_VARIATION_SHORT_MESSAGE = 0x00000040;
186
187    /**
188     * Variation of {@link #TYPE_CLASS_TEXT}: entering the content of a long, possibly
189     * formal message such as the body of an e-mail.
190     */
191    public static final int TYPE_TEXT_VARIATION_LONG_MESSAGE = 0x00000050;
192
193    /**
194     * Variation of {@link #TYPE_CLASS_TEXT}: entering the name of a person.
195     */
196    public static final int TYPE_TEXT_VARIATION_PERSON_NAME = 0x00000060;
197
198    /**
199     * Variation of {@link #TYPE_CLASS_TEXT}: entering a postal mailing address.
200     */
201    public static final int TYPE_TEXT_VARIATION_POSTAL_ADDRESS = 0x00000070;
202
203    /**
204     * Variation of {@link #TYPE_CLASS_TEXT}: entering a password.
205     */
206    public static final int TYPE_TEXT_VARIATION_PASSWORD = 0x00000080;
207
208    /**
209     * Variation of {@link #TYPE_CLASS_TEXT}: entering a password, which should
210     * be visible to the user.
211     */
212    public static final int TYPE_TEXT_VARIATION_VISIBLE_PASSWORD = 0x00000090;
213
214    /**
215     * Variation of {@link #TYPE_CLASS_TEXT}: entering text inside of a web form.
216     */
217    public static final int TYPE_TEXT_VARIATION_WEB_EDIT_TEXT = 0x000000a0;
218
219    /**
220     * Variation of {@link #TYPE_CLASS_TEXT}: entering text to filter contents
221     * of a list etc.
222     */
223    public static final int TYPE_TEXT_VARIATION_FILTER = 0x000000b0;
224
225    /**
226     * Variation of {@link #TYPE_CLASS_TEXT}: entering text for phonetic
227     * pronunciation, such as a phonetic name field in contacts.
228     */
229    public static final int TYPE_TEXT_VARIATION_PHONETIC = 0x000000c0;
230
231    /**
232     * Variation of {@link #TYPE_CLASS_TEXT}: entering e-mail address inside
233     * of a web form.  This was added in
234     * {@link android.os.Build.VERSION_CODES#HONEYCOMB}.  An IME must target
235     * this API version or later to see this input type; if it doesn't, a request
236     * for this type will be seen as {@link #TYPE_TEXT_VARIATION_EMAIL_ADDRESS}
237     * when passed through {@link android.view.inputmethod.EditorInfo#makeCompatible(int)
238     * EditorInfo.makeCompatible(int)}.
239     */
240    public static final int TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS = 0x000000d0;
241
242    /**
243     * Variation of {@link #TYPE_CLASS_TEXT}: entering password inside
244     * of a web form.  This was added in
245     * {@link android.os.Build.VERSION_CODES#HONEYCOMB}.  An IME must target
246     * this API version or later to see this input type; if it doesn't, a request
247     * for this type will be seen as {@link #TYPE_TEXT_VARIATION_PASSWORD}
248     * when passed through {@link android.view.inputmethod.EditorInfo#makeCompatible(int)
249     * EditorInfo.makeCompatible(int)}.
250     */
251    public static final int TYPE_TEXT_VARIATION_WEB_PASSWORD = 0x000000e0;
252
253    // ----------------------------------------------------------------------
254    // ----------------------------------------------------------------------
255    // ----------------------------------------------------------------------
256
257    /**
258     * Class for numeric text.  This class supports the following flag:
259     * {@link #TYPE_NUMBER_FLAG_SIGNED} and
260     * {@link #TYPE_NUMBER_FLAG_DECIMAL}.  It also supports the following
261     * variations: {@link #TYPE_NUMBER_VARIATION_NORMAL} and
262     * {@link #TYPE_NUMBER_VARIATION_PASSWORD}.  If you do not recognize
263     * the variation, normal should be assumed.
264     */
265    public static final int TYPE_CLASS_NUMBER = 0x00000002;
266
267    /**
268     * Flag of {@link #TYPE_CLASS_NUMBER}: the number is signed, allowing
269     * a positive or negative sign at the start.
270     */
271    public static final int TYPE_NUMBER_FLAG_SIGNED = 0x00001000;
272
273    /**
274     * Flag of {@link #TYPE_CLASS_NUMBER}: the number is decimal, allowing
275     * a decimal point to provide fractional values.
276     */
277    public static final int TYPE_NUMBER_FLAG_DECIMAL = 0x00002000;
278
279    // ----------------------------------------------------------------------
280
281    /**
282     * Default variation of {@link #TYPE_CLASS_NUMBER}: plain normal
283     * numeric text.  This was added in
284     * {@link android.os.Build.VERSION_CODES#HONEYCOMB}.  An IME must target
285     * this API version or later to see this input type; if it doesn't, a request
286     * for this type will be dropped when passed through
287     * {@link android.view.inputmethod.EditorInfo#makeCompatible(int)
288     * EditorInfo.makeCompatible(int)}.
289     */
290    public static final int TYPE_NUMBER_VARIATION_NORMAL = 0x00000000;
291
292    /**
293     * Variation of {@link #TYPE_CLASS_NUMBER}: entering a numeric password.
294     * This was added in {@link android.os.Build.VERSION_CODES#HONEYCOMB}.  An
295     * IME must target this API version or later to see this input type; if it
296     * doesn't, a request for this type will be dropped when passed
297     * through {@link android.view.inputmethod.EditorInfo#makeCompatible(int)
298     * EditorInfo.makeCompatible(int)}.
299     */
300    public static final int TYPE_NUMBER_VARIATION_PASSWORD = 0x00000010;
301
302    // ----------------------------------------------------------------------
303    // ----------------------------------------------------------------------
304    // ----------------------------------------------------------------------
305
306    /**
307     * Class for a phone number.  This class currently supports no variations
308     * or flags.
309     */
310    public static final int TYPE_CLASS_PHONE = 0x00000003;
311
312    // ----------------------------------------------------------------------
313    // ----------------------------------------------------------------------
314    // ----------------------------------------------------------------------
315
316    /**
317     * Class for dates and times.  It supports the
318     * following variations:
319     * {@link #TYPE_DATETIME_VARIATION_NORMAL}
320     * {@link #TYPE_DATETIME_VARIATION_DATE}, and
321     * {@link #TYPE_DATETIME_VARIATION_TIME},.
322     */
323    public static final int TYPE_CLASS_DATETIME = 0x00000004;
324
325    /**
326     * Default variation of {@link #TYPE_CLASS_DATETIME}: allows entering
327     * both a date and time.
328     */
329    public static final int TYPE_DATETIME_VARIATION_NORMAL = 0x00000000;
330
331    /**
332     * Default variation of {@link #TYPE_CLASS_DATETIME}: allows entering
333     * only a date.
334     */
335    public static final int TYPE_DATETIME_VARIATION_DATE = 0x00000010;
336
337    /**
338     * Default variation of {@link #TYPE_CLASS_DATETIME}: allows entering
339     * only a time.
340     */
341    public static final int TYPE_DATETIME_VARIATION_TIME = 0x00000020;
342}
343