Android 1.5 introduced the input method framework (IMF), which is commonly referred to as soft keyboards. However, this term is not necessarily accurate, as IMF could be used for handwriting recognition or other means of accepting text input via the screen.
Some Android devices have a hardware keyboard that is visible some of the time (when it is slid out). A few Android devices have a hardware keyboard that is always visible (so-called “bar” or “slab” phones). Most Android devices, though, have no hardware keyboard at all. The IMF handles all of these scenarios.
In short, if there is no hardware keyboard, an input method editor (IME) will be available to the user when they tap an enabled EditText
widget. If the default functionality of the IME is what you want to offer, you don't need to make any code changes to your application. Fortunately, Android is fairly smart about guessing what you want, so you may simply need to test with the IME and make no specific code changes.
But the IME may not quite behave how you would like it to for your application. For example, in the Basic/Field
sample project, the FieldDemo
activity has the IME overlaying the multiple-line EditText
, as shown in Figure 11–1. It would be nice to have more control over how this appears, and to be able to control other behavior of the IME. Fortunately, the IMF as a whole gives you many options for this, as described in this chapter.
Android 1.1 and earlier offered many attributes on EditText
widgets to control their style of input, such as android:password
to indicate a field should be for password entry (shrouding the password keystrokes from prying eyes). Starting in Android 1.5, with the IMF, many of these attributes have been combined into a single android:inputType
attribute.
The android:inputType
attribute takes a class plus modifiers, in a pipe-delimited list (where |
is the pipe character). The class generally describes what the user is allowed to input, and this determines the basic set of keys available on the soft keyboard. The available classes are as follows:
text
(the default)number
phone
datetime
date
time
Many of these classes offer one or more modifiers to further refine what the user will be allowed to enter. To get a better understanding of how these modifiers work, take a look at the res/layout/main.xml
file from the InputMethod/IMEDemo1
project:
<?xml version="1.0" encoding="utf-8"?>
<TableLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:stretchColumns="1"
>
<TableRow>
<TextView
android:text="No special rules:"
/>
<EditText
/>
</TableRow>
<TableRow>
<TextView
android:text="Email address:"
/>
<EditText
android:inputType="text|textEmailAddress"
/>
</TableRow>
<TableRow>
<TextView
android:text="Signed decimal number:"
/>
<EditText
android:inputType="number|numberSigned|numberDecimal"
/>
</TableRow>
<TableRow>
<TextView
android:text="Date:"
/>
<EditText
android:inputType="date"
/>
</TableRow>
<TableRow>
<TextView
android:text="Multi-line text:"
/>
<EditText
android:inputType="text|textMultiLine|textAutoCorrect"
android:minLines="3"
android:gravity="top"
/>
</TableRow>
</TableLayout>
This shows a TableLayout
containing five rows, each demonstrating a slightly different flavor of EditText
:
EditText
, meaning you get a plain text-entry field.android:inputType = "text|textEmailAddress"
, meaning it is a text-entry field that specifically seeks an e-mail address.android:inputType = "number|numberSigned|numberDecimal"
.android:inputType = "date"
).android:inputType = "text|textMultiLine|textAutoCorrect"
).The class and modifiers tailor the keyboard. For example, a plain text-entry field results in a plain soft keyboard, as shown in Figure 11–2.
An e-mail address field might put the @
symbol on the soft keyboard, at the cost of a smaller spacebar, as shown in Figure 11–3.
Note that this behavior is specific to the IME. Some editors might put the @
symbol on the primary keyboard for an e-mail field. Some might put a .com
button on the primary keyboard. Some might not react at all. It is up to the implementation of the IME—all you can do is supply the hint.
Number and date fields restrict the keys to numeric keys, plus a set of symbols that may or may not be valid on a given field, as shown in Figure 11–4.
These are just a few examples of the possible IMEs. By choosing the appropriate android:inputType
, you can give users a soft keyboard that best suits the type of data they should be entering.
You may have noticed a subtle difference between the IME shown in Figure 11–2 and the IME shown in Figure 11–3, beyond the addition of the @
key. The lower-right corner of the soft keyboard in Figure 11–3 has a Next button, whereas the one in Figure 11–2 has a newline button. This points out two things:
EditText
widgets are multiline by default if you do not specify android:inputType
.By default, on an EditText
widget where you have specified android:inputType
, the accessory button will be Next, moving you to the next EditText
widget in sequence, or Done, if you are on the last EditText
widget on the screen. You can manually stipulate what the accessory button will be labeled via the android:imeOptions
attribute. For example, in the res/layout/main.xml
file from InputMethod/IMEDemo2
, you will see an augmented version of the previous example, where two input fields specify what their accessory button should look like:
<?xml version="1.0" encoding="utf-8"?>
<ScrollView xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
>
<TableLayout
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:stretchColumns="1"
>
<TableRow>
<TextView
android:text="No special rules:"
/>
<EditText
/>
</TableRow>
<TableRow>
<TextView
android:text="Email address:"
/>
<EditText
android:inputType="text|textEmailAddress"
android:imeOptions="actionSend"
/>
</TableRow>
<TableRow>
<TextView
android:text="Signed decimal number:"
/>
<EditText
android:inputType="number|numberSigned|numberDecimal"
android:imeOptions="actionDone"
/>
</TableRow>
<TableRow>
<TextView
android:text="Date:"
/>
<EditText
android:inputType="date"
/>
</TableRow>
<TableRow>
<TextView
android:text="Multi-line text:"
/>
<EditText
android:inputType="text|textMultiLine|textAutoCorrect"
android:minLines="3"
android:gravity="top"
/>
</TableRow>
</TableLayout>
</ScrollView>
Here, we attach a Send action to the accessory button for the e-mail address (android:imeOptions = "actionSend"
), and the Done action on the middle field (android:imeOptions = "actionDone"
).
By default, Next moves the focus to the next EditText
and Done closes the IME. However, for those actions, or for any others like Send, you can use setOnEditorActionListener()
on EditText
(technically, on the TextView
superclass) to get control when the accessory button is clicked or the user presses the Enter key. You are provided with a flag indicating the desired action (e.g., IME_ACTION_SEND
), and you can then do something to handle that request (e.g., send an e-mail to the supplied e-mail address).
Notice that the IMEDemo2
layout shown in the preceding section has another difference from its IMEDemo1
predecessor: the use of a ScrollView
container wrapping the TableLayout
. This ties into another level of control you have over the IMEs: what happens to your activity's own layout when the IME appears. There are three possibilities, depending on circumstances:
EditText
being edited is at the top or bottom. This has the effect of hiding some portion of your UI.Android controls the full-screen option using its historic defaults. And, by default, Android will choose between pan and resize modes depending on what your layout looks like. If you want to specifically choose between pan and resize, you can do so via an android:windowSoftInputMode
attribute on the <activity>
element in your AndroidManifest.xml
file. For example, here is the manifest from IMEDemo2
:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.commonsware.android.imf.two" android:versionCode="1" android:versionName="1.0">
<application android:label="@string/app_name" android:icon="@drawable/cw">
<activity android:name=".IMEDemo2" android:label="@string/app_name" android:windowSoftInputMode="adjustResize">
<intent-filter>
<action android:name="android.intent.action.MAIN"/>
<category android:name="android.intent.category.LAUNCHER"/>
</intent-filter>
</activity>
</application>
<supports-screens android:largeScreens="true" android:normalScreens="true" android:smallScreens="true" android:anyDensity="true"/>
</manifest>
Because we specified resize, Android will shrink our layout to accommodate the IME. With the ScrollView
in place, this means the scroll bar will appear as needed, as shown in Figure 11–5.
You can control Android's behavior to maximize screen real-estate by using the additional methods introduced in Honeycomb, and refined in Ice Cream Sandwich. Use the Java method setSystemUiVisibility()
with the STATUS_BAR_HIDDEN
option to hide the System Bar and allow even larger full-screen modes, or use the method setDimAmount()
to tweak the brightness of the home buttons to remove distractions from your regularly resized full-screen layout.
Sometimes, you need the IME to just go away. For example, if you make the accessory button a Search button, the IME won't be hidden automatically when the user taps that button, whereas you may want it to be hidden. To hide the IME, you need to make a call to the InputMethodManager
, a system service that controls these IMEs:
InputMethodManager mgr=(InputMethodManager)getSystemService(INPUT_METHOD_SERVICE);
mgr.hideSoftInputFromWindow(fld.getWindowToken(), 0);
(In the preceding line, fld
is the EditText
whose IME you want to hide.)
This will always close the designated IME. However, bear in mind that there are two ways a user can open the IME in the first place:
EditText
, the IME should appear.ListView
), and the user presses the Menu button, the IME should appear.If you want to close the IME only for the first scenario, but not the second, use InputMethodManager.HIDE_IMPLICIT_ONLY
as a flag for the second parameter to your call to hideSoftInputFromWindow()
, instead of the 0
shown in the previous example.