# Text Fields-文本框

A text field allows the user to type text into your app. It can be either single line or multi-line. Touching a text field places the cursor and automatically displays the keyboard. In addition to typing, text fields allow for a variety of other activities, such as text selection (cut, copy, paste) and data look-up via auto-completion.

You can add a text field to you layout with the EditText object. You should usually do so in your XML layout with a <EditText> element.

## Specifying the Keyboard Type-指定键盘类型

Text fields can have different input types, such as number, date, password, or email address. The type determines what kind of characters are allowed inside the field, and may prompt the virtual keyboard to optimize its layout for frequently used characters.

You can specify the type of keyboard you want for your EditText object with the android:inputType attribute. For example, if you want the user to input an email address, you should use the textEmailAddress input type:


<EditText
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:hint="@string/email_hint"


There are several different input types available for different situations. You can find them all listed with the documentation for android:inputType

Tip: To allow users to input long strings of text with line breaks, use the "textMultiLine" input type. By default, an EditText object is restricted to one line of text and scrolls horizontally when the text exceeds the available width.

### Controlling other behaviors-控制其他行为

The android:inputType also allows you to specify certain keyboard behaviors, such as whether to capitalize all new words or use features like auto-complete and spelling suggestions.
android：inputType还允许您指定操作行为，如在某此键盘上是否要利用所有新词，或使用自动完成和拼写建议功能。

The android:inputType attribute allows bitwise combinations so you can specify both a keyboard layout and one or more behaviors at once. For example, here's how you can collect a postal address, capitalize each word, and disable text suggestions:


<EditText
android:layout_width="fill_parent"
android:layout_height="wrap_content"
textCapWords|
textNoSuggestions" />


All behaviors are also listed with the android:inputType documentation.

## Specifying Keyboard Actions-指定键盘操作

In addition to changing the keyboard's input type, Android allows you to specify an action to be made when users have completed their input. The action specifies the button that appears in place of the carriage return key and the action to be made, such as "Search" or "Send."

You can specify the action by setting the android:imeOptions attribute. For example, here's how you can specify the Send action:


<EditText
android:id="@+id/search"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:hint="@string/search_hint"
android:inputType="text"
android:imeOptions="actionSend" />


If you do not explicitly specify an input action then the system attempts to determine if there are any subsequent android:focusable fields. If any focusable fields are found following this one, the system applies the (@code actionNext} action to the current EditText so the user can select Next to move to the next field. If there's no subsequent focusable field, the system applies the "actionDone" action. You can override this by setting the android:imeOptions attribute to any other value such as "actionSend" or "actionSearch" or suppress the default behavior by using the "actionNone" action.

### Responding to action button events-响应按钮事件

If you have specified a keyboard action for the input method using android:imeOptions attribute (such as"actionSend"), you can listen for the specific action event using an TextView.OnEditorActionListener. The TextView.OnEditorActionListener interface provides a callback method called onEditorAction()that indicates the action type invoked with an action ID such as IME_ACTION_SEND or IME_ACTION_SEARCH.

For example, here's how you can listen for when the user clicks the Send button on the keyboard:


EditText editText = (EditText) findViewById(R.id.search);
editText.setOnEditorActionListener(new OnEditorActionListener() {
@Override
public boolean onEditorAction(TextView v, int actionId, KeyEvent event) {
boolean handled = false;
if (actionId == EditorInfo.IME_ACTION_SEND) {
// Send the user message
handled = true;
}
return handled;
}
});


### Setting a custom action button label-设置文本框标签

If the keyboard is too large to reasonably share space with the underlying application (such as when a handset device is in landscape orientation) then fullscreen ("extract mode") is triggered. In this mode, a labeled action button is displayed next to the input. You can customize the text of this button by setting the android:imeActionLabel attribute:


<EditText
android:id="@+id/launch_codes"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:hint="@string/enter_launch_codes"
android:inputType="number"
android:imeActionLabel="@string/launch" />


Figure 5. A custom action label with android:imeActionLabel
android:imeActionLabel属性案例

In addition to the actions you can specify with the android:imeOptions attribute, you can add additional flags to specify other keyboard behaviors. All available flags are listed along with the actions in the android:imeOptions documentation.

For example, figure 5 shows how the system enables a fullscreen text field when a handset device is in landscape orientation (or the screen space is otherwise constrained for space). You can disable the fullscreen input mode with flagNoExtractUi in the android:imeOptions attribute, as shown in figure 6.

Figure 6. The fullscreen text field ("extract mode") is disabled with android:imeOptions="flagNoExtractUi".
android:imeOptions="flagNoExtractUi"的提取模式

## Providing Auto-complete Suggestions-提供自动完成建议

If you want to provide suggestions to users as they type, you can use a subclass of EditText called AutoCompleteTextView. To implement auto-complete, you must specify an (@link android.widget.Adapter) that provides the text suggestions. There are several kinds of adapters available, depending on where the data is coming from, such as from a database or an array.

Figure 7. Example of AutoCompleteTextView with text suggestions
AutoCompleteTextView控件案例

The following procedure describes how to set up an AutoCompleteTextView that provides suggestions from an array, using ArrayAdapter:

1.Add the AutoCompleteTextView to your layout. Here's a layout with only the text field:


<?xml version="1.0" encoding="utf-8"?>
<AutoCompleteTextView xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/autocomplete_country"
android:layout_width="fill_parent"
android:layout_height="wrap_content" />


2.Define the array that contains all text suggestions. For example, here's an array of country names that's defined in an XML resource file (res/values/strings.xml):


<?xml version="1.0" encoding="utf-8"?>
<resources>
<string-array name="countries_array">
<item>Afghanistan</item>
<item>Albania</item>
<item>Algeria</item>
<item>American Samoa</item>
<item>Andorra</item>
<item>Angola</item>
<item>Anguilla</item>
<item>Antarctica</item>
...
</string-array>
</resources>


3.In your Activity or Fragment, use the following code to specify the adapter that supplies the suggestions:


// Get a reference to the AutoCompleteTextView in the layout
AutoCompleteTextView textView = (AutoCompleteTextView) findViewById(R.id.autocomplete_country);
// Get the string array
String[] countries = getResources().getStringArray(R.array.countries_array);
// Create the adapter and set it to the AutoCompleteTextView