Beginning Android 3 : The Input Method Framework - Fitting In

3. Tell Android Where It Can Go

You may have noticed a subtle difference between the IME shown in Figure 1 and the IME shown in Figure 2, beyond the addition of the @ key. The lower-right corner of the soft keyboard in Figure 2 has a Next button, whereas the one in Figure 1 has a newline button. This points out two things:

• EditText widgets are multiline by default if you do not specify android:inputType.

• You can control what goes on with that lower-right button, called the accessory button.

By default, on an EditText where you have specified android:inputType, the accessory button will be Next, moving you to the next EditText in sequence, or Done, if you are on the last EditText 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).

2. Fitting In

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:

• Android can "pan" your activity, effectively sliding the whole layout up to accommodate the IME, or overlaying your layout, depending on whether the EditText being edited is at the top or bottom. This has the effect of hiding some portion of your UI.

• Android can resize your activity, effectively causing it to shrink to a smaller screen dimension, allowing the IME to sit below the activity itself. This is great when the layout can readily be shrunk (e.g., it is dominated by a list or multiline input field that does not need the whole screen to be functional).

• In landscape mode, Android may display the IME full-screen, obscuring your entire activity. This allows for a bigger keyboard and generally easier data entry.

Android controls the full-screen option purely on its own. 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 1.

Figure 1. The shrunken, scrollable layout