1page.title=Specifying the Input Method Type
2
3trainingnavtop=true
4
5@jd:body
6
7<div id="tb-wrapper">
8<div id="tb">
9
10<h2>This lesson teaches you to</h2>
11<ol>
12  <li><a href="#Type">Specify the Keyboard Type</a></li>
13  <li><a href="#Spelling">Enable Spelling Suggestions and Other Behaviors</a></li>
14  <li><a href="#Action">Specify the Input Method Action</a></li>
15</ol>
16
17<h2>You should also read</h2>
18<ul>
19  <li><a href="{@docRoot}guide/topics/ui/controls/text.html">Text Fields</a></li>
20</ul>
21
22</div>
23</div>
24
25
26<p>Every text field expects a certain type of text input, such as an
27email address, phone number, or just plain text. So it's important
28that you specify the input type for each text field in your app
29so the system displays the appropriate soft input method (such as an on-screen keyboard).</p>
30
31<p>Beyond the type of buttons available with an input method, you should specify
32behaviors such as whether the input method provides spelling suggestions,
33capitalizes new sentences, and replaces the carriage return button with an
34action button such as a <b>Done</b> or <b>Next</b>.
35This lesson shows how to specify these characteristics.</p>
36
37
38
39<h2 id="Type">Specify the Keyboard Type</h2>
40
41<p>You should always declare the input method for your text fields by adding
42the <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
43>{@code android:inputType}</a> attribute to the {@link android.widget.EditText
44&lt;EditText&gt;} element.</p>
45
46<div class="figure" style="width:300px">
47<img src="{@docRoot}images/ui/edittext-phone.png" alt="" />
48<p class="img-caption"><strong>Figure 1.</strong> The {@code phone} input type.</p>
49</div>
50
51<p>For example, if you'd like an input method for entering a phone number,
52use the {@code "phone"} value:</p>
53<pre>
54&lt;EditText
55    android:id="@+id/phone"
56    android:layout_width="fill_parent"
57    android:layout_height="wrap_content"
58    android:hint="@string/phone_hint"
59    android:inputType="phone" />
60</pre>
61
62<div class="figure" style="width:300px">
63<img src="{@docRoot}images/training/input/ime_password.png" alt="" />
64<p class="img-caption"><strong>Figure 2.</strong> The {@code textPassword} input type.</p>
65</div>
66
67<p>Or if the text field is for a password, use the {@code "textPassword"} value
68so the text field conceals the user's input:</p>
69<pre>
70&lt;EditText
71    android:id="@+id/password"
72    android:hint="@string/password_hint"
73    android:inputType="textPassword"
74    ... />
75</pre>
76
77<p>There are several possible values documented with the
78<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
79>{@code android:inputType}</a> attribute and
80some of the values can be combined to specify the input method
81appearance and additional behaviors.</p>
82
83
84
85<h2 id="Spelling">Enable Spelling Suggestions and Other Behaviors</h2>
86
87<div class="figure" style="width:300px">
88<img src="{@docRoot}images/training/input/ime_autocorrect.png" alt="" />
89<p class="img-caption"><strong>Figure 3.</strong> Adding {@code textAutoCorrect}
90provides auto-correction for misspellings.</p>
91</div>
92
93<p>The <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
94>{@code android:inputType}</a> attribute allows you to specify various behaviors for the
95input method. Most importantly, if your text field is intended for basic text input (such
96as for a text message), you should enable auto spelling correction with the
97{@code "textAutoCorrect"} value.</p>
98
99<p>You can combine different behaviors and input method styles with the
100<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
101>{@code android:inputType}</a> attribute. For example,
102here's how to create a text field that capitalizes the first word of a sentence
103and also auto-corrects misspellings:</p>
104
105<pre>
106&lt;EditText
107    android:id="@+id/message"
108    android:layout_width="wrap_content"
109    android:layout_height="wrap_content"
110    android:inputType=
111        "textCapSentences|textAutoCorrect"
112    ... />
113</pre>
114
115
116
117
118<h2 id="Action">Specify the Input Method Action</h2>
119
120<p>Most soft input methods provide a user action button in the
121bottom corner that's appropriate for the current text field.
122By default, the system uses this button for either a <b>Next</b> or
123<b>Done</b> action unless your text field allows multi-line text (such as with {@code
124android:inputType="textMultiLine"}), in which case the action button is a carriage return.
125However, you can specify additional actions that might be more appropriate for your
126text field, such as <b>Send</b> or <b>Go</b>.</p>
127
128<p>To specify the keyboard action button, use the <a
129href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code
130android:imeOptions}</a> attribute with an action value such as {@code "actionSend"} or
131{@code "actionSearch"}. For example:</p>
132
133<div class="figure" style="width:300px">
134<img src="{@docRoot}images/ui/edittext-actionsend.png" alt="" />
135<p class="img-caption"><strong>Figure 4.</strong> The Send button appears when you declare
136{@code android:imeOptions="actionSend"}.</p>
137</div>
138
139<pre>
140&lt;EditText
141    android:id="@+id/search"
142    android:layout_width="fill_parent"
143    android:layout_height="wrap_content"
144    android:hint="@string/search_hint"
145    android:inputType="text"
146    android:imeOptions="actionSend" />
147</pre>
148
149<p>You can then listen for presses on the action button by defining a
150{@link android.widget.TextView.OnEditorActionListener} for the {@link android.widget.EditText}
151element. In your listener, respond to the appropriate IME action ID defined in the
152{@link android.view.inputmethod.EditorInfo} class, such as
153{@link android.view.inputmethod.EditorInfo#IME_ACTION_SEND}. For example:</p>
154
155<pre>
156EditText editText = (EditText) findViewById(R.id.search);
157editText.setOnEditorActionListener(new OnEditorActionListener() {
158    &#64;Override
159    public boolean onEditorAction(TextView v, int actionId, KeyEvent event) {
160        boolean handled = false;
161        if (actionId == EditorInfo.IME_ACTION_SEND) {
162            sendMessage();
163            handled = true;
164        }
165        return handled;
166    }
167});
168</pre>
169
170
171
172