am 093ed383: Merge "DOC CHANGE: IME subtype article" into ics-mr1
* commit '093ed3838c3f2847be1893ea49c6b15b90e0afc3': DOC CHANGE: IME subtype article
This commit is contained in:
Joe Malin
@@ -3,248 +3,526 @@ parent.title=Articles
|
|||||||
parent.link=../browser.html?tag=article
|
parent.link=../browser.html?tag=article
|
||||||
@jd:body
|
@jd:body
|
||||||
|
|
||||||
|
|
||||||
<div id="qv-wrapper">
|
<div id="qv-wrapper">
|
||||||
<div id="qv">
|
<div id="qv">
|
||||||
|
<h2>See also</h2>
|
||||||
<h2>See also</h2>
|
<ol>
|
||||||
<ol>
|
<li>
|
||||||
<li><a href="{@docRoot}resources/articles/on-screen-inputs.html">Onscreen Input Methods</a></li>
|
<a href="{@docRoot}resources/articles/on-screen-inputs.html">Onscreen Input Methods</a>
|
||||||
<li><a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a></li>
|
</li>
|
||||||
</ol>
|
<li>
|
||||||
|
<a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a>
|
||||||
|
</li>
|
||||||
|
</ol>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
<p>
|
||||||
|
An input method editor (IME) is a user control that enables users to enter text. Android
|
||||||
<p>To create an input method (IME) for entering text into text fields
|
provides an extensible input method framework that allows applications to provide users
|
||||||
and other Views, you need to extend the {@link android.inputmethodservice.InputMethodService}.
|
alternative input methods, such as on-screen keyboards or even speech input. Once installed,
|
||||||
class. This class provides much of the basic implementation for an input
|
users can select which IME they want to use from the system settings and use it across the
|
||||||
method, in terms of managing the state and visibility of the input method and
|
entire system; only one IME may be enabled at a time.
|
||||||
communicating with the currently visible activity.</p>
|
</p>
|
||||||
|
<p>
|
||||||
<p>A good starting point would be the SoftKeyboard sample code provided as part
|
To add an IME to the Android system, you create an Android application
|
||||||
of the SDK. You can modify the sample code to start building your own input
|
containing a class that extends {@link android.inputmethodservice.InputMethodService}. In
|
||||||
method.</p>
|
addition, you usually create a "settings" activity that passes options to the IME
|
||||||
|
service. You can also define a settings UI that's displayed as part of the system settings.
|
||||||
<p>An input method is packaged like any other application or service. In the
|
</p>
|
||||||
<code>AndroidManifest.xml</code> file, you declare the input method as a
|
<p>This article covers the following:</p>
|
||||||
service, with the appropriate intent filter and any associated meta data:</p>
|
|
||||||
|
|
||||||
<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android"
|
|
||||||
package="com.example.fastinput">
|
|
||||||
|
|
||||||
<application android:label="@string/app_label"><br>
|
|
||||||
<!-- Declares the input method service -->
|
|
||||||
<service android:name="FastInputIME"
|
|
||||||
android:label="@string/fast_input_label"
|
|
||||||
android:permission="android.permission.BIND_INPUT_METHOD">
|
|
||||||
<intent-filter>
|
|
||||||
<action android:name="android.view.InputMethod" />
|
|
||||||
</intent-filter>
|
|
||||||
<meta-data android:name="android.view.im" android:resource="@xml/method" />
|
|
||||||
</service>
|
|
||||||
|
|
||||||
<!-- Optional activities. A good idea to have some user settings. -->
|
|
||||||
<activity android:name="FastInputIMESettings" android:label="@string/fast_input_settings">
|
|
||||||
<intent-filter>
|
|
||||||
<action android:name="android.intent.action.MAIN"/>
|
|
||||||
</intent-filter>
|
|
||||||
</activity>
|
|
||||||
</application>
|
|
||||||
</manifest></pre>
|
|
||||||
|
|
||||||
<p>If your input method allows the user to tweak some settings, you should
|
|
||||||
provide a settings activity that can be launched from the Settings application.
|
|
||||||
This is optional and you may choose to provide all user settings directly in
|
|
||||||
your IME's UI.</p>
|
|
||||||
|
|
||||||
<p>The typical life-cycle of an <code>InputMethodService</code> looks like
|
|
||||||
this:</p>
|
|
||||||
|
|
||||||
<p><img src="images/ime_003.png" style="border: medium none ; width: 374px; height: 871px;"></p>
|
|
||||||
|
|
||||||
<h3>Visual Elements</h3>
|
|
||||||
|
|
||||||
<p>There are two main visual elements for an input method—the input view and the
|
|
||||||
candidates view. You don't have to follow this style though, if one of them is
|
|
||||||
not relevant to your input method experience.</p>
|
|
||||||
|
|
||||||
<h4>Input View</h4>
|
|
||||||
|
|
||||||
<p>This is where the user can input text either in the form of keypresses,
|
|
||||||
handwriting or other gestures. When the input method is displayed for the first
|
|
||||||
time, <code>InputMethodService.onCreateInputView()</code> will be called. Create
|
|
||||||
and return the view hierarchy that you would like to display in the input method
|
|
||||||
window.</p>
|
|
||||||
|
|
||||||
<h4>Candidates View</h4>
|
|
||||||
|
|
||||||
<p>This is where potential word corrections or completions are presented to the
|
|
||||||
user for selection. Again, this may or may not be relevant to your input method
|
|
||||||
and you can return <code>null</code> from calls to
|
|
||||||
<code>InputMethodService.onCreateCandidatesView()</code>, which is the default
|
|
||||||
behavior.</p>
|
|
||||||
|
|
||||||
<h3>Designing for the different Input Types</h3>
|
|
||||||
|
|
||||||
<p>An application's text fields can have different input types specified on
|
|
||||||
them, such as free form text, numeric, URL, email address and search. When you
|
|
||||||
implement a new input method, you need to be aware of the different input types.
|
|
||||||
Input methods are not automatically switched for different input types and so
|
|
||||||
you need to support all types in your IME. However, the IME is not responsible
|
|
||||||
for validating the input sent to the application. That's the responsibility of
|
|
||||||
the application.</p>
|
|
||||||
|
|
||||||
<p>For example, the LatinIME provided with the Android platform provides
|
|
||||||
different layouts for text and phone number entry:</p>
|
|
||||||
|
|
||||||
<p><img style="margin: 0pt 10px 0pt 0pt; width: 319px; height: 198px;" src="images/ime_002.png"><img style="width: 320px; height: 199px;" src="images/ime.png"></p>
|
|
||||||
|
|
||||||
<p><code>InputMethodService.onStartInputView()</code> is called with an<code>
|
|
||||||
EditorInfo</code> object that contains details about the input type and other
|
|
||||||
attributes of the application's text field.</p><p>(<code>EditorInfo.inputType
|
|
||||||
& EditorInfo.TYPE_CLASS_MASK</code>) can be one of many different values,
|
|
||||||
including:</p>
|
|
||||||
|
|
||||||
<ul>
|
<ul>
|
||||||
<li><code>TYPE_CLASS_NUMBER</code></li>
|
<li>The IME lifecycle.</li>
|
||||||
<li><code>TYPE_CLASS_DATETIME</code></li>
|
<li>Declaring IME components in the application manifest.</li>
|
||||||
<li><code>TYPE_CLASS_PHONE</code></li>
|
<li>The IME API.</li>
|
||||||
<li><code>TYPE_CLASS_TEXT</code></li>
|
<li>Designing an IME UI.</li>
|
||||||
|
<li>Sending text from an IME to an application.</li>
|
||||||
|
<li>Working with IME subtypes.</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
<p>
|
||||||
|
If you haven't worked with IMEs before, you should read the introductory article
|
||||||
|
<a href="{@docRoot}resources/articles/on-screen-inputs.html">Onscreen Input Methods</a> first.
|
||||||
|
Also, the Soft Keyboard sample app included in the SDK contains sample code that you can modify
|
||||||
|
to start building your own IME.
|
||||||
|
</p>
|
||||||
|
<h2 id="InputMethodLifecycle">The IME Lifecycle</h2>
|
||||||
|
<p>
|
||||||
|
The following diagram describes the life cycle of an IME:
|
||||||
|
</p>
|
||||||
|
<img src="{@docRoot}resources/articles/images/inputmethod_lifecycle_image.png" alt="" height="845"
|
||||||
|
id="figure1" />
|
||||||
|
<p class="img-caption">
|
||||||
|
<strong>Figure 1.</strong> The life cycle of an IME.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The following sections describe how to implement the UI and code associated with an IME that
|
||||||
|
follows this lifecycle.
|
||||||
|
</p>
|
||||||
|
<h2 id="DefiningIME">Declaring IME Components in the Manifest</h2>
|
||||||
|
<p>
|
||||||
|
In the Android system, an IME is an Android application that contains a special IME service.
|
||||||
|
The application's manifest file must declare the service, request the necessary permissions,
|
||||||
|
provide an intent filter that matches the action <code>action.view.InputMethod</code>, and
|
||||||
|
provide metadata that defines characteristics of the IME. In addition, to provide a settings
|
||||||
|
interface that allows the user to modify the behavior of the IME, you can define a "settings"
|
||||||
|
activity that can be launched from System Settings.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The following snippet declares IME service. It requests the permission {@link
|
||||||
|
android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to connect the IME to
|
||||||
|
the system, sets up an intent filter that matches the action
|
||||||
|
<code>android.view.InputMethod</code>, and defines metadata for the IME:
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
<!-- Declares the input method service -->
|
||||||
|
<service android:name="FastInputIME"
|
||||||
|
android:label="@string/fast_input_label"
|
||||||
|
android:permission="android.permission.BIND_INPUT_METHOD">
|
||||||
|
<intent-filter>
|
||||||
|
<action android:name="android.view.InputMethod" />
|
||||||
|
</intent-filter>
|
||||||
|
<meta-data android:name="android.view.im" android:resource="@xml/method" />
|
||||||
|
</service>
|
||||||
|
</pre>
|
||||||
|
<p>
|
||||||
|
This next snippet declares the settings activity for the IME. It has an intent filter for
|
||||||
|
{@link android.content.Intent#ACTION_MAIN} that indicates this activity is the main entry point
|
||||||
|
for the IME application:</p>
|
||||||
|
<pre>
|
||||||
|
<!-- Optional: an activity for controlling the IME settings -->
|
||||||
|
<activity android:name="FastInputIMESettings"
|
||||||
|
android:label="@string/fast_input_settings">
|
||||||
|
<intent-filter>
|
||||||
|
<action android:name="android.intent.action.MAIN"/>
|
||||||
|
</intent-filter>
|
||||||
|
</activity>
|
||||||
|
</pre>
|
||||||
|
<p>
|
||||||
|
You can also provide access to the IME's settings directly from its UI.
|
||||||
|
</p>
|
||||||
|
<h2 id="IMEAPI">The Input Method API</h2>
|
||||||
|
<p>
|
||||||
|
Classes specific to IMEs are found in the {@link android.inputmethodservice} and {@link
|
||||||
|
android.view.inputmethod} packages. The {@link android.view.KeyEvent} class is important for
|
||||||
|
handling keyboard characters.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The central part of an IME is a service component, a class that extends
|
||||||
|
{@link android.inputmethodservice.InputMethodService}. In addition to implementing the
|
||||||
|
normal service lifecycle, this class has callbacks for providing your IME's UI, handling user
|
||||||
|
input, and delivering text to the field that currently has focus. By default, the
|
||||||
|
{@link android.inputmethodservice.InputMethodService} class provides most of the implementation
|
||||||
|
for managing the state and visibility of the IME and communicating with the current
|
||||||
|
input field.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The following classes are also important:
|
||||||
|
</p>
|
||||||
|
<dl>
|
||||||
|
<dt>{@link android.view.inputmethod.BaseInputConnection}</dt>
|
||||||
|
<dd>
|
||||||
|
Defines the communication channel from an {@link android.view.inputmethod.InputMethod}
|
||||||
|
back to the application that is receiving its input. You use it to read text around the
|
||||||
|
cursor, commit text to the text box, and send raw key events to the application.
|
||||||
|
Applications should extend this class rather than implementing the base interface
|
||||||
|
{@link android.view.inputmethod.InputConnection}.
|
||||||
|
</dd>
|
||||||
|
<dt>{@link android.inputmethodservice.KeyboardView}</dt>
|
||||||
|
<dd>
|
||||||
|
An extension of {@link android.view.View} that renders a keyboard and responds to user
|
||||||
|
input events. The keyboard layout is specified by an instance of
|
||||||
|
{@link android.inputmethodservice.Keyboard}, which you can define in an XML file.
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
<h2 id="IMEUI">Designing the Input Method UI</h2>
|
||||||
|
<p>
|
||||||
|
There are two main visual elements for an IME: the <strong>input</strong> view and the
|
||||||
|
<strong>candidates</strong> view. You only have to implement the elements that are relevant to
|
||||||
|
the input method you're designing.
|
||||||
|
</p>
|
||||||
|
<h3 id="InputView">Input view</h3>
|
||||||
|
<p>
|
||||||
|
The input view is the UI where the user inputs text, in the form of keyclicks, handwriting or
|
||||||
|
gestures. When the iIME is displayed for the first time, the system calls the
|
||||||
|
{@link android.inputmethodservice.InputMethodService#onCreateInputView()} callback. In your
|
||||||
|
implementation of this method, you create the layout you want to display in the IME
|
||||||
|
window and return the layout to the system. This snippet is an example of implementing the
|
||||||
|
{@link android.inputmethodservice.InputMethodService#onCreateInputView()} method:
|
||||||
|
<pre>
|
||||||
|
@Override
|
||||||
|
public View onCreateInputView() {
|
||||||
|
MyKeyboardView inputView =
|
||||||
|
(MyKeyboardView) getLayoutInflater().inflate( R.layout.input, null);
|
||||||
|
|
||||||
|
inputView.setOnKeyboardActionListener(this); inputView.setKeyboard(mLatinKeyboard);
|
||||||
|
|
||||||
|
return mInputView;
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
<p>
|
||||||
|
In this example, {@code MyKeyboardView} is an instance of a custom implementation of
|
||||||
|
{@link android.inputmethodservice.KeyboardView} that renders a
|
||||||
|
{@link android.inputmethodservice.Keyboard}. If you’re building a traditional QWERTY keyboard,
|
||||||
|
see the <a href=”{@docRoot}resources/samples/SoftKeyboard/index.html”>Soft Keyboard</a> sample
|
||||||
|
app for an example of how to extend the {@link android.inputmethodservice.KeyboardView} class.
|
||||||
|
</p>
|
||||||
|
<h3 id="CandidateView">Candidates view</h3>
|
||||||
|
<p>
|
||||||
|
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 candidate 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).</p>
|
||||||
|
<p>
|
||||||
|
For an example implementation that provides user suggestions, see the
|
||||||
|
<a href=”{@docRoot}resources/samples/SoftKeyboard/index.html”>Soft Keyboard</a> sample app.
|
||||||
|
</p>
|
||||||
|
<h3 id="DesignConsiderations">UI design considerations</h3>
|
||||||
|
<p>
|
||||||
|
This section describes some specific UI design considerations for IMEs.
|
||||||
|
</p>
|
||||||
|
<h4>Handling multiple screen sizes</h4>
|
||||||
|
<p>
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
<h4>Handling different input types</h4>
|
||||||
|
<p>
|
||||||
|
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 that's valid for the
|
||||||
|
input type; that's the responsibility of the application that owns the text field.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
For example, here are screenshots of the interfaces that the Latin IME provided with the
|
||||||
|
Android platform provides for text and phone number inputs:
|
||||||
|
</p>
|
||||||
|
<img src="{@docRoot}resources/articles/images/inputmethod_text_type_screenshot.png" alt=""
|
||||||
|
height="142" id="figure2" />
|
||||||
|
<img src="{@docRoot}resources/articles/images/inputmethod_numeric_type_screenshot.png" alt=""
|
||||||
|
height="120" id="figure2a" />
|
||||||
|
<p class="img-caption">
|
||||||
|
<strong>Figure 2.</strong> Latin IME input types.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The {@link android.view.inputmethod.EditorInfo#inputType} field is an <code>int</code>
|
||||||
|
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:
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
inputType & InputType.TYPE_MASK_CLASS
|
||||||
|
</pre>
|
||||||
|
<p>
|
||||||
|
The input type bit pattern can have one of several values, including:
|
||||||
|
</p>
|
||||||
|
<dl>
|
||||||
|
<dt>{@link android.text.InputType#TYPE_CLASS_NUMBER}</dt>
|
||||||
|
<dd>
|
||||||
|
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.
|
||||||
|
</dd>
|
||||||
|
<dt>{@link android.text.InputType#TYPE_CLASS_DATETIME}</dt>
|
||||||
|
<dd>
|
||||||
|
A text field for entering a date and time.
|
||||||
|
</dd>
|
||||||
|
<dt>{@link android.text.InputType#TYPE_CLASS_PHONE}</dt>
|
||||||
|
<dd>
|
||||||
|
A text field for entering telephone numbers.
|
||||||
|
</dd>
|
||||||
|
<dt>{@link android.text.InputType#TYPE_CLASS_TEXT}</dt>
|
||||||
|
<dd>
|
||||||
|
A text field for entering all supported characters.
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
<p>
|
||||||
|
These constants are described in more detail in the reference documentation for
|
||||||
|
{@link android.text.InputType}.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The {@link android.view.inputmethod.EditorInfo#inputType} field can contain other bits that
|
||||||
|
indicate a variant of the text field type, such as:
|
||||||
|
</p>
|
||||||
|
<dl>
|
||||||
|
<dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_PASSWORD}</dt>
|
||||||
|
<dd>
|
||||||
|
A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering passwords. The
|
||||||
|
input method will display dingbats instead of the actual text.
|
||||||
|
</dd>
|
||||||
|
<dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_URI}</dt>
|
||||||
|
<dd>
|
||||||
|
A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering web URLs and
|
||||||
|
other Uniform Resource Identifiers (URIs).
|
||||||
|
</dd>
|
||||||
|
<dt>{@link android.text.InputType#TYPE_TEXT_FLAG_AUTO_COMPLETE}</dt>
|
||||||
|
<dd>
|
||||||
|
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.
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
<p>
|
||||||
|
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}.
|
||||||
|
</p>
|
||||||
|
<p class="caution">
|
||||||
|
<strong>Caution:</strong> 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 <a
|
||||||
|
href="{@docRoot}guide/practices/security.html">Designing for Security</a> guide.
|
||||||
|
</p>
|
||||||
|
<h2 id="SendText">Sending Text to the Application</h2>
|
||||||
|
<p>
|
||||||
|
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()}.
|
||||||
|
</p>
|
||||||
|
<h3 id="EditingCursor">Editing the text around the cursor</h3>
|
||||||
|
<p>
|
||||||
|
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:
|
||||||
|
</p>
|
||||||
|
<dl>
|
||||||
|
<dt>
|
||||||
|
{@link android.view.inputmethod.BaseInputConnection#getTextBeforeCursor(int, int)
|
||||||
|
getTextBeforeCursor()}</dt>
|
||||||
|
<dd>
|
||||||
|
Returns a {@link java.lang.CharSequence} containing the number of requested characters
|
||||||
|
before the current cursor position.
|
||||||
|
</dd>
|
||||||
|
<dt>
|
||||||
|
{@link android.view.inputmethod.BaseInputConnection#getTextAfterCursor(int, int)
|
||||||
|
getTextAfterCursor()}
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
Returns a {@link java.lang.CharSequence} containing the number of requested characters
|
||||||
|
following the current cursor position.
|
||||||
|
</dd>
|
||||||
|
<dt>
|
||||||
|
{@link android.view.inputmethod.BaseInputConnection#deleteSurroundingText(int, int)
|
||||||
|
deleteSurroundingText()}
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
Deletes the specified number of characters before and following the current cursor
|
||||||
|
position.
|
||||||
|
</dd>
|
||||||
|
<dt>
|
||||||
|
{@link android.view.inputmethod.BaseInputConnection#commitText(CharSequence, int)
|
||||||
|
commitText()}
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
Commit a {@link java.lang.CharSequence} to the text field and set a new cursor
|
||||||
|
position.
|
||||||
|
</dd>
|
||||||
|
</dl>
|
||||||
|
<p>
|
||||||
|
For example, the following snippet shows how to replace the text "Fell" to the left of the
|
||||||
|
with the text "Hello!":
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
InputConnection ic = getCurrentInputConnection();
|
||||||
|
|
||||||
|
ic.deleteSurroundingText(4, 0);
|
||||||
|
|
||||||
|
ic.commitText("Hello", 1);
|
||||||
|
|
||||||
|
ic.commitText("!", 1);
|
||||||
|
</pre>
|
||||||
|
<h3 id="ComposeThenCommit">Composing text before committing</h3>
|
||||||
|
<p>
|
||||||
|
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 InputConnection#setComposingText().
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The following snippet shows how to show progress in a text field:
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
InputConnection ic = getCurrentInputConnection();
|
||||||
|
|
||||||
<p>See <code>android.text.InputType</code> for more details.</p>
|
ic.setComposingText("Composi", 1);
|
||||||
|
|
||||||
<p><code>EditorInfo.inputType</code> can contain other masked bits that
|
|
||||||
indicate the class variation and other flags. For example,
|
|
||||||
<code>TYPE_TEXT_VARIATION_PASSWORD</code> or <code>TYPE_TEXT_VARIATION_URI</code>
|
|
||||||
or <code>TYPE_TEXT_FLAG_AUTO_COMPLETE</code>.</p>
|
|
||||||
|
|
||||||
<h4>Password fields</h4>
|
|
||||||
|
|
||||||
<p>Pay
|
|
||||||
specific attention when sending text to password fields. Make sure that
|
|
||||||
the password is not visible within your UI — neither in the input
|
|
||||||
view or the candidates view. Also, do not save the password anywhere without
|
|
||||||
explicitly informing the user.</p>
|
|
||||||
|
|
||||||
<h3>Landscape vs. portrait</h3>
|
|
||||||
|
|
||||||
<p>The UI needs to be able to scale between landscape and portrait orientations.
|
|
||||||
In non-fullscreen IME mode, leave sufficient space for the application to show
|
|
||||||
the text field and any associated context. Preferably, no more than half the
|
|
||||||
screen should be occupied by the IME. In fullscreen IME mode this is not an
|
|
||||||
issue.</p>
|
|
||||||
|
|
||||||
<h3>Sending text to the application</h3>
|
|
||||||
|
|
||||||
<p>There are two ways to send text to the application. You can either send
|
|
||||||
individual key events or you can edit the text around the cursor in the
|
|
||||||
application's text field.</p>
|
|
||||||
|
|
||||||
<p>To send a key event, you can simply construct KeyEvent objects and call
|
|
||||||
<code>InputConnection.sendKeyEvent()</code>. Here are some examples:</p>
|
|
||||||
|
|
||||||
<pre>InputConnection ic = getCurrentInputConnection();
|
|
||||||
long eventTime = SystemClock.uptimeMillis();
|
|
||||||
ic.sendKeyEvent(new KeyEvent(eventTime, eventTime,
|
|
||||||
KeyEvent.ACTION_DOWN, keyEventCode, 0, 0, 0, 0,
|
|
||||||
KeyEvent.FLAG_SOFT_KEYBOARD|KeyEvent.FLAG_KEEP_TOUCH_MODE));
|
|
||||||
ic.sendKeyEvent(new KeyEvent(SystemClock.uptimeMillis(), eventTime,
|
|
||||||
KeyEvent.ACTION_UP, keyEventCode, 0, 0, 0, 0,
|
|
||||||
KeyEvent.FLAG_SOFT_KEYBOARD|KeyEvent.FLAG_KEEP_TOUCH_MODE));</pre>
|
|
||||||
|
|
||||||
<p>Or use the convenience method:</p>
|
|
||||||
|
|
||||||
<pre>InputMethodService.sendDownUpKeyEvents(keyEventCode);</pre>
|
|
||||||
|
|
||||||
<p class="note"><strong>Note</strong>:
|
|
||||||
It is recommended to use the above method for certain fields such as
|
|
||||||
phone number fields because of filters that may be applied to the text
|
|
||||||
after each key press. Return key and delete key should also be sent as
|
|
||||||
raw key events for certain input types, as applications may be watching
|
|
||||||
for specific key events in order to perform an action.</p>
|
|
||||||
|
|
||||||
<p>When editing text in a text field, some of the more useful methods on
|
|
||||||
<code>android.view.inputmethod.InputConnection</code> are:</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li><code>getTextBeforeCursor()</code></li>
|
|
||||||
<li><code>getTextAfterCursor()</code></li>
|
|
||||||
<li><code>deleteSurroundingText()</code></li>
|
|
||||||
<li><code>commitText()</code></li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p>For example, let's say the text "Fell" is to the left of the cursor
|
|
||||||
and you want to replace it with "Hello!":</p>
|
|
||||||
|
|
||||||
<pre>InputConnection ic = getCurrentInputConnection();
|
|
||||||
ic.deleteSurroundingText(4, 0);
|
|
||||||
ic.commitText("Hello", 1);
|
|
||||||
ic.commitText("!", 1);</pre>
|
|
||||||
|
|
||||||
<h4>Composing text before committing</h4>
|
|
||||||
|
|
||||||
<p>If your input method does some kind of text prediction or requires multiple
|
|
||||||
steps to compose a word or glyph, 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. The text that is being composed will be highlighted in
|
|
||||||
the text field in some fashion, such as an underline.</p>
|
|
||||||
|
|
||||||
<pre>InputConnection ic = getCurrentInputConnection();
|
|
||||||
ic.setComposingText("Composi", 1);
|
|
||||||
...
|
...
|
||||||
ic.setComposingText("Composin", 1);
|
|
||||||
|
ic.setComposingText("Composin", 1);
|
||||||
|
|
||||||
...
|
...
|
||||||
ic.commitText("Composing ", 1);</pre>
|
|
||||||
|
|
||||||
<p><img style="width: 320px; height: 98px; margin-bottom: 10px;" src="images/ime_006.png">
|
|
||||||
<img style="width: 320px; height: 97px; margin-bottom: 10px;" src="images/ime_005.png">
|
|
||||||
<img style="width: 320px; height: 97px;" src="images/ime_004.png"></p>
|
|
||||||
|
|
||||||
<h3>Intercepting hard key events</h3>
|
|
||||||
|
|
||||||
<p>Even though the input method window doesn't have explicit focus, it receives
|
|
||||||
hard key events first and can choose to consume them or forward them along to
|
|
||||||
the application. For instance, you may want to consume the directional keys to
|
|
||||||
navigate within your UI for candidate selection during composition. Or you may
|
|
||||||
want to trap the back key to dismiss any popups originating from the input
|
|
||||||
method window. To intercept hard keys, override
|
|
||||||
<code>InputMethodService.onKeyDown()</code> and
|
|
||||||
<code>InputMethodService.onKeyUp().</code> Remember to call
|
|
||||||
<code>super.onKey</code>* if you don't want to consume a certain key
|
|
||||||
yourself.</p>
|
|
||||||
|
|
||||||
<h3>Other considerations</h3>
|
|
||||||
|
|
||||||
|
ic.commitText("Composing ", 1);
|
||||||
|
</pre>
|
||||||
|
<p>
|
||||||
|
The following screenshots show how this appears to the user:
|
||||||
|
</p>
|
||||||
|
<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_1.png" alt="" height="54"
|
||||||
|
id="figure3a" />
|
||||||
|
<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_2.png" alt="" height="53"
|
||||||
|
id="figure3b" />
|
||||||
|
<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_3.png" alt="" height="31"
|
||||||
|
id="figure3c" />
|
||||||
|
<p class="img-caption">
|
||||||
|
<strong>Figure 3.</strong> Composing text before committing.
|
||||||
|
</p>
|
||||||
|
<h3 id="HardwareKeyEvents">Intercepting hardware key events</h3>
|
||||||
|
<p>
|
||||||
|
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.</p>
|
||||||
|
<p>
|
||||||
|
To intercept hardware keys, override
|
||||||
|
{@link android.inputmethodservice.InputMethodService#onKeyDown(int, KeyEvent) onKeyDown()}
|
||||||
|
and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}.
|
||||||
|
See the <a href=”{@docRoot}resources/samples/SoftKeyboard/index.html”>Soft Keyboard</a> sample
|
||||||
|
app for an example.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Remember to call the <code>super()</code> method for keys you don't want to handle yourself.
|
||||||
|
</p>
|
||||||
|
<h2 id="IMESubTypes">Creating an IME Subtype</h2>
|
||||||
|
<p>
|
||||||
|
Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A
|
||||||
|
subtype can represent:
|
||||||
|
</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Provide a way for the user to easily bring up any associated settings
|
<li>A locale such as en_US or fr_FR</li>
|
||||||
directly from the input method UI</li>
|
<li>An input mode such as voice, keyboard, or handwriting</li>
|
||||||
<li>Provide
|
<li>
|
||||||
a way for the user to switch to a different input method (multiple
|
Other input styles, forms, or properties specific to the IME, such as 10-key or qwerty
|
||||||
input methods may be installed) directly from the input method UI.</li>
|
keyboard layouts.
|
||||||
<li>Bring
|
</li>
|
||||||
up the UI quickly - preload or lazy-load any large resources so that
|
</ul>
|
||||||
the user sees the input method quickly on tapping on a text field. And
|
<p>
|
||||||
cache any resources and views for subsequent invocations of the input
|
Basically, the mode can be any text such as "keyboard", "voice", and so forth.
|
||||||
method.</li>
|
</p>
|
||||||
<li>On the flip side, any large memory allocations should
|
<p>A subtype can also expose a combination of these.</p>
|
||||||
be released soon after the input method window is hidden so that
|
<p>
|
||||||
applications can have sufficient memory to run. Consider using a
|
Subtype information is used for an IME switcher dialog that's available from the notification
|
||||||
delayed message to release resources if the input method is in a hidden
|
bar and also for IME settings. The information also allows the framework to bring up a
|
||||||
state for a few seconds.</li>
|
specific subtype of an IME directly. When you build an IME, use the subtype facility, because
|
||||||
<li>Make sure that most common characters
|
it helps the user identify and switch between different IME languages and modes.
|
||||||
can be entered using the input method, as users may use punctuation in
|
</p>
|
||||||
passwords or user names and they shouldn't be stuck in a situation
|
<p>
|
||||||
where they can't enter a certain character in order to gain access into
|
You define subtypes in one of the input method's XML resource files, using the
|
||||||
a password-locked device.</li>
|
<code><subtype></code> 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:
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
<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"
|
||||||
|
...
|
||||||
|
/>
|
||||||
|
/>
|
||||||
|
</pre>
|
||||||
|
<p>
|
||||||
|
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:
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
<subtype
|
||||||
|
android:label="@string/label_subtype_generic"
|
||||||
|
android:imeSubtypeLocale="en_US"
|
||||||
|
android:icon="@drawable/icon_en_us"
|
||||||
|
android:imeSubtypeMode="keyboard" />
|
||||||
|
</pre>
|
||||||
|
<p>
|
||||||
|
The next snippet is part of the IME's <code>strings.xml</code> file. The string
|
||||||
|
resource <code>label_subtype_generic</code>, which is used by the input method UI definition to
|
||||||
|
set the subtype's label, is defined as:
|
||||||
|
</p>
|
||||||
|
<pre>
|
||||||
|
<string name="label_subtype_generic">%s</string>
|
||||||
|
</pre>
|
||||||
|
<p>
|
||||||
|
This sets the subtype’s display name to “English (United States)” in any English language
|
||||||
|
locale, or to the appropriate localization in other locales.
|
||||||
|
</p>
|
||||||
|
<h3 id="SubtypeProcessing">Choosing IME subtypes from the notification bar</h3>
|
||||||
|
<p>
|
||||||
|
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:
|
||||||
|
</p>
|
||||||
|
<img src="{@docRoot}resources/articles/images/inputmethod_subtype_notification.png" alt=""
|
||||||
|
height="85" id="figure4" />
|
||||||
|
<p class="img-caption">
|
||||||
|
<strong>Figure 4.</strong> Choosing an IME subtype from the notification bar.
|
||||||
|
</p>
|
||||||
|
<img src="{@docRoot}resources/articles/images/inputmethod_subtype_preferences.png" alt=""
|
||||||
|
height="165" id="figure5" />
|
||||||
|
<p class="img-caption">
|
||||||
|
<strong>Figure 5.</strong> Setting subtype preferences in System Settings.
|
||||||
|
</p>
|
||||||
|
<h3 id="SubtypeSettings">Choosing IME subtypes from System Settings</h3>
|
||||||
|
<p>
|
||||||
|
A user can control how subtypes are used in the “Language & input” settings panel in the
|
||||||
|
System Settings area. In the Soft Keyboard sample, the file
|
||||||
|
<code>InputMethodSettingsFragment.java</code> contains an implementation that
|
||||||
|
facilitates a subtype enabler in the IME settings. Please refer to the SoftKeyboard sample in
|
||||||
|
the Android SDK for more information about how to support Input Method Subtypes in your IME.
|
||||||
|
</p>
|
||||||
|
<img src="{@docRoot}resources/articles/images/inputmethod_subtype_settings.png" alt=""
|
||||||
|
height="210" id="figure6" />
|
||||||
|
<p class="img-caption">
|
||||||
|
<strong>Figure 6.</strong> Choosing a language for the IME.
|
||||||
|
</p>
|
||||||
|
<h2 id="GeneralDesign">General IME Considerations</h2>
|
||||||
|
<p>
|
||||||
|
Here are some other things to consider as you're implementing your IME:
|
||||||
|
</p>
|
||||||
|
<ul>
|
||||||
|
<li>
|
||||||
|
Provide a way for users to set options directly from the IME's UI.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
Because multiple IMEs may be installed on the device, provide a way for the user to switch to a
|
||||||
|
different IME directly from the input method UI.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
Bring up the IME's UI quickly. Preload or load on demand any large resources so that users
|
||||||
|
see the IME as soon as they tap on a text field. Cache resources and views for subsequent
|
||||||
|
invocations of the input method.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
Conversely, you should release large memory allocations soon after the input method window is
|
||||||
|
hidden, so that applications can have sufficient memory to run. Consider using a delayed message
|
||||||
|
to release resources if the IME is in a hidden state for a few seconds.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
Make sure that users can enter as many characters as possible for the language or locale
|
||||||
|
associated with the IME. Remember that users may use punctuation in passwords or user
|
||||||
|
names, so your IME has to provide many different characters to allow users to enter a
|
||||||
|
password and get access to the device.
|
||||||
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
<h3>Samples</h3>
|
|
||||||
|
|
||||||
<p>For a real world example, with support for multiple input types and text
|
|
||||||
prediction, see the <a id="ccpb"
|
|
||||||
href="http://android.git.kernel.org/?p=platform/packages/inputmethods/LatinIME.
|
|
||||||
git;a=tree" title="LatinIME source code online">LatinIME source code</a>. The
|
|
||||||
Android SDK also includes a SoftKeyboard sample as well.</p>
|
|
||||||
|
|||||||
Binary file not shown.
|
After Width: | Height: | Size: 5.4 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.3 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.8 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 87 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Reference in New Issue
Block a user