diff options
author | Joe Malin <jmalin@google.com> | 2012-03-25 13:04:59 -0700 |
---|---|---|
committer | Android Git Automerger <android-git-automerger@android.com> | 2012-03-25 13:04:59 -0700 |
commit | 8ea93aa6adc0e46c8931d31d4f940cdde97c672f (patch) | |
tree | b844d1e140e0287633627abc799eba6340bda2c9 | |
parent | 278296b59fb16b5dcb7cc8e5a7538518a2a3dbb7 (diff) | |
parent | 093ed3838c3f2847be1893ea49c6b15b90e0afc3 (diff) | |
download | frameworks_base-8ea93aa6adc0e46c8931d31d4f940cdde97c672f.zip frameworks_base-8ea93aa6adc0e46c8931d31d4f940cdde97c672f.tar.gz frameworks_base-8ea93aa6adc0e46c8931d31d4f940cdde97c672f.tar.bz2 |
am 093ed383: Merge "DOC CHANGE: IME subtype article" into ics-mr1
* commit '093ed3838c3f2847be1893ea49c6b15b90e0afc3':
DOC CHANGE: IME subtype article
-rw-r--r-- | docs/html/resources/articles/creating-input-method.jd | 742 | ||||
-rw-r--r-- | docs/html/resources/articles/images/inputmethod_composing_text_1.png | bin | 0 -> 5551 bytes | |||
-rw-r--r-- | docs/html/resources/articles/images/inputmethod_composing_text_2.png | bin | 0 -> 5458 bytes | |||
-rw-r--r-- | docs/html/resources/articles/images/inputmethod_composing_text_3.png | bin | 0 -> 1888 bytes | |||
-rw-r--r-- | docs/html/resources/articles/images/inputmethod_lifecycle_image.png | bin | 0 -> 88902 bytes | |||
-rw-r--r-- | docs/html/resources/articles/images/inputmethod_numeric_type_screenshot.png | bin | 0 -> 11814 bytes | |||
-rw-r--r-- | docs/html/resources/articles/images/inputmethod_subtype_notification.png | bin | 0 -> 11404 bytes | |||
-rw-r--r-- | docs/html/resources/articles/images/inputmethod_subtype_preferences.png | bin | 0 -> 18451 bytes | |||
-rw-r--r-- | docs/html/resources/articles/images/inputmethod_subtype_settings.png | bin | 0 -> 16355 bytes | |||
-rw-r--r-- | docs/html/resources/articles/images/inputmethod_text_type_screenshot.png | bin | 0 -> 13017 bytes |
10 files changed, 510 insertions, 232 deletions
diff --git a/docs/html/resources/articles/creating-input-method.jd b/docs/html/resources/articles/creating-input-method.jd index e4b77f4..84c2704 100644 --- a/docs/html/resources/articles/creating-input-method.jd +++ b/docs/html/resources/articles/creating-input-method.jd @@ -3,248 +3,526 @@ parent.title=Articles parent.link=../browser.html?tag=article @jd:body - <div id="qv-wrapper"> <div id="qv"> - - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}resources/articles/on-screen-inputs.html">Onscreen Input Methods</a></li> - <li><a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a></li> - </ol> - +<h2>See also</h2> +<ol> + <li> + <a href="{@docRoot}resources/articles/on-screen-inputs.html">Onscreen Input Methods</a> + </li> + <li> + <a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a> + </li> +</ol> </div> </div> - - -<p>To create an input method (IME) for entering text into text fields -and other Views, you need to extend the {@link android.inputmethodservice.InputMethodService}. -class. This class provides much of the basic implementation for an input -method, in terms of managing the state and visibility of the input method and -communicating with the currently visible activity.</p> - -<p>A good starting point would be the SoftKeyboard sample code provided as part -of the SDK. You can modify the sample code to start building your own input -method.</p> - -<p>An input method is packaged like any other application or service. In the -<code>AndroidManifest.xml</code> file, you declare the input method as a -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> - +<p> + 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 + 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 + entire system; only one IME may be enabled at a time. +</p> +<p> + To add an IME to the Android system, you create an Android application + containing a class that extends {@link android.inputmethodservice.InputMethodService}. In + 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> +<p>This article covers the following:</p> <ul> -<li><code>TYPE_CLASS_NUMBER</code></li> -<li><code>TYPE_CLASS_DATETIME</code></li> -<li><code>TYPE_CLASS_PHONE</code></li> -<li><code>TYPE_CLASS_TEXT</code></li> + <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> + 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(); + + ic.setComposingText("Composi", 1); +... -<p>See <code>android.text.InputType</code> for more details.</p> - -<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> + ic.setComposingText("Composin", 1); -<p>When editing text in a text field, some of the more useful methods on -<code>android.view.inputmethod.InputConnection</code> are:</p> +... + 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> -<li><code>getTextBeforeCursor()</code></li> -<li><code>getTextAfterCursor()</code></li> -<li><code>deleteSurroundingText()</code></li> -<li><code>commitText()</code></li> + <li>A locale such as en_US or fr_FR</li> + <li>An input mode such as voice, keyboard, or handwriting</li> + <li> + Other input styles, forms, or properties specific to the IME, such as 10-key or qwerty + keyboard layouts. + </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.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> - +<p> + Basically, the mode can be any text such as "keyboard", "voice", and so forth. +</p> +<p>A subtype can also expose a combination of these.</p> +<p> + Subtype information is used for an IME switcher dialog that's available from the notification + bar and also for IME settings. The information also allows the framework to bring up a + specific subtype of an IME directly. When you build an IME, use the subtype facility, because + it helps the user identify and switch between different IME languages and modes. +</p> +<p> + You define subtypes in one of the input method's XML resource files, using the + <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 the user to easily bring up any associated settings -directly from the input method UI</li> -<li>Provide -a way for the user to switch to a different input method (multiple -input methods may be installed) directly from the input method UI.</li> -<li>Bring -up the UI quickly - preload or lazy-load any large resources so that -the user sees the input method quickly on tapping on a text field. And -cache any resources and views for subsequent invocations of the input -method.</li> -<li>On the flip side, any large memory allocations should -be released 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 input method is in a hidden -state for a few seconds.</li> -<li>Make sure that most common characters -can be entered using the input method, as users may use punctuation in -passwords or user names and they shouldn't be stuck in a situation -where they can't enter a certain character in order to gain access into -a password-locked device.</li> +<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> - -<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> diff --git a/docs/html/resources/articles/images/inputmethod_composing_text_1.png b/docs/html/resources/articles/images/inputmethod_composing_text_1.png Binary files differnew file mode 100644 index 0000000..3403489 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_composing_text_1.png diff --git a/docs/html/resources/articles/images/inputmethod_composing_text_2.png b/docs/html/resources/articles/images/inputmethod_composing_text_2.png Binary files differnew file mode 100644 index 0000000..67bd1d9 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_composing_text_2.png diff --git a/docs/html/resources/articles/images/inputmethod_composing_text_3.png b/docs/html/resources/articles/images/inputmethod_composing_text_3.png Binary files differnew file mode 100644 index 0000000..4fd1a30 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_composing_text_3.png diff --git a/docs/html/resources/articles/images/inputmethod_lifecycle_image.png b/docs/html/resources/articles/images/inputmethod_lifecycle_image.png Binary files differnew file mode 100644 index 0000000..5f7cf95 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_lifecycle_image.png diff --git a/docs/html/resources/articles/images/inputmethod_numeric_type_screenshot.png b/docs/html/resources/articles/images/inputmethod_numeric_type_screenshot.png Binary files differnew file mode 100644 index 0000000..61b7483 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_numeric_type_screenshot.png diff --git a/docs/html/resources/articles/images/inputmethod_subtype_notification.png b/docs/html/resources/articles/images/inputmethod_subtype_notification.png Binary files differnew file mode 100644 index 0000000..3f13927 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_subtype_notification.png diff --git a/docs/html/resources/articles/images/inputmethod_subtype_preferences.png b/docs/html/resources/articles/images/inputmethod_subtype_preferences.png Binary files differnew file mode 100644 index 0000000..d8aa0cf --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_subtype_preferences.png diff --git a/docs/html/resources/articles/images/inputmethod_subtype_settings.png b/docs/html/resources/articles/images/inputmethod_subtype_settings.png Binary files differnew file mode 100644 index 0000000..b8942c6 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_subtype_settings.png diff --git a/docs/html/resources/articles/images/inputmethod_text_type_screenshot.png b/docs/html/resources/articles/images/inputmethod_text_type_screenshot.png Binary files differnew file mode 100644 index 0000000..8008b27 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_text_type_screenshot.png |