The candidates view is the UI where the IME displays potential word corrections or suggestions for the user to select. In the IME lifecycle, the system calls {@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when it's ready to display the candidates view. In your implementation of this method, return a layout that shows word suggestions, or return null if you don’t want to show anything. A null response is the default behavior, so you don’t have to implement this if you don’t provide suggestions.
For an example implementation that provides user suggestions, see the SoftKeyboard sample app.
UI design considerations
This section describes some specific UI design considerations for IMEs.
Handling multiple screen sizes
The UI for your IME must be able to scale for different screen sizes, and it also must handle both landscape and portrait orientations. In non-fullscreen IME mode, leave sufficient space for the application to show the text field and any associated context, so that no more than half the screen is occupied by the IME. In fullscreen IME mode this is not an issue.
Handling different input types
Android text fields allow you to set a specific input type, such as free-form text, numbers, URLs, email addresses, and search strings. When you implement a new IME, you need to detect the input type of each field and provide the appropriate interface for it. However, you don't have to set up your IME to check that the user entered text valid for the input type; that's the responsibility of the application that owns the text field.
For example, here are screenshots of the interfaces that the Latin IME provided with the Android platform provides for text and phone number inputs:
Figure 2. Latin IME input types.
When an input field receives focus and your IME starts, the system calls {@link android.inputmethodservice.InputMethodService#onStartInputView(EditorInfo, boolean) onStartInputView()}, passing in an {@link android.view.inputmethod.EditorInfo} object that contains details about the input type and other attributes of the text field. In this object, the {@link android.view.inputmethod.EditorInfo#inputType} field contains the text field's input type.
The {@link android.view.inputmethod.EditorInfo#inputType} field is an int
that contains bit patterns for various input type settings. To test it for the text field's
input type, mask it with the constant {@link android.text.InputType#TYPE_MASK_CLASS}, like
this:
inputType & InputType.TYPE_MASK_CLASS
The input type bit pattern can have one of several values, including:
- {@link android.text.InputType#TYPE_CLASS_NUMBER}
- A text field for entering numbers. As illustrated in the previous screen shot, the Latin IME displays a number pad for fields of this type.
- {@link android.text.InputType#TYPE_CLASS_DATETIME}
- A text field for entering a date and time.
- {@link android.text.InputType#TYPE_CLASS_PHONE}
- A text field for entering telephone numbers.
- {@link android.text.InputType#TYPE_CLASS_TEXT}
- A text field for entering all supported characters.
These constants are described in more detail in the reference documentation for {@link android.text.InputType}.
The {@link android.view.inputmethod.EditorInfo#inputType} field can contain other bits that indicate a variant of the text field type, such as:
- {@link android.text.InputType#TYPE_TEXT_VARIATION_PASSWORD}
- A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering passwords. The input method will display dingbats instead of the actual text.
- {@link android.text.InputType#TYPE_TEXT_VARIATION_URI}
- A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering web URLs and other Uniform Resource Identifiers (URIs).
- {@link android.text.InputType#TYPE_TEXT_FLAG_AUTO_COMPLETE}
- A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering text that the application "auto-completes" from a dictionary, search, or other facility.
Remember to mask {@link android.view.inputmethod.EditorInfo#inputType} with the appropriate constant when you test for these variants. The available mask constants are listed in the reference documentation for {@link android.text.InputType}.
Caution: In your own IME, make sure you handle text correctly when you send it to a password field. Hide the password in your UI both in the input view and in the candidates view. Also remember that you shouldn't store passwords on a device. To learn more, see the Designing for Security guide.
Sending Text to the Application
As the user inputs text with your IME, you can send text to the application by sending individual key events or by editing the text around the cursor in the application's text field. In either case, you use an instance of {@link android.view.inputmethod.InputConnection} to deliver the text. To get this instance, call {@link android.inputmethodservice.InputMethodService#getCurrentInputConnection InputMethodService.getCurrentInputConnection()}.
Editing the text around the cursor
When you're handling the editing of existing text in a text field, some of the more useful methods in {@link android.view.inputmethod.BaseInputConnection} are:
- {@link android.view.inputmethod.BaseInputConnection#getTextBeforeCursor(int, int) getTextBeforeCursor()}
- Returns a {@link java.lang.CharSequence} containing the number of requested characters before the current cursor position.
- {@link android.view.inputmethod.BaseInputConnection#getTextAfterCursor(int, int) getTextAfterCursor()}
- Returns a {@link java.lang.CharSequence} containing the number of requested characters following the current cursor position.
- {@link android.view.inputmethod.BaseInputConnection#deleteSurroundingText(int, int) deleteSurroundingText()}
- Deletes the specified number of characters before and following the current cursor position.
- {@link android.view.inputmethod.BaseInputConnection#commitText(CharSequence, int) commitText()}
- Commit a {@link java.lang.CharSequence} to the text field and set a new cursor position.
For example, the following snippet shows how to replace the four characters to the left of the cursor with the text "Hello!":
InputConnection ic = getCurrentInputConnection();
ic.deleteSurroundingText(4, 0);
ic.commitText("Hello", 1);
ic.commitText("!", 1);
Composing text before committing
If your IME does text prediction or requires multiple steps to compose a glyph or word, you can show the progress in the text field until the user commits the word, and then you can replace the partial composition with the completed text. You may give special treatment to the text by adding a "span" to it when you pass it to {@link android.view.inputmethod.InputConnection#setComposingText setComposingText()}.
The following snippet shows how to show progress in a text field:
InputConnection ic = getCurrentInputConnection();
ic.setComposingText("Composi", 1);
...
ic.setComposingText("Composin", 1);
...
ic.commitText("Composing ", 1);
The following screenshots show how this appears to the user:
Figure 3. Composing text before committing.
Intercepting hardware key events
Even though the input method window doesn't have explicit focus, it receives hardware key events first and can choose to consume them or forward them along to the application. For example, you may want to consume the directional keys to navigate within your UI for candidate selection during composition. You may also want to trap the back key to dismiss any popups originating from the input method window.
To intercept hardware keys, override {@link android.inputmethodservice.InputMethodService#onKeyDown(int, KeyEvent) onKeyDown()} and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}. See the SoftKeyboard sample app for an example.
Remember to call the super() method for keys you don't want to handle yourself.
Creating an IME Subtype
Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A subtype can represent:
- A locale such as en_US or fr_FR
- An input mode such as voice, keyboard, or handwriting
- Other input styles, forms, or properties specific to the IME, such as 10-key or qwerty keyboard layouts.
Basically, the mode can be any text such as "keyboard", "voice", and so forth. A subtype can also expose a combination of these.
Subtype information is used for an IME switcher dialog that's available from the notification bar and also for IME settings. The information also allows the framework to bring up a specific subtype of an IME directly. When you build an IME, use the subtype facility, because it helps the user identify and switch between different IME languages and modes.
You define subtypes in one of the input method's XML resource files, using the
<subtype> element. The following snippet defines an IME with two
subtypes: a keyboard subtype for the US English locale, and another keyboard subtype for the
French language locale for France:
<input-method xmlns:android="http://schemas.android.com/apk/res/android"
android:settingsActivity="com.example.softkeyboard.Settings"
android:icon="@drawable/ime_icon"
<subtype android:name="@string/display_name_english_keyboard_ime"
android:icon="@drawable/subtype_icon_english_keyboard_ime"
android:imeSubtypeLanguage="en_US"
android:imeSubtypeMode="keyboard"
android:imeSubtypeExtraValue="somePrivateOption=true"
/>
<subtype android:name="@string/display_name_french_keyboard_ime"
android:icon="@drawable/subtype_icon_french_keyboard_ime"
android:imeSubtypeLanguage="fr_FR"
android:imeSubtypeMode="keyboard"
android:imeSubtypeExtraValue="foobar=30,someInternalOption=false"
/>
<subtype android:name="@string/display_name_german_keyboard_ime"
...
/>
/>
To ensure that your subtypes are labeled correctly in the UI, use %s to get a subtype label that is the same as the subtype’s locale label. This is demonstrated in the next two snippets. The first snippet shows part of the input method's XML file:
<subtype
android:label="@string/label_subtype_generic"
android:imeSubtypeLocale="en_US"
android:icon="@drawable/icon_en_us"
android:imeSubtypeMode="keyboard" />
The next snippet is part of the IME's strings.xml file. The string
resource label_subtype_generic, which is used by the input method UI definition to
set the subtype's label, is defined as:
<string name="label_subtype_generic">%s</string>
This setting causes the subtype’s display name to match the locale setting. For example, in any English locale, the display name is “English (United States)”.
Choosing IME subtypes from the notification bar
The Android system manages all subtypes exposed by all IMEs. IME subtypes are treated as modes of the IME they belong to. In the notification bar, a user can select an available subtype for the currently-set IME, as shown in the following screenshot:
Figure 4. Choosing an IME subtype from the notification bar.
Figure 5. Setting subtype preferences in System Settings.
Choosing IME subtypes from System Settings
A user can control how subtypes are used in the “Language & input” settings panel in the
System Settings area. In the
SoftKeyboard sample app, the file InputMethodSettingsFragment.java contains an
implementation that facilitates a subtype enabler in the IME settings. Refer to the
SoftKeyboard sample app in the Android SDK for more information about how to support
Input Method Subtypes in your IME.
Figure 6. Choosing a language for the IME.
Switching among IME Subtypes
You can allow users to switch easily among multiple IME subtypes by providing a switching key, such as the globe-shaped language icon, as part of the keyboard. Doing so greatly improves the keyboard's usability, and can help avoid user frustration. To enable such switching, perform the following steps:
- Declare
supportsSwitchingToNextInputMethod = "true"in the input method's XML resource files. Your declaration should look similar to the following snippet:<input-method xmlns:android="http://schemas.android.com/apk/res/android" android:settingsActivity="com.example.softkeyboard.Settings" android:icon="@drawable/ime_icon" android:supportsSwitchingToNextInputMethod="true"> - Call the {@link android.view.inputmethod.InputMethodManager#shouldOfferSwitchingToNextInputMethod shouldOfferSwitchingToNextInputMethod()} method.
- If the method returns true, display a switching key.
- When the user taps the switching key, call {@link android.view.inputmethod.InputMethodManager#switchToNextInputMethod switchToNextInputMethod()}, passing false to the second parameter. A value of false tells the system to treat all subtypes equally, regardless of what IME they belong to. Specifying true requires the system to cycle through subtypes in the current IME.