Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Added an "In This Document" nav list at top-right of page, and deleted corresponding text from body." into klp-modular-docs

Browse Source
This commit is contained in:
David Friedman
2014-07-22 20:42:05 +00:00
committed by Android (Google) Code Review
parent 40b5d8a0e5 86efa014fc
commit 170b09535d
1 changed files with 90 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
docs/html/guide/topics/text/creating-input-method.jd
View File

@@ -4,6 +4,30 @@ page.tags="ime","keyboard","inputmethodservice"
<div id="qv-wrapper"> <div id="qv-wrapper">
<div id="qv"> <div id="qv">
<h2>In This Document</h2>
<ol>
<li>
<a href="#InputMethodLifecycle">The IME Lifecycle</a>
</li>
<li>
<a href="#DefiningIME">Declaring IME Components in the Manifest</a>
</li>
<li>
<a href="#IMEAPI">The Input Method API</a>
</li>
<li>
<a href="#IMEUI">Designing the Input Method UI</a>
</li>
<li>
<a href="#SendText">Sending Text to the Application</a>
</li>
<li>
<a href="#IMESubTypes">Creating an IME Subtype</a>
</li>
<li>
<a href="#GeneralDesign">General IME Considerations</a>
</li>
</ol>
<h2>See also</h2> <h2>See also</h2>
<ol> <ol>
<li> <li>
@@ -16,29 +40,20 @@ page.tags="ime","keyboard","inputmethodservice"
</div> </div>
</div> </div>
<p> <p>
An input method editor (IME) is a user control that enables users to enter text. Android An input method editor (IME) is a user control that enables users to enter text. Android
provides an extensible input method framework that allows applications to provide users provides an extensible input method framework that allows applications to provide users
alternative input methods, such as on-screen keyboards or even speech input. Once installed, alternative input methods, such as on-screen keyboards or even speech input. Once installed,
users can select which IME they want to use from the system settings and use it across the users can select which IME they want to use from the system settings and use it across the
entire system; only one IME may be enabled at a time. entire system; only one IME may be enabled at a time.
</p> </p>
<p> <p>
To add an IME to the Android system, you create an Android application To add an IME to the Android system, you create an Android application
containing a class that extends {@link android.inputmethodservice.InputMethodService}. In containing a class that extends {@link android.inputmethodservice.InputMethodService}. In
addition, you usually create a "settings" activity that passes options to the IME 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. service. You can also define a settings UI that's displayed as part of the system settings.
</p> </p>
<p>This article covers the following:</p>
<ul>
<li>The IME lifecycle.</li>
<li>Declaring IME components in the application manifest.</li>
<li>The IME API.</li>
<li>Designing an IME UI.</li>
<li>Sending text from an IME to an application.</li>
<li>Working with IME subtypes.</li>
</ul>
<p> <p>
If you haven't worked with IMEs before, you should read the introductory article If you haven't worked with IMEs before, you should read the introductory article
<a href="http://android-developers.blogspot.com/2009/04/updating-applications-for-on-screen.html">Onscreen Input Methods</a> first. <a href="http://android-developers.blogspot.com/2009/04/updating-applications-for-on-screen.html">Onscreen Input Methods</a> first.
Also, the Soft Keyboard sample app included in the SDK contains sample code that you can modify Also, the Soft Keyboard sample app included in the SDK contains sample code that you can modify
to start building your own IME. to start building your own IME.
@@ -59,16 +74,16 @@ page.tags="ime","keyboard","inputmethodservice"
<h2 id="DefiningIME">Declaring IME Components in the Manifest</h2> <h2 id="DefiningIME">Declaring IME Components in the Manifest</h2>
<p> <p>
In the Android system, an IME is an Android application that contains a special IME service. 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, 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 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 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" 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. activity that can be launched from System Settings.
</p> </p>
<p> <p>
The following snippet declares IME service. It requests the permission {@link 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 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 the system, sets up an intent filter that matches the action
<code>android.view.InputMethod</code>, and defines metadata for the IME: <code>android.view.InputMethod</code>, and defines metadata for the IME:
</p> </p>
<pre> <pre>
@@ -88,7 +103,7 @@ page.tags="ime","keyboard","inputmethodservice"
for the IME application:</p> for the IME application:</p>
<pre> <pre>
&lt;!-- Optional: an activity for controlling the IME settings --&gt; &lt;!-- Optional: an activity for controlling the IME settings --&gt;
&lt;activity android:name="FastInputIMESettings" &lt;activity android:name="FastInputIMESettings"
android:label="&#64;string/fast_input_settings"&gt; android:label="&#64;string/fast_input_settings"&gt;
&lt;intent-filter&gt; &lt;intent-filter&gt;
&lt;action android:name="android.intent.action.MAIN"/&gt; &lt;action android:name="android.intent.action.MAIN"/&gt;
@@ -105,12 +120,12 @@ page.tags="ime","keyboard","inputmethodservice"
handling keyboard characters. handling keyboard characters.
</p> </p>
<p> <p>
The central part of an IME is a service component, a class that extends The central part of an IME is a service component, a class that extends
{@link android.inputmethodservice.InputMethodService}. In addition to implementing the {@link android.inputmethodservice.InputMethodService}. In addition to implementing the
normal service lifecycle, this class has callbacks for providing your IME's UI, handling user 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 input, and delivering text to the field that currently has focus. By default, the
{@link android.inputmethodservice.InputMethodService} class provides most of the implementation {@link android.inputmethodservice.InputMethodService} class provides most of the implementation
for managing the state and visibility of the IME and communicating with the current for managing the state and visibility of the IME and communicating with the current
input field. input field.
</p> </p>
<p> <p>
@@ -122,13 +137,13 @@ page.tags="ime","keyboard","inputmethodservice"
Defines the communication channel from an {@link android.view.inputmethod.InputMethod} 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 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. 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 Applications should extend this class rather than implementing the base interface
{@link android.view.inputmethod.InputConnection}. {@link android.view.inputmethod.InputConnection}.
</dd> </dd>
<dt>{@link android.inputmethodservice.KeyboardView}</dt> <dt>{@link android.inputmethodservice.KeyboardView}</dt>
<dd> <dd>
An extension of {@link android.view.View} that renders a keyboard and responds to user 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 input events. The keyboard layout is specified by an instance of
{@link android.inputmethodservice.Keyboard}, which you can define in an XML file. {@link android.inputmethodservice.Keyboard}, which you can define in an XML file.
</dd> </dd>
</dl> </dl>
@@ -141,40 +156,40 @@ page.tags="ime","keyboard","inputmethodservice"
<h3 id="InputView">Input view</h3> <h3 id="InputView">Input view</h3>
<p> <p>
The input view is the UI where the user inputs text, in the form of keyclicks, handwriting or 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 gestures. When the iIME is displayed for the first time, the system calls the
{@link android.inputmethodservice.InputMethodService#onCreateInputView()} callback. In your {@link android.inputmethodservice.InputMethodService#onCreateInputView()} callback. In your
implementation of this method, you create the layout you want to display in the IME 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 window and return the layout to the system. This snippet is an example of implementing the
{@link android.inputmethodservice.InputMethodService#onCreateInputView()} method: {@link android.inputmethodservice.InputMethodService#onCreateInputView()} method:
<pre> <pre>
&#64;Override &#64;Override
public View onCreateInputView() { public View onCreateInputView() {
MyKeyboardView inputView = MyKeyboardView inputView =
(MyKeyboardView) getLayoutInflater().inflate( R.layout.input, null); (MyKeyboardView) getLayoutInflater().inflate( R.layout.input, null);
inputView.setOnKeyboardActionListener(this); inputView.setKeyboard(mLatinKeyboard); inputView.setOnKeyboardActionListener(this); inputView.setKeyboard(mLatinKeyboard);
return mInputView; return mInputView;
} }
</pre> </pre>
<p> <p>
In this example, {@code MyKeyboardView} is an instance of a custom implementation of In this example, {@code MyKeyboardView} is an instance of a custom implementation of
{@link android.inputmethodservice.KeyboardView} that renders a {@link android.inputmethodservice.KeyboardView} that renders a
{@link android.inputmethodservice.Keyboard}. If you’re building a traditional QWERTY keyboard, {@link android.inputmethodservice.Keyboard}. If you’re building a traditional QWERTY keyboard,
see the Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample see the Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample
app</a> for an example of how to extend the {@link android.inputmethodservice.KeyboardView} class. app</a> for an example of how to extend the {@link android.inputmethodservice.KeyboardView} class.
</p> </p>
<h3 id="CandidateView">Candidates view</h3> <h3 id="CandidateView">Candidates view</h3>
<p> <p>
The candidates view is the UI where the IME displays potential word corrections or 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 suggestions for the user to select. In the IME lifecycle, the system calls
{@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when it's ready {@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 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 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> default behavior, so you don’t have to implement this if you don’t provide suggestions).</p>
<p> <p>
For an example implementation that provides user suggestions, see the For an example implementation that provides user suggestions, see the
Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample
app</a>. app</a>.
</p> </p>
<h3 id="DesignConsiderations">UI design considerations</h3> <h3 id="DesignConsiderations">UI design considerations</h3>
@@ -209,10 +224,10 @@ page.tags="ime","keyboard","inputmethodservice"
<strong>Figure 2.</strong> Latin IME input types. <strong>Figure 2.</strong> Latin IME input types.
</p> </p>
<p> <p>
When an input field receives focus and your IME starts, the system calls When an input field receives focus and your IME starts, the system calls
{@link android.inputmethodservice.InputMethodService#onStartInputView(EditorInfo, boolean) {@link android.inputmethodservice.InputMethodService#onStartInputView(EditorInfo, boolean)
onStartInputView()}, passing in an {@link android.view.inputmethod.EditorInfo} object that 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, 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 the {@link android.view.inputmethod.EditorInfo#inputType} field contains the text field's input
type. type.
</p> </p>
@@ -223,7 +238,7 @@ page.tags="ime","keyboard","inputmethodservice"
this: this:
</p> </p>
<pre> <pre>
inputType &amp; InputType.TYPE_MASK_CLASS inputType &amp; InputType.TYPE_MASK_CLASS
</pre> </pre>
<p> <p>
The input type bit pattern can have one of several values, including: The input type bit pattern can have one of several values, including:
@@ -248,7 +263,7 @@ The input type bit pattern can have one of several values, including:
</dd> </dd>
</dl> </dl>
<p> <p>
These constants are described in more detail in the reference documentation for These constants are described in more detail in the reference documentation for
{@link android.text.InputType}. {@link android.text.InputType}.
</p> </p>
<p> <p>
@@ -287,8 +302,8 @@ The input type bit pattern can have one of several values, including:
<p> <p>
As the user inputs text with your IME, you can send text to the application by 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 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} field. In either case, you use an instance of {@link android.view.inputmethod.InputConnection}
to deliver the text. To get this instance, call to deliver the text. To get this instance, call
{@link android.inputmethodservice.InputMethodService#getCurrentInputConnection {@link android.inputmethodservice.InputMethodService#getCurrentInputConnection
InputMethodService.getCurrentInputConnection()}. InputMethodService.getCurrentInputConnection()}.
</p> </p>
@@ -336,18 +351,18 @@ The input type bit pattern can have one of several values, including:
</p> </p>
<pre> <pre>
InputConnection ic = getCurrentInputConnection(); InputConnection ic = getCurrentInputConnection();
ic.deleteSurroundingText(4, 0); ic.deleteSurroundingText(4, 0);
ic.commitText("Hello", 1); ic.commitText("Hello", 1);
ic.commitText("!", 1); ic.commitText("!", 1);
</pre> </pre>
<h3 id="ComposeThenCommit">Composing text before committing</h3> <h3 id="ComposeThenCommit">Composing text before committing</h3>
<p> <p>
If your IME does text prediction or requires multiple steps to compose a glyph or 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 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 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(). the text by adding a "span" to it when you pass it to InputConnection#setComposingText().
</p> </p>
<p> <p>
@@ -385,10 +400,10 @@ The input type bit pattern can have one of several values, including:
selection during composition. You may also want to trap the back key to dismiss any popups selection during composition. You may also want to trap the back key to dismiss any popups
originating from the input method window.</p> originating from the input method window.</p>
<p> <p>
To intercept hardware keys, override To intercept hardware keys, override
{@link android.inputmethodservice.InputMethodService#onKeyDown(int, KeyEvent) onKeyDown()} {@link android.inputmethodservice.InputMethodService#onKeyDown(int, KeyEvent) onKeyDown()}
and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}. and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}.
See the Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample See the Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample
app</a> for an example. app</a> for an example.
</p> </p>
<p> <p>
@@ -396,7 +411,7 @@ The input type bit pattern can have one of several values, including:
</p> </p>
<h2 id="IMESubTypes">Creating an IME Subtype</h2> <h2 id="IMESubTypes">Creating an IME Subtype</h2>
<p> <p>
Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A
subtype can represent: subtype can represent:
</p> </p>
<ul> <ul>
@@ -414,13 +429,13 @@ The input type bit pattern can have one of several values, including:
<p> <p>
Subtype information is used for an IME switcher dialog that's available from the notification 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 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 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. it helps the user identify and switch between different IME languages and modes.
</p> </p>
<p> <p>
You define subtypes in one of the input method's XML resource files, using the You define subtypes in one of the input method's XML resource files, using the
<code>&lt;subtype&gt;</code> element. The following snippet defines an IME with two <code>&lt;subtype&gt;</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 subtypes: a keyboard subtype for the US English locale, and another keyboard subtype for the
French language locale for France: French language locale for France:
</p> </p>
<pre> <pre>
@@ -457,8 +472,8 @@ The input type bit pattern can have one of several values, including:
android:imeSubtypeMode="keyboard" /&gt; android:imeSubtypeMode="keyboard" /&gt;
</pre> </pre>
<p> <p>
The next snippet is part of the IME's <code>strings.xml</code> file. The string 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 resource <code>label_subtype_generic</code>, which is used by the input method UI definition to
set the subtype's label, is defined as: set the subtype's label, is defined as:
</p> </p>
<pre> <pre>
@@ -487,9 +502,9 @@ The input type bit pattern can have one of several values, including:
<h3 id="SubtypeSettings">Choosing IME subtypes from System Settings</h3> <h3 id="SubtypeSettings">Choosing IME subtypes from System Settings</h3>
<p> <p>
A user can control how subtypes are used in the “Language &amp; input” settings panel in the A user can control how subtypes are used in the “Language &amp; input” settings panel in the
System Settings area. In the Soft Keyboard sample, the file System Settings area. In the Soft Keyboard sample, the file
<code>InputMethodSettingsFragment.java</code> contains an implementation that <code>InputMethodSettingsFragment.java</code> contains an implementation that
facilitates a subtype enabler in the IME settings. Please refer to the SoftKeyboard sample in 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. the Android SDK for more information about how to support Input Method Subtypes in your IME.
</p> </p>
<img src="{@docRoot}resources/articles/images/inputmethod_subtype_settings.png" alt="" <img src="{@docRoot}resources/articles/images/inputmethod_subtype_settings.png" alt=""
@@ -497,6 +512,7 @@ The input type bit pattern can have one of several values, including:
<p class="img-caption"> <p class="img-caption">
<strong>Figure 6.</strong> Choosing a language for the IME. <strong>Figure 6.</strong> Choosing a language for the IME.
</p> </p>
<h2 id="GeneralDesign">General IME Considerations</h2> <h2 id="GeneralDesign">General IME Considerations</h2>
<p> <p>
Here are some other things to consider as you're implementing your IME: Here are some other things to consider as you're implementing your IME:
@@ -506,22 +522,22 @@ The input type bit pattern can have one of several values, including:
Provide a way for users to set options directly from the IME's UI. Provide a way for users to set options directly from the IME's UI.
</li> </li>
<li> <li>
Because multiple IMEs may be installed on the device, provide a way for the user to switch to a 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. different IME directly from the input method UI.
</li> </li>
<li> <li>
Bring up the IME's UI quickly. Preload or load on demand any large resources so that users 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 see the IME as soon as they tap on a text field. Cache resources and views for subsequent
invocations of the input method. invocations of the input method.
</li> </li>
<li> <li>
Conversely, you should release large memory allocations soon after the input method window is 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 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. to release resources if the IME is in a hidden state for a few seconds.
</li> </li>
<li> <li>
Make sure that users can enter as many characters as possible for the language or locale 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 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 names, so your IME has to provide many different characters to allow users to enter a
password and get access to the device. password and get access to the device.
</li> </li>