An input method editor (IME) is a user control that allows users to enter text. Android provides an extensible input method framework that allows apps to provide users with alternative input methods, such as on-screen keyboards or even voice input. After installing the desired IMEs, a user can select which one to use from system settings and use it system-wide; only one IME can be enabled at a time.
To add an IME to the Android system, create an Android application that contains a class that extends InputMethodService. Also, you typically create a “settings” activity that passes options to the IME service. You can also define a configuration user interface that is displayed as part of the system configuration.
This guide covers the following:
- The IME lifecycle
- Declaring IME components in the application manifest
- The IME API
- Designing an IME user interface
- Sending text from an IME to an application
- Working with IME subtypes
If you haven’t worked with IME before, you should first read the introductory article Screen Input Methods.
Note: Starting with Android 11, the platform allows IMEs to display autocomplete suggestions inline, rather than using a dropdown menu. For more information about how autocomplete services can support this functionality, see Integrating autocomplete with keyboards.
The IME Lifecycle
The following diagram describes the lifecycle of an IME:
Figure 1. The life cycle of an IME.
The following sections describe how to implement the user interface and associated code with an IME that follows this lifecycle.
Declaring IME components in the manifest
In the Android system, an IME is an Android application that contains a special IME service. The app’s manifest file must declare the service, request the necessary permissions, provide an intent filter that matches the action.view.InputMethod action, and provide metadata that defines the characteristics of the IME. Additionally, to provide a configuration interface that allows the user to modify the behavior of the IME, you can define a “configure” activity that can be launched from System Configuration.
The following snippet declares an IME service. Request the BIND_INPUT_METHOD permission to allow the service to connect the IME to the system, configure an intent filter that matches the android.view.InputMethod action, and define metadata for the IME:
The following snippet declares the configuration activity for the IME. It has an intent filter for ACTION_MAIN indicating that this activity is the main entry point for the IME application:
You can also provide access to the IME settings directly from its user interface.
The Input Method API
IME-specific classes are found in the android.inputmethodservice and android.view.inputmethod packages. The KeyEvent class is important for handling keyboard characters.
The heart of an IME is a service component, a class that extends InputMethodService. In addition to implementing the normal lifecycle of the service, this class has callbacks to provide the user interface for your IME, handle user input, and send text to the field that currently has focus. By default, the InputMethodService class provides most of the implementation for managing the state and visibility of the IME and communicating with the current input field.
The following classes are also important:
BaseInputConnection Defines the communication channel from an InputMethod to the application that receives its input. You use it to read the text around the cursor, send text to the text box, and send raw key events to the application. Applications should extend this class instead of implementing the base InputConnection interface. KeyboardView An extension to View that renders a keyboard and responds to user input events. The keyboard layout is specified by a Keyboard instance, which you can define in an XML file.
Design the input method UI
There are two main visual elements to an IME: the input view and the leads view >.You only have to implement the elements that are relevant to the input method you are designing.
Input View
The Input View is the user interface where the user enters text in the form of key clicks, handwriting, or gestures. When the IME is displayed for the first time, the system calls the onCreateInputView() callback. In your implementation of this method, you create the layout that you want to display in the IME window and return the layout to the system. This snippet is an example implementation of the onCreateInputView() method:
In this example, MyKeyboardView is an instance of a custom KeyboardView implementation that represents a keyboard.
Candidate View
The candidate view is the user interface where the IME displays possible word corrections or suggestions for the user to select. In the IME lifecycle, the system calls onCreateCandidatesView() when it is ready to display the candidate view. In your implementation of this method, return a layout that displays word suggestions, or return null if you don’t want to display anything. A null response is the default behavior, so you don’t have to implement this if you don’t provide hints.
User Interface Design Considerations
This section describes some specific considerations on the design of the user interface. for IME.
Handle Multiple Screen Sizes
The user interface for your IME should be able to scale for different screen sizes, and it should also handle both landscape and portrait orientations. In non-fullscreen IME mode, leave enough space for the app to display the text field and any associated context, so that the IME doesn’t take up more than half of the screen. In full screen IME mode, this is not a problem.
Handling Different Types of Input
Android text fields allow you to set a specific type of input, such as free-form text, numbers, URLs, email addresses, and search strings. When you implement a new IME, you must detect the input type of each field and provide the appropriate interface for it. However, you don’t have to configure your IME to verify that the user entered valid text for the input type; that is the responsibility of the application that owns the text field.
For example, here are screenshots of the interfaces that Latin IME provided with the Android platform for entering text and phone numbers:
Figure 2. Latin IME input types.
When an input field receives focus and its IME starts, the system calls onStartInputView(), passing an EditorInfo object containing details about the input type and other attributes of the text field. In this object, the inputType field contains the input type of the text field.
The inputType field is an int containing bit patterns for various input type configurations. To test it for the input type of the text field, mask it with the constant TYPE_MASK_CLASS, like this:
The input type bit pattern can have one of several values, including:
TYPE_CLASS_NUMBER A text field for entering numbers. As illustrated in the screenshot above, the Latin IME displays a numeric keypad for fields of this type. TYPE_CLASS_DATETIME A text field to enter a date and time. TYPE_CLASS_PHONE A text field for entering phone numbers. TYPE_CLASS_TEXT A text field to enter all supported characters.
These constants are described in more detail in the InputType reference documentation.
The inputType field may contain other bits that indicate a variant of the text field type, such as:
TYPE_TEXT_VARIATION_PASSWORD A variant of TYPE_CLASS_TEXT for entering passwords. The input method will display dingbats instead of the actual text. TYPE_TEXT_VARIATION_URI A variant of TYPE_CLASS_TEXT for entering web URLs and other Uniform Resource Identifiers (URIs). TYPE_TEXT_FLAG_AUTO_COMPLETE A variant of TYPE_CLASS_TEXT to enter text that the application “autocompletes” from a dictionary, search, or other function.
Remember to mask inputType with the appropriate constant when testing these variants. The available mask constants are listed in the InputType reference documentation.
Caution: In your own IME, be sure to handle text correctly when sending it to a password field. Hide the password in your UI in both entry view and candidate view. Also remember that you should not store passwords on a device. For more information, see the Design for Security guide.
Send Text to App
As the user enters text with their IME, they can send text to the app by sending individual key events or by editing the text around the cursor in the field application text. In either case, it uses an InputConnection instance to deliver the text.To get this instance, call InputMethodService.getCurrentInputConnection().
Edit the text around the cursor
When you handle editing existing text in a text field, some of the most useful methods on BaseInputConnection are:
getTextBeforeCursor () Returns a CharSequence containing the number of characters requested before the current cursor position. getTextAfterCursor() Returns a CharSequence containing the requested number of characters after the current cursor position. deleteSurroundingText() Deletes the specified number of characters before and after the current cursor position. commitText() Commits a CharSequence in the text field and sets 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!”:
Compose text before committing
If your IME makes text predictions or requires multiple steps to compose a glyph or word, it can display the progress in the text field until the user confirms the word, and then it can replace the partial comp with full text. You can give text special treatment by adding a “range” to it when you pass it to setComposingText().
The following snippet shows how to display progress in a text field:
The following screenshots show how this appears to the user:
Figure 3. Write text before confirming.
Intercept hardware key events
Although the input method window has no explicit focus, it does receive hardware key events first and can choose to consume or forward them to the application . For example, you might want to use the directional keys to navigate within your user interface 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 trap hardware keys, override onKeyDown() and onKeyUp().
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 IME-specific properties, such as qwerty or 10-key keyboard layouts.
Basically, the mode can be any text like “keyboard”, “voice”, etc. A subtype can also expose a combination of these.
The subtype information is used for an IME change dialog that is available in the notification bar and also for IME settings. The information also allows the framework to directly display a specific subtype of an IME. When creating an IME, use the subtype feature as it helps the user to identify and switch between different IME modes and languages.
Subtypes are defined in one of the input method’s XML resource files, using the element. The following snippet defines an IME with two subtypes: a keyboard subtype for the US English locale and another keyboard subtype for the France French locale:
To ensure To ensure that your subtypes are tagged correctly ly in the UI, use %s to get a subtype tag that is the same as the subtype’s locale tag. This is demonstrated in the following two fragments. The first snippet shows part of the XML file for the input method:
The following snippet is part of the IME’s strings.xml file. The label_subtype_generic string resource, which uses the input method’s UI definition to set the subtype’s label, is defined as:
%s
This setting causes the subtype to display the name to match the locale. For example, in any English locale, the display name is “English (United States)”.
Choose IME subtypes in the notification bar
The Android system manages all subtypes exposed by all IMEs.IME subtypes are treated as modes of the IME to which they belong. In the notification bar, a user can select an available subtype for the currently configured IME, as shown in the following screenshot:
Figure 4. Choosing a subtype of IME of the notification bar.
Figure 5 Setting subtype preferences in System Settings.
Choose IME subtypes from system settings
A user can control how subtypes are used in the “Language & input” settings panel in the System Settings area.
Figure 6 . Choose a language for the IME.
Switching between IME subtypes
You can allow users to easily switch between various IME subtypes by providing a switch key, such as the globe-shaped language icon, as part of the IME subtype. of the keyboard. Doing so greatly improves keyboard usability and can help prevent user frustration. To enable such a switch, perform the following steps:
- Declare supportSwitchingToNextInputMethod = “true” in the input method XML resource files. Your declaration should look similar to the following snippet:
- Calls the shouldOfferSwitchingToNextInputMethod() method.
- If the method returns true, displays a switch key.
- When the user touches the switch key, call switchToNextInputMethod(), passing false to the second parameter. A false value tells the system to treat all subtypes equally, regardless of which IME they belong to. Specifying true requires the system to step through the subtypes in the current IME.
li>
Caution: prior to Android 5.0 (API level 21), switchToNextInputMethod() is not aware of the supportSwitchingToNextInputMethod attribute. If the user switches to an IME without a switch key, they might get stuck in that IME and not be able to exit it easily.
General IME Considerations
Here’s A few other things to keep in mind as you implement your IME:
- Provide a way for users to set options directly from the IME UI.
- Because multiple IMEs can be installed on the device, provide a way for the user to switch to a different IME directly from the input method UI.
- Display the IME user interface quickly. Preload or load on demand any large asset so that users see the IME as soon as they touch a text field. Cache resources and views for subsequent invocations of the input method.
- Instead, you should free up large memory allocations soon after the input method window is hidden, so that applications can have enough memory to run. Consider using a delayed message to release resources if the IME is hidden for a few seconds.
- Make sure users can enter as many characters as possible for the language or locale associated with the IME. Remember that users can use punctuation in passwords or usernames, so your IME must provide many different characters to allow users to enter a password and gain access to the device.
.