diff options
Diffstat (limited to 'docs/html/resources')
14 files changed, 541 insertions, 239 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 diff --git a/docs/html/resources/resources_toc.cs b/docs/html/resources/resources_toc.cs index e1a5e0f..303a6d4 100644 --- a/docs/html/resources/resources_toc.cs +++ b/docs/html/resources/resources_toc.cs @@ -97,6 +97,30 @@ </li> </ul> </li> + + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>training/efficient-downloads/index.html"> + <span class="en">Transferring Data Without Draining the Battery</span> + </a> <span class="new">new!</span></div> + <ul> + <li><a href="<?cs var:toroot ?>training/efficient-downloads/efficient-network-access.html"> + <span class="en">Optimizing Downloads for Efficient Network Access</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/efficient-downloads/regular_updates.html"> + <span class="en">Minimizing the Effect of Regular Updates</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/efficient-downloads/redundant_redundant.html"> + <span class="en">Redundant Downloads are Redundant</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/efficient-downloads/connectivity_patterns.html"> + <span class="en">Modifying Patterns Based on the Connectivity Type</span> + </a> + </li> + </ul> + </li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>training/search/index.html"> diff --git a/docs/html/resources/samples/get.jd b/docs/html/resources/samples/get.jd index 86ec836..751965f 100644 --- a/docs/html/resources/samples/get.jd +++ b/docs/html/resources/samples/get.jd @@ -26,15 +26,15 @@ needed!</p> <p>The SDK sample code is available to you as a set of downloadable SDK components, each of which contains the samples for a specific Android platform version. Once you have installed the SDK, you can download one or more samples -component(s) into your SDK environment using the Android SDK and AVD Manager +component(s) into your SDK environment using the Android SDK Manager tool, which is pre-installed in the SDK. </p> -<p>To download the samples, launch the Android SDK and AVD Manager tool and +<p>To download the samples, launch the Android SDK Manager tool and select one of the samples components from the <strong>Available Packages</strong> panel, for example "Samples for SDK API 7". Select <strong>Install Selected</strong>, verify and accept the download, then select <strong>Install Accepted</strong> to download the component into your SDK. If -you aren't familiar with the Android SDK and AVD Manager and how to launch or +you aren't familiar with the Android SDK Manager and how to launch or use it, please read the <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a> document. </p> @@ -74,7 +74,7 @@ From there you can read a short summary of each sample application and what types of concepts, features, or APIs it includes. Then, use the links provided to move through the directories and files of each sample. The browseable source is generated from the same source code that is downloadable through the Android -SDK and AVD Manager, as described above. </p> +SDK Manager, as described above. </p> <p>The browseable samples files are available online, at the Android Developers site only and are not included in the downloadable offline documentation. diff --git a/docs/html/resources/tutorials/hello-world.jd b/docs/html/resources/tutorials/hello-world.jd index cc8cb3e..70ba06c 100644 --- a/docs/html/resources/tutorials/hello-world.jd +++ b/docs/html/resources/tutorials/hello-world.jd @@ -42,7 +42,7 @@ you need to do it now.</p> <ol> - <li>In the Android SDK and AVD Manager, choose <strong>Available + <li>In the Android SDK Manager, choose <strong>Available Packages</strong> in the left panel.</li> <li>In the right panel, expand the Android Repository list to display @@ -72,7 +72,7 @@ device settings used by the emulator.</p> <p>To create an AVD:</p> <ol> - <li>In Eclipse, select <strong>Window > Android SDK and AVD Manager</strong>.</li> + <li>In Eclipse, select <strong>Window > AVD Manager</strong>.</li> <li>Select <strong>Virtual Devices</strong> in the left panel.</li> <li>Click <strong>New...</strong>. diff --git a/docs/html/resources/tutorials/testing/activity_test.jd b/docs/html/resources/tutorials/testing/activity_test.jd index 4b861e2..f88b768 100644 --- a/docs/html/resources/tutorials/testing/activity_test.jd +++ b/docs/html/resources/tutorials/testing/activity_test.jd @@ -163,7 +163,7 @@ parent.link=../../browser.html?tag=tutorial open the Android SDK and AVD Manager and check in the <strong>Installed Packages</strong> panel. If aren't sure how to download a platform into your SDK, - read <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. + read <a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>. </p> </li> </ul> |
