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

am 315a45e0: am 36d13e6a: am 491fa057: am d664dc93: Merge "Android 5.0 changes to IME switching" into lmp-dev

Browse Source 
* commit '315a45e085a14884e267c49498e94a316376e212':
  Android 5.0 changes to IME switching
This commit is contained in:
Joe Fernandez
2014-10-17 19:09:52 +00:00
committed by Android Git Automerger
parent 324091e6d2 315a45e085
commit bc31db59e5
1 changed files with 330 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -6,45 +6,37 @@ page.tags=ime,keyboard,inputmethodservice
<div id="qv"> <div id="qv">
<h2>In This Document</h2> <h2>In This Document</h2>
<ol> <ol>
<li> <li><a href="#InputMethodLifecycle">The IME Lifecycle</a></li>
<a href="#InputMethodLifecycle">The IME Lifecycle</a> <li><a href="#DefiningIME">Declaring IME Components in the Manifest</a></li>
</li> <li><a href="#IMEAPI">The Input Method API</a></li>
<li> <li><a href="#IMEUI">Designing the Input Method UI</a></li>
<a href="#DefiningIME">Declaring IME Components in the Manifest</a> <li><a href="#SendText">Sending Text to the Application</a></li>
</li> <li><a href="#IMESubTypes">Creating an IME Subtype</a></li>
<li> <li><a href="#Switching">Switching among IME Subtypes</a></li>
<a href="#IMEAPI">The Input Method API</a> <li><a href="#GeneralDesign">General IME Considerations</a></li>
</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> </ol>
<h2>See also</h2> <h2>See also</h2>
<ol> <ol>
<li> <li>
<a href="http://android-developers.blogspot.com/2009/04/updating-applications-for-on-screen.html">Onscreen Input Methods</a> <a href="http://android-developers.blogspot.com/2009/04/updating-applications-for-on-screen.html">Onscreen Input Methods</a>
</li> </li>
<li> </ol>
<a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a>
<h2>Sample</h2>
<ol>
<li><a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/">
SoftKeyboard</a>
</li> </li>
</ol> </ol>
</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. After installing
users can select which IME they want to use from the system settings and use it across the the desired IMEs, a user can select which one to use from the system settings, and use it
entire system; only one IME may be enabled at a time. across the 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
@@ -52,37 +44,54 @@ page.tags=ime,keyboard,inputmethodservice
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 guide 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>
Also, the Soft Keyboard sample app included in the SDK contains sample code that you can modify first.
to start building your own IME. Also, the <a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/">
SoftKeyboard</a> sample app included in the SDK contains sample code that you can modify to
start building your own IME.
</p> </p>
<h2 id="InputMethodLifecycle">The IME Lifecycle</h2> <h2 id="InputMethodLifecycle">The IME Lifecycle</h2>
<p> <p>
The following diagram describes the life cycle of an IME: The following diagram describes the life cycle of an IME:
</p> </p>
<img src="{@docRoot}resources/articles/images/inputmethod_lifecycle_image.png" alt="" height="845" <img src="{@docRoot}resources/articles/images/inputmethod_lifecycle_image.png" alt="" height="845" id="figure1" />
id="figure1" />
<p class="img-caption"> <p class="img-caption">
<strong>Figure 1.</strong> The life cycle of an IME. <strong>Figure 1.</strong> The life cycle of an IME.
</p> </p>
<p> <p>
The following sections describe how to implement the UI and code associated with an IME that The following sections describe how to implement the UI and code associated
with an IME that
follows this lifecycle. follows this lifecycle.
</p> </p>
<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
The application's manifest file must declare the service, request the necessary permissions, special IME service.
provide an intent filter that matches the action <code>action.view.InputMethod</code>, and The application's manifest file must declare the service, request the
provide metadata that defines characteristics of the IME. In addition, to provide a settings necessary permissions,
interface that allows the user to modify the behavior of the IME, you can define a "settings" 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. 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 an IME service. It requests the permission
android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to connect the IME to {@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 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>
@@ -94,12 +103,15 @@ page.tags=ime,keyboard,inputmethodservice
&lt;intent-filter&gt; &lt;intent-filter&gt;
&lt;action android:name="android.view.InputMethod" /&gt; &lt;action android:name="android.view.InputMethod" /&gt;
&lt;/intent-filter&gt; &lt;/intent-filter&gt;
&lt;meta-data android:name="android.view.im" android:resource="&#64;xml/method" /&gt; &lt;meta-data android:name="android.view.im"
android:resource="&#64;xml/method" /&gt;
&lt;/service&gt; &lt;/service&gt;
</pre> </pre>
<p> <p>
This next snippet declares the settings activity for the IME. It has an intent filter for This next snippet declares the settings activity for the IME. It has an
{@link android.content.Intent#ACTION_MAIN} that indicates this activity is the main entry point intent filter for
{@link android.content.Intent#ACTION_MAIN} that indicates this activity is
the main entry point
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;
@@ -115,17 +127,22 @@ page.tags=ime,keyboard,inputmethodservice
</p> </p>
<h2 id="IMEAPI">The Input Method API</h2> <h2 id="IMEAPI">The Input Method API</h2>
<p> <p>
Classes specific to IMEs are found in the {@link android.inputmethodservice} and {@link Classes specific to IMEs are found in the {@link android.inputmethodservice} and {@link android.view.inputmethod}
android.view.inputmethod} packages. The {@link android.view.KeyEvent} class is important for packages. The {@link android.view.KeyEvent} class is important for handling keyboard
handling keyboard characters. 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
normal service lifecycle, this class has callbacks for providing your IME's UI, handling user implementing the
input, and delivering text to the field that currently has focus. By default, the normal service lifecycle, this class has callbacks for providing your IME's
{@link android.inputmethodservice.InputMethodService} class provides most of the implementation UI, handling user
for managing the state and visibility of the IME and communicating with the current 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. input field.
</p> </p>
<p> <p>
@@ -135,62 +152,84 @@ page.tags=ime,keyboard,inputmethodservice
<dt>{@link android.view.inputmethod.BaseInputConnection}</dt> <dt>{@link android.view.inputmethod.BaseInputConnection}</dt>
<dd> <dd>
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
cursor, commit text to the text box, and send raw key events to the application. text around the
Applications should extend this class rather than implementing the base interface 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}. {@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>
<h2 id="IMEUI">Designing the Input Method UI</h2> <h2 id="IMEUI">Designing the Input Method UI</h2>
<p> <p>
There are two main visual elements for an IME: the <strong>input</strong> view and the There are two main visual elements for an IME: the <strong>input</strong>
<strong>candidates</strong> view. You only have to implement the elements that are relevant to view and the
<strong>candidates</strong> view. You only have to implement the elements
that are relevant to
the input method you're designing. the input method you're designing.
</p> </p>
<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
gestures. When the iIME is displayed for the first time, the system calls the keyclicks, handwriting or
{@link android.inputmethodservice.InputMethodService#onCreateInputView()} callback. In your gestures. When the IME is displayed for the first time, the system calls
implementation of this method, you create the layout you want to display in the IME the
window and return the layout to the system. This snippet is an example of implementing the {@link android.inputmethodservice.InputMethodService#onCreateInputView()}
{@link android.inputmethodservice.InputMethodService#onCreateInputView()} method: 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> <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
see the Soft Keyboard <a href="{@docRoot}tools/samples/index.html">sample traditional QWERTY keyboard,
app</a> for an example of how to extend the {@link android.inputmethodservice.KeyboardView} class. see the <a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/>
SoftKeyboard</a> sample app 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
to display the candidate view. In your implementation of this method, return a layout that shows it's ready
word suggestions, or return null if you don’t want to show anything (a null response is the to display the candidates view. In your implementation of this method,
default behavior, so you don’t have to implement this if you don’t provide suggestions).</p> 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> <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 <a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/">
app</a>. SoftKeyboard</a> sample app.
</p> </p>
<h3 id="DesignConsiderations">UI design considerations</h3> <h3 id="DesignConsiderations">UI design considerations</h3>
<p> <p>
@@ -198,42 +237,54 @@ page.tags=ime,keyboard,inputmethodservice
</p> </p>
<h4>Handling multiple screen sizes</h4> <h4>Handling multiple screen sizes</h4>
<p> <p>
The UI for your IME must be able to scale for different screen sizes, and it also The UI for your IME must be able to scale for different screen sizes, and
must handle both landscape and portrait orientations. In non-fullscreen IME mode, leave it also
sufficient space for the application to show the text field and any associated context, so that must handle both landscape and portrait orientations. In non-fullscreen IME
no more than half the screen is occupied by the IME. In fullscreen IME mode this is not an 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. issue.
</p> </p>
<h4>Handling different input types</h4> <h4>Handling different input types</h4>
<p> <p>
Android text fields allow you to set a specific input type, such as free form text, numbers, Android text fields allow you to set a specific input type, such as free
URLs, email addresses, and search strings. When you implement a new IME, you need to form text, numbers,
detect the input type of each field and provide the appropriate interface for it. However, you URLs, email addresses, and search strings. When you implement a new IME,
don't have to set up your IME to check that the user entered text that's valid for the you need to
input type; that's the responsibility of the application that owns the text field. 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.
</p> </p>
<p> <p>
For example, here are screenshots of the interfaces that the Latin IME provided with the For example, here are screenshots of the interfaces that the Latin IME
provided with the
Android platform provides for text and phone number inputs: Android platform provides for text and phone number inputs:
</p> </p>
<img src="{@docRoot}resources/articles/images/inputmethod_text_type_screenshot.png" alt="" <img src="{@docRoot}resources/articles/images/inputmethod_text_type_screenshot.png" alt="" height="142" id="figure2" />
height="142" id="figure2" /> <img src="{@docRoot}resources/articles/images/inputmethod_numeric_type_screenshot.png" alt="" height="120" id="figure2a" />
<img src="{@docRoot}resources/articles/images/inputmethod_numeric_type_screenshot.png" alt=""
height="120" id="figure2a" />
<p class="img-caption"> <p class="img-caption">
<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()},
onStartInputView()}, passing in an {@link android.view.inputmethod.EditorInfo} object that 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
the {@link android.view.inputmethod.EditorInfo#inputType} field contains the text field's input field. In this object,
the {@link android.view.inputmethod.EditorInfo#inputType} field contains
the text field's input
type. type.
</p> </p>
<p> <p>
The {@link android.view.inputmethod.EditorInfo#inputType} field is an <code>int</code> The {@link android.view.inputmethod.EditorInfo#inputType} field is an
that contains bit patterns for various input type settings. To test it for the text field's <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 input type, mask it with the constant {@link android.text.InputType#TYPE_MASK_CLASS}, like
this: this:
</p> </p>
@@ -246,7 +297,8 @@ The input type bit pattern can have one of several values, including:
<dl> <dl>
<dt>{@link android.text.InputType#TYPE_CLASS_NUMBER}</dt> <dt>{@link android.text.InputType#TYPE_CLASS_NUMBER}</dt>
<dd> <dd>
A text field for entering numbers. As illustrated in the previous screen shot, the 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. Latin IME displays a number pad for fields of this type.
</dd> </dd>
<dt>{@link android.text.InputType#TYPE_CLASS_DATETIME}</dt> <dt>{@link android.text.InputType#TYPE_CLASS_DATETIME}</dt>
@@ -263,91 +315,103 @@ 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>
The {@link android.view.inputmethod.EditorInfo#inputType} field can contain other bits that The {@link android.view.inputmethod.EditorInfo#inputType} field can contain
other bits that
indicate a variant of the text field type, such as: indicate a variant of the text field type, such as:
</p> </p>
<dl> <dl>
<dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_PASSWORD}</dt> <dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_PASSWORD}</dt>
<dd> <dd>
A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering passwords. The A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for
entering passwords. The
input method will display dingbats instead of the actual text. input method will display dingbats instead of the actual text.
</dd> </dd>
<dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_URI}</dt> <dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_URI}</dt>
<dd> <dd>
A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering web URLs and A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for
entering web URLs and
other Uniform Resource Identifiers (URIs). other Uniform Resource Identifiers (URIs).
</dd> </dd>
<dt>{@link android.text.InputType#TYPE_TEXT_FLAG_AUTO_COMPLETE}</dt> <dt>{@link android.text.InputType#TYPE_TEXT_FLAG_AUTO_COMPLETE}</dt>
<dd> <dd>
A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering text that the A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for
application "auto-completes" from a dictionary, search, or other facility. entering text that the
application "auto-completes" from a dictionary, search, or other
facility.
</dd> </dd>
</dl> </dl>
<p> <p>
Remember to mask {@link android.view.inputmethod.EditorInfo#inputType} with the appropriate Remember to mask {@link android.view.inputmethod.EditorInfo#inputType} with
constant when you test for these variants. The available mask constants are listed in the the appropriate
constant when you test for these variants. The available mask constants are
listed in the
reference documentation for {@link android.text.InputType}. reference documentation for {@link android.text.InputType}.
</p> </p>
<p class="caution"> <p class="caution">
<strong>Caution:</strong> In your own IME, make sure you handle text correctly when you send it <strong>Caution:</strong> In your own IME, make sure you handle text
to a password field. Hide the password in your UI both in the input view and in the candidates correctly when you send it
view. Also remember that you shouldn't store passwords on a device. To learn more, see the <a to a password field. Hide the password in your UI both in the input view
href="{@docRoot}guide/practices/security.html">Designing for Security</a> guide. 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> </p>
<h2 id="SendText">Sending Text to the Application</h2> <h2 id="SendText">Sending Text to the Application</h2>
<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
sending individual key events or by editing the text around the cursor in the application's text 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} 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>
<h3 id="EditingCursor">Editing the text around the cursor</h3> <h3 id="EditingCursor">Editing the text around the cursor</h3>
<p> <p>
When you're handling the editing of existing text in a text field, some of the more useful 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: methods in {@link android.view.inputmethod.BaseInputConnection} are:
</p> </p>
<dl> <dl>
<dt> <dt>
{@link android.view.inputmethod.BaseInputConnection#getTextBeforeCursor(int, int) {@link android.view.inputmethod.BaseInputConnection#getTextBeforeCursor(int, int) getTextBeforeCursor()}</dt>
getTextBeforeCursor()}</dt>
<dd> <dd>
Returns a {@link java.lang.CharSequence} containing the number of requested characters Returns a {@link java.lang.CharSequence} containing the number of
requested characters
before the current cursor position. before the current cursor position.
</dd> </dd>
<dt> <dt>
{@link android.view.inputmethod.BaseInputConnection#getTextAfterCursor(int, int) {@link android.view.inputmethod.BaseInputConnection#getTextAfterCursor(int, int) getTextAfterCursor()}
getTextAfterCursor()}
</dt> </dt>
<dd> <dd>
Returns a {@link java.lang.CharSequence} containing the number of requested characters Returns a {@link java.lang.CharSequence} containing the number of
following the current cursor position. requested characters following the current cursor position.
</dd> </dd>
<dt> <dt>
{@link android.view.inputmethod.BaseInputConnection#deleteSurroundingText(int, int) {@link android.view.inputmethod.BaseInputConnection#deleteSurroundingText(int, int) deleteSurroundingText()}
deleteSurroundingText()}
</dt> </dt>
<dd> <dd>
Deletes the specified number of characters before and following the current cursor Deletes the specified number of characters before and following the
current cursor
position. position.
</dd> </dd>
<dt> <dt>
{@link android.view.inputmethod.BaseInputConnection#commitText(CharSequence, int) {@link android.view.inputmethod.BaseInputConnection#commitText(CharSequence, int) commitText()}
commitText()}
</dt> </dt>
<dd> <dd>
Commit a {@link java.lang.CharSequence} to the text field and set a new cursor Commit a {@link java.lang.CharSequence} to the text field and set a new
cursor
position. position.
</dd> </dd>
</dl> </dl>
<p> <p>
For example, the following snippet shows how to replace the text "Fell" to the left of the For example, the following snippet shows how to replace the four characters to
with the text "Hello!": the left of the cursor with the text "Hello!":
</p> </p>
<pre> <pre>
InputConnection ic = getCurrentInputConnection(); InputConnection ic = getCurrentInputConnection();
@@ -360,10 +424,14 @@ The input type bit pattern can have one of several values, including:
</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
word, you can show the progress in the text field until the user commits the word, and then you glyph or
can replace the partial composition with the completed text. You may give special treatment to word, you can show the progress in the text field until the user commits
the text by adding a "span" to it when you pass it to InputConnection#setComposingText(). 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()}.
</p> </p>
<p> <p>
The following snippet shows how to show progress in a text field: The following snippet shows how to show progress in a text field:
@@ -383,59 +451,77 @@ The input type bit pattern can have one of several values, including:
<p> <p>
The following screenshots show how this appears to the user: The following screenshots show how this appears to the user:
</p> </p>
<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_1.png" alt="" height="54" <img src="{@docRoot}resources/articles/images/inputmethod_composing_text_1.png"
alt="" height="54"
id="figure3a" /> id="figure3a" />
<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_2.png" alt="" height="53" <img src="{@docRoot}resources/articles/images/inputmethod_composing_text_2.png"
alt="" height="53"
id="figure3b" /> id="figure3b" />
<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_3.png" alt="" height="31" <img src="{@docRoot}resources/articles/images/inputmethod_composing_text_3.png"
alt="" height="31"
id="figure3c" /> id="figure3c" />
<p class="img-caption"> <p class="img-caption">
<strong>Figure 3.</strong> Composing text before committing. <strong>Figure 3.</strong> Composing text before committing.
</p> </p>
<h3 id="HardwareKeyEvents">Intercepting hardware key events</h3> <h3 id="HardwareKeyEvents">Intercepting hardware key events</h3>
<p> <p>
Even though the input method window doesn't have explicit focus, it receives hardware key Even though the input method window doesn't have explicit focus, it
events first and can choose to consume them or forward them along to the application. For receives hardware key
example, you may want to consume the directional keys to navigate within your UI for candidate events first and can choose to consume them or forward them along to the
selection during composition. You may also want to trap the back key to dismiss any popups 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> 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
app</a> for an example. <a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/">
SoftKeyboard</a> sample app for an example.
</p> </p>
<p> <p>
Remember to call the <code>super()</code> method for keys you don't want to handle yourself. Remember to call the <code>super()</code> method for keys you don't want to
handle yourself.
</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
subtype can represent: supported by an IME. A subtype can represent:
</p> </p>
<ul> <ul>
<li>A locale such as en_US or fr_FR</li> <li>A locale such as en_US or fr_FR</li>
<li>An input mode such as voice, keyboard, or handwriting</li> <li>An input mode such as voice, keyboard, or handwriting</li>
<li> <li>
Other input styles, forms, or properties specific to the IME, such as 10-key or qwerty Other input styles, forms, or properties specific to the IME, such as
10-key or qwerty
keyboard layouts. keyboard layouts.
</li> </li>
</ul> </ul>
<p> <p>
Basically, the mode can be any text such as "keyboard", "voice", and so forth. Basically, the mode can be any text such as "keyboard", "voice", and so
forth. A subtype can also expose a combination of these.
</p> </p>
<p>A subtype can also expose a combination of these.</p>
<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
bar and also for IME settings. The information also allows the framework to bring up a from the notification
specific subtype of an IME directly. When you build an IME, use the subtype facility, because bar and also for IME settings. The information also allows the framework to
it helps the user identify and switch between different IME languages and modes. 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.
</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
<code>&lt;subtype&gt;</code> element. The following snippet defines an IME with two the
subtypes: a keyboard subtype for the US English locale, and another keyboard subtype for the <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
French language locale for France: French language locale for France:
</p> </p>
<pre> <pre>
@@ -460,8 +546,10 @@ The input type bit pattern can have one of several values, including:
/&gt; /&gt;
</pre> </pre>
<p> <p>
To ensure that your subtypes are labeled correctly in the UI, use %s to get a subtype label To ensure that your subtypes are labeled correctly in the UI, use %s to get
that is the same as the subtype’s locale label. This is demonstrated in the next two snippets. 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: The first snippet shows part of the input method's XML file:
</p> </p>
<pre> <pre>
@@ -472,47 +560,99 @@ 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
resource <code>label_subtype_generic</code>, which is used by the input method UI definition to 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: set the subtype's label, is defined as:
</p> </p>
<pre> <pre>
&lt;string name="label_subtype_generic"&gt;%s&lt;/string&gt; &lt;string name="label_subtype_generic"&gt;%s&lt;/string&gt;
</pre> </pre>
<p> <p>
This sets the subtype’s display name to “English (United States)” in any English language This setting causes the subtype’s display name to match the locale setting.
locale, or to the appropriate localization in other locales. For example, in any English locale, the display name is “English (United States)”.
</p> </p>
<h3 id="SubtypeProcessing">Choosing IME subtypes from the notification bar</h3> <h3 id="SubtypeProcessing">Choosing IME subtypes from the notification bar</h3>
<p> <p>
The Android system manages all subtypes exposed by all IMEs. IME subtypes are The Android system manages all subtypes exposed by all IMEs. IME subtypes
treated as modes of the IME they belong to. In the notification bar, a user can select an are
available subtype for the currently-set IME, as shown in the following screenshot: 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> </p>
<img src="{@docRoot}resources/articles/images/inputmethod_subtype_notification.png" alt="" <img
src="{@docRoot}resources/articles/images/inputmethod_subtype_notification.png"
alt=""
height="85" id="figure4" /> height="85" id="figure4" />
<p class="img-caption"> <p class="img-caption">
<strong>Figure 4.</strong> Choosing an IME subtype from the notification bar. <strong>Figure 4.</strong> Choosing an IME subtype from the notification
bar.
</p> </p>
<img src="{@docRoot}resources/articles/images/inputmethod_subtype_preferences.png" alt="" <img
src="{@docRoot}resources/articles/images/inputmethod_subtype_preferences.png"
alt=""
height="165" id="figure5" /> height="165" id="figure5" />
<p class="img-caption"> <p class="img-caption">
<strong>Figure 5.</strong> Setting subtype preferences in System Settings. <strong>Figure 5.</strong> Setting subtype preferences in System Settings.
</p> </p>
<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”
System Settings area. In the Soft Keyboard sample, the file settings panel in the
<code>InputMethodSettingsFragment.java</code> contains an implementation that System Settings area. In the <a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/">
facilitates a subtype enabler in the IME settings. Please refer to the SoftKeyboard sample in SoftKeyboard</a> sample app, the file <code>InputMethodSettingsFragment.java</code> contains an
the Android SDK for more information about how to support Input Method Subtypes in your IME. implementation that facilitates a subtype enabler in the IME settings. Refer to the
<a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/">
SoftKeyboard</a> sample app in 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=""
height="210" id="figure6" /> height="210" id="figure6" />
<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="Switching">Switching among IME Subtypes</h2>
<p>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:</p>
<p>
<ol>
<li>Declare <code>supportsSwitchingToNextInputMethod = "true"</code> in the
input method's XML resource files. Your declaration
should look similar to the following snippet:
<pre>
&lt;input-method xmlns:android="http://schemas.android.com/apk/res/android"
android:settingsActivity="com.example.softkeyboard.Settings"
android:icon="&#64;drawable/ime_icon"
android:supportsSwitchingToNextInputMethod="true"&gt;
</pre></li>
<li>Call the {@link android.view.inputmethod.InputMethodManager#shouldOfferSwitchingToNextInputMethod shouldOfferSwitchingToNextInputMethod()} method.</li>
<li>If the method returns true, display a switching key.</li>
<li>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.</li>
</ol>
</p>
<p class="caution">
<strong>Caution:</strong> Prior to Android 5.0 (API level 21),
{@link android.view.inputmethod.InputMethodManager#switchToNextInputMethod switchToNextInputMethod()}
is not aware of the <code>supportsSwitchingToNextInputMethod</code> attribute. If the user switches
into an IME without a switching key, he or she may get stuck in that IME, unable to switch out of it
easily.</p>
<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:
@@ -522,23 +662,31 @@ 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
see the IME as soon as they tap on a text field. Cache resources and views for subsequent 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. 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
hidden, so that applications can have sufficient memory to run. Consider using a delayed message 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. 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
associated with the IME. Remember that users may use punctuation in passwords or user language or locale
names, so your IME has to provide many different characters to allow users to enter a 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. password and get access to the device.
</li> </li>
</ul> </ul>