Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 1 | page.title=Text Fields |
Scott Main | 64461bf | 2013-04-11 19:32:08 -0700 | [diff] [blame] | 2 | page.tags="edittext","autocompletetextview" |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 3 | @jd:body |
| 4 | |
| 5 | <div id="qv-wrapper"> |
| 6 | <div id="qv"> |
| 7 | |
| 8 | <h2>In this document</h2> |
| 9 | <ol> |
| 10 | <li><a href="#Keyboard">Specifying the Keyboard Type</a> |
| 11 | <ol> |
| 12 | <li><a href="#Behaviors">Controlling other behaviors</a></li> |
| 13 | </ol> |
| 14 | </li> |
| 15 | <li><a href="#Actions">Specifying Keyboard Actions</a> |
| 16 | <ol> |
| 17 | <li><a href="#ActionEvent">Responding to action button events</a></li> |
| 18 | <li><a href="#ActionLabel">Setting a custom action button label</a></li> |
| 19 | </ol> |
| 20 | </li> |
| 21 | <li><a href="#Flags">Adding Other Keyboard Flags</a></li> |
| 22 | <li><a href="#AutoComplete">Providing Auto-complete Suggestions</a></li> |
| 23 | </ol> |
| 24 | <h2>Key classes</h2> |
| 25 | <ol> |
| 26 | <li>{@link android.widget.EditText}</li> |
| 27 | <li>{@link android.widget.AutoCompleteTextView}</li> |
| 28 | </ol> |
| 29 | |
| 30 | </div> |
| 31 | </div> |
| 32 | |
| 33 | <p>A text field allows the user to type text into your app. It can be either single line or |
| 34 | multi-line. Touching a text field places the cursor and automatically displays the keyboard. In |
| 35 | addition to typing, text fields allow for a variety of other activities, such as text selection |
| 36 | (cut, copy, paste) and data look-up via auto-completion.</p> |
| 37 | |
| 38 | <p>You can add a text field to you layout with the {@link android.widget.EditText} object. You |
| 39 | should usually do so in your XML layout with a {@code <EditText>} element.</p> |
| 40 | |
| 41 | <img src="{@docRoot}images/ui/edittext-noextract.png" alt="" /> |
| 42 | |
| 43 | |
| 44 | |
| 45 | <h2 id="Keyboard">Specifying the Keyboard Type</h2> |
| 46 | |
| 47 | <div class="figure" style="width:300px;margin-top:0"> |
| 48 | <img src="{@docRoot}images/ui/edittext-text.png" alt="" /> |
| 49 | <p class="img-caption"><strong>Figure 1.</strong> The default {@code text} input type.</p> |
| 50 | </div> |
| 51 | |
| 52 | <div class="figure" style="width:300px"> |
| 53 | <img src="{@docRoot}images/ui/edittext-email.png" alt="" /> |
| 54 | <p class="img-caption"><strong>Figure 2.</strong> The {@code textEmailAddress} input type.</p> |
| 55 | </div> |
| 56 | |
| 57 | <div class="figure" style="width:300px"> |
| 58 | <img src="{@docRoot}images/ui/edittext-phone.png" alt="" /> |
| 59 | <p class="img-caption"><strong>Figure 3.</strong> The {@code phone} input type.</p> |
| 60 | </div> |
| 61 | |
| 62 | <p>Text fields can have different input types, such as number, date, password, or email address. The |
| 63 | type determines what kind of characters are allowed inside the field, and may prompt the virtual |
| 64 | keyboard to optimize its layout for frequently used characters.</p> |
| 65 | |
| 66 | <p>You can specify the type of keyboard you want for your {@link android.widget.EditText} object |
| 67 | with the <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code |
| 68 | android:inputType}</a> attribute. For example, if you want the user to input an email address, you |
| 69 | should use the {@code textEmailAddress} input type:</p> |
| 70 | |
| 71 | <pre> |
| 72 | <EditText |
| 73 | android:id="@+id/email_address" |
| 74 | android:layout_width="fill_parent" |
| 75 | android:layout_height="wrap_content" |
| 76 | android:hint="@string/email_hint" |
| 77 | android:inputType="textEmailAddress" /> |
| 78 | </pre> |
| 79 | |
| 80 | |
Scott Main | c8a6f8a | 2012-12-05 16:13:25 -0800 | [diff] [blame] | 81 | <p>There are several different input types available for different situations. |
| 82 | Here are some of the more common values for |
| 83 | <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType" |
| 84 | >{@code android:inputType}</a>:</p> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 85 | |
Scott Main | c8a6f8a | 2012-12-05 16:13:25 -0800 | [diff] [blame] | 86 | <dl> |
| 87 | <dt>{@code "text"}</dt> |
| 88 | <dd>Normal text keyboard.</dd> |
| 89 | <dt>{@code "textEmailAddress"}</dt> |
| 90 | <dd>Normal text keyboard with the @ character.</dd> |
| 91 | <dt>{@code "textUri"}</dt> |
| 92 | <dd>Normal text keyboard with the / character.</dd> |
| 93 | <dt>{@code "number"}</dt> |
| 94 | <dd>Basic number keypad.</dd> |
| 95 | <dt>{@code "phone"}</dt> |
| 96 | <dd>Phone-style keypad.</dd> |
| 97 | </dl> |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 98 | |
| 99 | |
| 100 | <h3 id="Behaviors">Controlling other behaviors</h3> |
| 101 | |
| 102 | <p>The <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code |
| 103 | android:inputType}</a> also allows you to specify certain keyboard behaviors, such as whether to |
| 104 | capitalize all new words or use features like auto-complete and spelling suggestions.</p> |
| 105 | |
| 106 | <p>The <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code |
| 107 | android:inputType}</a> attribute allows bitwise combinations so you can specify both a keyboard |
Scott Main | c8a6f8a | 2012-12-05 16:13:25 -0800 | [diff] [blame] | 108 | layout and one or more behaviors at once.</p> |
| 109 | |
| 110 | <p>Here are some of the common input type values that define keyboard behaviors:</p> |
| 111 | |
| 112 | <dl> |
| 113 | <dt>{@code "textCapSentences"}</dt> |
| 114 | <dd>Normal text keyboard that capitalizes the first letter for each new sentence.</dd> |
| 115 | <dt>{@code "textCapWords"}</dt> |
| 116 | <dd>Normal text keyboard that capitalizes every word. Good for titles or person names.</dd> |
| 117 | <dt>{@code "textAutoCorrect"}</dt> |
| 118 | <dd>Normal text keyboard that corrects commonly misspelled words.</dd> |
| 119 | <dt>{@code "textPassword"}</dt> |
| 120 | <dd>Normal text keyboard, but the characters entered turn into dots.</dd> |
| 121 | <dt>{@code "textMultiLine"}</dt> |
| 122 | <dd>Normal text keyboard that allow users to input long strings of text that include line |
| 123 | breaks (carriage returns).</dd> |
| 124 | </dl> |
| 125 | |
| 126 | <p>For example, here's how you can collect a postal |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 127 | address, capitalize each word, and disable text suggestions:</p> |
| 128 | |
| 129 | <pre> |
| 130 | <EditText |
| 131 | android:id="@+id/postal_address" |
| 132 | android:layout_width="fill_parent" |
| 133 | android:layout_height="wrap_content" |
| 134 | android:hint="@string/postal_address_hint" |
| 135 | android:inputType="textPostalAddress| |
| 136 | textCapWords| |
| 137 | textNoSuggestions" /> |
| 138 | </pre> |
| 139 | |
| 140 | <p>All behaviors are also listed with the <a |
| 141 | href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code |
| 142 | android:inputType}</a> documentation.</p> |
| 143 | |
| 144 | |
| 145 | <h2 id="Actions">Specifying Keyboard Actions</h2> |
| 146 | |
| 147 | <div class="figure" style="width:300px"> |
| 148 | <img src="{@docRoot}images/ui/edittext-actionsend.png" alt="" /> |
| 149 | <p class="img-caption"><strong>Figure 4.</strong> If you declare {@code |
| 150 | android:imeOptions="actionSend"}, the keyboard includes the Send action.</p> |
| 151 | </div> |
| 152 | |
| 153 | <p>In addition to changing the keyboard's input type, Android allows you to specify an action to be |
| 154 | made when users have completed their input. The action specifies the button that appears in place of |
| 155 | the carriage return key and the action to be made, such as "Search" or "Send."</p> |
| 156 | |
| 157 | <p>You can specify the action by setting the <a |
| 158 | href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code |
| 159 | android:imeOptions}</a> attribute. For example, here's how you can specify the Send action:</p> |
| 160 | |
| 161 | <pre> |
| 162 | <EditText |
| 163 | android:id="@+id/search" |
| 164 | android:layout_width="fill_parent" |
| 165 | android:layout_height="wrap_content" |
| 166 | android:hint="@string/search_hint" |
| 167 | android:inputType="text" |
| 168 | android:imeOptions="actionSend" /> |
| 169 | </pre> |
| 170 | |
| 171 | <p>If you do not explicitly specify an input action then the system attempts to determine if there |
| 172 | are any subsequent <a |
| 173 | href="{@docRoot}reference/android/view/View.html#attr_android:focusable">{@code |
| 174 | android:focusable}</a> fields. If any focusable fields are found following this one, the system |
| 175 | applies the (@code actionNext} action to the current {@link android.widget.EditText} so the user can |
| 176 | select Next to move to the next field. If there's no subsequent focusable field, the system applies |
| 177 | the {@code "actionDone"} action. You can override this by setting the <a |
| 178 | href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code |
| 179 | android:imeOptions}</a> attribute to any other value such as {@code "actionSend"} or {@code |
| 180 | "actionSearch"} or suppress the default behavior by using the {@code "actionNone"} action.</p> |
| 181 | |
| 182 | |
| 183 | <h3 id="ActionEvent">Responding to action button events</h3> |
| 184 | |
| 185 | <p>If you have specified a keyboard action for the input method using <a |
| 186 | href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code |
| 187 | android:imeOptions}</a> attribute (such as {@code "actionSend"}), you can listen for the specific |
| 188 | action event using an {@link android.widget.TextView.OnEditorActionListener}. The {@link |
| 189 | android.widget.TextView.OnEditorActionListener} interface provides a callback method called {@link |
| 190 | android.widget.TextView.OnEditorActionListener#onEditorAction onEditorAction()} that indicates the |
| 191 | action type invoked with an action ID such as {@link |
| 192 | android.view.inputmethod.EditorInfo#IME_ACTION_SEND} or {@link |
| 193 | android.view.inputmethod.EditorInfo#IME_ACTION_SEARCH}.</p> |
| 194 | |
| 195 | <p>For example, here's how you can listen for when the user clicks the Send button on the |
| 196 | keyboard:</p> |
| 197 | |
| 198 | <pre> |
| 199 | EditText editText = (EditText) findViewById(R.id.search); |
| 200 | editText.setOnEditorActionListener(new OnEditorActionListener() { |
| 201 | @Override |
| 202 | public boolean onEditorAction(TextView v, int actionId, KeyEvent event) { |
| 203 | boolean handled = false; |
| 204 | if (actionId == EditorInfo.IME_ACTION_SEND) { |
Scott Main | c8a6f8a | 2012-12-05 16:13:25 -0800 | [diff] [blame] | 205 | sendMessage(); |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 206 | handled = true; |
| 207 | } |
| 208 | return handled; |
| 209 | } |
| 210 | }); |
| 211 | </pre> |
| 212 | |
| 213 | |
| 214 | <h3 id="ActionLabel">Setting a custom action button label</h3> |
| 215 | |
| 216 | <p>If the keyboard is too large to reasonably share space with the underlying application (such as |
| 217 | when a handset device is in landscape orientation) then fullscreen ("extract mode") is triggered. In |
| 218 | this mode, a labeled action button is displayed next to the input. You can customize the text of |
| 219 | this button by setting the <a |
| 220 | href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeActionLabel">{@code |
| 221 | android:imeActionLabel}</a> attribute:</p> |
| 222 | |
| 223 | <pre> |
| 224 | <EditText |
| 225 | android:id="@+id/launch_codes" |
| 226 | android:layout_width="fill_parent" |
| 227 | android:layout_height="wrap_content" |
| 228 | android:hint="@string/enter_launch_codes" |
| 229 | android:inputType="number" |
| 230 | android:imeActionLabel="@string/launch" /> |
| 231 | </pre> |
| 232 | |
| 233 | <img src="{@docRoot}images/ui/edittext-actionlabel.png" alt="" /> |
| 234 | <p class="img-caption"><strong>Figure 5.</strong> A custom action label with <a |
| 235 | href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeActionLabel">{@code |
| 236 | android:imeActionLabel}</a>.</p> |
| 237 | |
| 238 | |
| 239 | |
| 240 | <h2 id="Flags">Adding Other Keyboard Flags</h2> |
| 241 | |
| 242 | <p>In addition to the actions you can specify with the <a |
| 243 | href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code |
| 244 | android:imeOptions}</a> attribute, you can add additional flags to specify other keyboard |
| 245 | behaviors. All available flags are listed along with the actions in the <a |
| 246 | href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code |
| 247 | android:imeOptions}</a> documentation.</p> |
| 248 | |
| 249 | <p>For example, figure 5 shows how the system enables a fullscreen text field when a handset device |
| 250 | is in landscape orientation (or the screen space is otherwise constrained for space). You can |
| 251 | disable the fullscreen input mode with {@code flagNoExtractUi} in the <a |
| 252 | href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code |
| 253 | android:imeOptions}</a> attribute, as shown in figure 6.</p> |
| 254 | |
| 255 | <img src="{@docRoot}images/ui/edittext-noextract.png" alt="" /> |
| 256 | <p class="img-caption"><strong>Figure 6.</strong> The fullscreen text field ("extract mode") is |
| 257 | disabled with {@code android:imeOptions="flagNoExtractUi"}.</p> |
| 258 | |
| 259 | |
| 260 | |
| 261 | |
| 262 | <h2 id="AutoComplete">Providing Auto-complete Suggestions</h2> |
| 263 | |
| 264 | <p>If you want to provide suggestions to users as they type, you can use a subclass of {@link |
| 265 | android.widget.EditText} called {@link android.widget.AutoCompleteTextView}. To implement |
| 266 | auto-complete, you must specify an (@link android.widget.Adapter) that provides the text |
| 267 | suggestions. There are several kinds of adapters available, depending on where the data is coming |
| 268 | from, such as from a database or an array.</p> |
| 269 | |
| 270 | <img src="{@docRoot}images/ui/edittext-autocomplete.png" alt="" /> |
| 271 | <p class="img-caption"><strong>Figure 7.</strong> Example of {@link |
| 272 | android.widget.AutoCompleteTextView} with text suggestions.</p> |
| 273 | |
| 274 | <p>The following procedure describes how to set up an {@link android.widget.AutoCompleteTextView} |
| 275 | that provides suggestions from an array, using {@link android.widget.ArrayAdapter}: |
| 276 | |
| 277 | <ol> |
| 278 | <li>Add the {@link android.widget.AutoCompleteTextView} to your layout. Here's a |
| 279 | layout with only the text field: |
| 280 | <pre> |
| 281 | <?xml version="1.0" encoding="utf-8"?> |
| 282 | <AutoCompleteTextView xmlns:android="http://schemas.android.com/apk/res/android" |
| 283 | android:id="@+id/autocomplete_country" |
| 284 | android:layout_width="fill_parent" |
| 285 | android:layout_height="wrap_content" /> |
| 286 | </pre> |
| 287 | </li> |
| 288 | |
| 289 | <li>Define the array that contains all text suggestions. For example, here's an array of country |
| 290 | names that's defined in an XML resource file ({@code res/values/strings.xml}): |
| 291 | <pre> |
| 292 | <?xml version="1.0" encoding="utf-8"?> |
| 293 | <resources> |
| 294 | <string-array name="countries_array"> |
| 295 | <item>Afghanistan</item> |
| 296 | <item>Albania</item> |
| 297 | <item>Algeria</item> |
| 298 | <item>American Samoa</item> |
| 299 | <item>Andorra</item> |
| 300 | <item>Angola</item> |
| 301 | <item>Anguilla</item> |
| 302 | <item>Antarctica</item> |
| 303 | ... |
| 304 | </string-array> |
| 305 | </resources> |
| 306 | </pre> |
| 307 | </li> |
| 308 | |
| 309 | <li>In your {@link android.app.Activity} or {@link android.app.Fragment}, use the following |
| 310 | code to specify the adapter that supplies the suggestions: |
| 311 | <pre> |
| 312 | // Get a reference to the AutoCompleteTextView in the layout |
| 313 | AutoCompleteTextView textView = (AutoCompleteTextView) findViewById(R.id.autocomplete_country); |
| 314 | // Get the string array |
| 315 | String[] countries = getResources().getStringArray(R.array.countries_array); |
| 316 | // Create the adapter and set it to the AutoCompleteTextView |
| 317 | ArrayAdapter<String> adapter = |
| 318 | new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, countries); |
| 319 | textView.setAdapter(adapter); |
| 320 | </pre> |
| 321 | |
| 322 | <p>Here, a new {@link |
| 323 | android.widget.ArrayAdapter} is initialized to bind each item in the <code>COUNTRIES</code> |
| 324 | string array to a {@link android.widget.TextView} that exists in the {@code simple_list_item_1} |
| 325 | layout (this is a layout provided by Android that provides a standard appearance for text in a |
| 326 | list).</p> |
| 327 | <p>Then assign the adapter to the {@link android.widget.AutoCompleteTextView} by |
| 328 | calling {@link android.widget.AutoCompleteTextView#setAdapter setAdapter()}.</p> |
| 329 | </li> |
| 330 | </ol> |
| 331 | |