| page.title=Onscreen Input Methods |
| 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/creating-input-method.html">Creating an Input |
| Method</a></li> |
| <li><a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| |
| <p>Starting from Android 1.5, the Android platform offers an Input Method |
| Framework (IMF) that lets you create on-screen input methods such as software |
| keyboards. This article provide an overview of what Android input method editors |
| (IMEs) are and what an application needs to do to work well with them. The IMF |
| is designed to support new classes of Android devices, such as those without |
| hardware keyboards, so it is important that your application works well with the |
| IMF and offers a great experience for users.</p> |
| |
| <h3>What is an input method?</h3> |
| |
| <p>The Android IMF is designed to support a variety of IMEs, including soft |
| keyboard, hand-writing recognizers, and hard keyboard translators. Our focus, |
| however, will be on soft keyboards, since this is the kind of input method that |
| is currently part of the platform.</p> |
| |
| <p>A user will usually access the current IME by tapping on a text view to |
| edit, as shown here in the home screen:</p> |
| |
| <img style="width: 320px; height: 480px; margin-right: 10px;" src="images/on-screen-inputs_004.png"> |
| <img style="width: 320px; height: 480px;" src="images/on-screen-inputs.png"> |
| |
| <p>The soft keyboard is positioned at the bottom of the screen over the |
| application's window. To organize the available space between the application |
| and IME, we use a few approaches; the one shown here is called <em>pan and |
| scan</em>, and simply involves scrolling the application window around so that |
| the currently focused view is visible. This is the default mode, since it is the |
| safest for existing applications.</p> |
| |
| <p>Most often the preferred screen layout is a <em>resize</em>, where the |
| application's window is resized to be entirely visible. An example is shown |
| here, when composing an e-mail message:</p> |
| |
| <img style="width: 320px; height: 480px; margin-right: 10px;" src="images/on-screen-inputs_005.png"> |
| <img style="width: 320px; height: 480px;" src="images/on-screen-inputs_003.png"> |
| |
| <p>The size of the application window is changed so that none of it is hidden by |
| the IME, allowing full access to both the application and IME. This of course |
| only works for applications that have a resizeable area that can be reduced to |
| make enough space, but the vertical space in this mode is actually no less than |
| what is available in landscape orientation, so very often an application can |
| already accommodate it.</p> |
| |
| <p>The final major mode is <em>fullscreen</em> or <em>extract</em> |
| mode. This is used when the IME is too large to reasonably share space |
| with the underlying application. With the standard IMEs, you will only |
| encounter this situation when the screen is in a landscape orientation, |
| although other IMEs are free to use it whenever they desire. In this |
| case the application window is left as-is, and the IME simply displays |
| fullscreen on top of it, as shown here:</p> |
| |
| <img style="width: 480px; height: 320px; margin-right: 10px; margin-bottom: 10px;" src="images/on-screen-inputs_006.png"> |
| <img style="width: 480px; height: 320px;" src="images/on-screen-inputs_002.png"> |
| |
| <p>Because the IME is covering the application, it has its own editing area, |
| which shows the text actually contained in the application. There are also some |
| limited opportunities the application has to customize parts of the IME (the |
| "done" button at the top and enter key label at the bottom) to improve the user |
| experience.</p> |
| |
| <h3>Basic XML attributes for controlling IMEs</h3> |
| |
| <p>There are a number of things the system does to try to help existing |
| applications work with IMEs as well as possible, such as:</p> |
| |
| <ul> |
| <li>Use pan and scan mode by default, unless it can reasonably guess that |
| resize mode will work by the existence of lists, scroll views, etc.</li> |
| <li>Analyze the various existing TextView attributes to guess at the kind of |
| content (numbers, plain text, etc) to help the soft keyboard display an |
| appropriate key layout.</li> |
| <li>Assign a few default actions to the fullscreen IME, such as "next field" |
| and "done".</li> |
| </ul> |
| |
| <p>There are also some simple things you can do in your application that will |
| often greatly improve its user experience. Except where explicitly mentioned, |
| these will work in any Android platform version, even those previous to Android |
| 1.5 (since they will simply ignore these new options).</p> |
| |
| <h4>Specifying each EditText control's input type</h4> |
| |
| <p>The most important thing for an application to do is to use the new |
| <code>android:inputType</code> |
| attribute on each <code>EditText</code>. The attribute provides much richer |
| information |
| about the text content. This attribute actually replaces many existing |
| attributes (<code>android:</code><code>password</code>, |
| <code>android:</code><code>singleLine</code>, |
| <code>android:</code><code>numeric</code>, |
| <code>android:</code><code>phoneNumber</code>, |
| <code>android:</code><code>capitalize</code>, |
| <code>android:</code><code>autoText</code>, and |
| <code>android:</code><code>editable</code>). If you specify the older attributes |
| and the new <code>android:inputType</code> attribute, the system uses |
| <code>android:inputType</code> and ignores the others. </p> |
| |
| <p>The <code>android:inputType</code> attribute has three pieces:</p> |
| |
| <ul> |
| <li>The <em>class</em> is the overall interpretation of characters. The |
| currently supported classes are <code>text</code> (plain text), |
| <code>number</code> (decimal number), <code>phone</code> (phone number), and |
| <code>datetime</code> (a date or time).</li> |
| <li>The <em>variation</em> is a further refinement on the class. In the |
| attribute you will normally specify the class and variant together, with the |
| class as a prefix. For example, <code>textEmailAddress</code> is a text field |
| where the user will enter something that is an e-mail address (foo@bar.com) so |
| the key layout will have an '@' character in easy access, and |
| <code>numberSigned</code> is a numeric field with a sign. If only the class is |
| specified, then you get the default/generic variant.</li> |
| <li>Additional <em>flags</em> can be specified that supply further refinement. |
| These flags are specific to a class. For example, some flags for the |
| <code>text</code> class are <code>textCapSentences</code>, |
| <code>textAutoCorrect</code>, and <code>textMultiline</code>.</li> |
| </ul> |
| |
| <p>As an example, here is the new EditText for the IM application's message text view:</p> |
| |
| <pre> <EditText android:id="@+id/edtInput" |
| android:layout_width="0dip" |
| android:layout_height="wrap_content" |
| android:layout_weight="1" |
| android:inputType="textShortMessage|textAutoCorrect|textCapSentences|textMultiLine" |
| android:imeOptions="actionSend|flagNoEnterAction" |
| android:maxLines="4" |
| android:maxLength="2000" |
| android:hint="@string/compose_hint"/></pre> |
| |
| <p>A full description of all of the input types can be found in the |
| documentation. It is important to make use of the correct input types that are |
| available, so that the soft keyboard can use the optimal keyboard layout for the |
| text the user will be entering.</p> |
| |
| <h4>Enabling resize mode and other window features</h4> |
| |
| <p>The second most important thing for your app to do is to specify the overall |
| behavior of your window in relation to the input method. The most visible aspect |
| of this is controlling resize vs. pan and scan mode, but there are other things |
| you can do as well to improve your user experience.</p> |
| |
| <p>You will usually control this behavior through the |
| <code>android:windowSoftInputMode</code> attribute on each |
| <code><activity></code> definition in your |
| <code>AndroidManifest.xml</code>. Like the input type, there are a couple |
| different pieces of data that can be specified here by combining them |
| together:</p> |
| |
| <ul> |
| <li>The window adjustment mode is specified with either |
| <code>adjustResize</code> or <code>adjustPan</code>. It is highly recommended |
| that you always specify one or the other.</li> |
| <li>You can further control whether the IME will be shown automatically when |
| your activity is displayed and other situations where the user moves to it. The |
| system won't automatically show an IME by default, but in some cases it can be |
| convenient for the user if an application enables this behavior. You can request |
| this with <code>stateVisible</code>. There are also a number of other state |
| options for finer-grained control that you can find in the documentation.</li> |
| </ul> |
| |
| <p>A typical example of this field can be see in the edit contact activity, |
| which ensures it is resized and automatically displays the IME for the user:</p> |
| |
| <pre> <activity name="EditContactActivity" |
| android:windowSoftInputMode="stateVisible|adjustResize"> |
| ... |
| </activity></pre> |
| |
| <p class="note"><strong>Note:</strong>Starting from Android 1.5 (API Level 3), |
| the platform offers a new method, |
| {@link android.view.Window#setSoftInputMode(int mode)}, |
| that non-Activity windows can use to control their behavior. Calling this method |
| in your will make your application incompatible with previous versions of the |
| Android platform.</p> |
| |
| <h4>Controlling the action buttons</h4> |
| |
| <p>The final customization we will look at is the "action" buttons in the IME. |
| There are currently two types of actions:</p> |
| |
| <ul> |
| <li>The enter key on a soft keyboard is typically bound to an action when not |
| operating on a mult-line edit text. For example, on the G1 pressing the hard |
| enter key will typically move to the next field or the application will |
| intercept it to execute an action; with a soft keyboard, this overloading of the |
| enter key remains, since the enter button just sends an enter key event.</li> |
| <li>When in fullscreen mode, an IME may also put an additional action button to |
| the right of the text being edited, giving the user quick access to a common |
| application operation.</li> |
| </ul> |
| |
| <p>These options are controlled with the <code>android:imeOptions</code> |
| attribute on <code>TextView</code>. The value you supply here can be any |
| combination of:</p> |
| |
| <ul> |
| <li>One of the pre-defined action constants (<code>actionGo</code>, |
| <code>actionSearch</code>, <code>actionSend</code>, <code>actionNext</code>, |
| <code>actionDone</code>). If none of these are specified, the system will infer |
| either <code>actionNext</code> or <code>actionDone</code> depending on whether |
| there is a focusable field after this one; you can explicitly force no action |
| with <code>actionNone</code>.</li> |
| <li>The <code>flagNoEnterAction</code> option tells the IME that the action |
| should <em>not</em> be available on the enter key, even if the text itself is |
| not multi-line. This avoids having unrecoverable actions like (send) that can be |
| accidentally touched by the user while typing.</li> |
| <li>The <code>flagNoAccessoryAction</code> removes the action button from the |
| text area, leaving more room for text.</li><li>The <code>flagNoExtractUi</code> |
| completely removes the text area, allowing the application to be seen behind |
| it.</li> |
| </ul> |
| |
| <p>The previous IM application message view also provides an example of an |
| interesting use of <code>imeOptions</code>, to specify the send action but not |
| let it be shown on the enter key:</p> |
| |
| <pre>android:imeOptions="actionSend|flagNoEnterAction"</pre> |
| |
| <h3>APIs for controlling IMEs</h3> |
| |
| <p>For more advanced control over the IME, there are a variety of new APIs you |
| can use. Unless special care is taken (such as by using reflection), using these |
| APIs will cause your application to be incompatible with previous versions of |
| Android, and you should make sure you specify |
| <code>android:minSdkVersion="3"</code> in your manifest. For more information, |
| see the documentation for the <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a |
| > manifest element.</p> |
| |
| <p>The primary API is the new <code>android.view.inputmethod.InputMethodManager</code> class, which you can retrieve with <code>Context.getSystemService()</code>. |
| It allows you to interact with the global input method state, such as |
| explicitly hiding or showing the current IME's input area.</p> |
| |
| <p>There are also new window flags controlling input method interaction, which you can control through the existing <code>Window.addFlags()</code> method and new <code>Window.setSoftInputMode()</code> method. The <code>PopupWindow</code> |
| class has grown corresponding methods to control these options on its |
| window. One thing in particular to be aware of is the new <code>WindowManager.LayoutParams.FLAG_ALT_FOCUSABLE_IM</code> constant, which is used to control whether a window is on top of or behind the current IME.</p> |
| |
| <p>Most of the interaction between an active IME and application is done through the <code>android.view.inputmethod.InputConnection</code> |
| class. This is the API an application implement, which an IME calls to |
| perform the appropriate edit operations on the application. You won't |
| normally need to worry about this, since <code>TextView</code> provides its own implementation for itself.</p> |
| |
| <p>There are also a handful of new <code>View</code> APIs, the most important of these being<code> onCreateInputConnection()</code> which creates a new <code>InputConnection</code> for an IME (and fills in an <code>android.view.inputmethod.EditorInfo</code> |
| structure with your input type, IME options, and other data); again, |
| most developers won't need to worry about this, since TextView takes |
| care of it for you.</p> |