Dirk Dougherty | 22558d0 | 2009-12-10 16:25:06 -0800 | [diff] [blame] | 1 | page.title=Onscreen Input Methods |
Scott Main | 796ce77 | 2011-02-16 10:04:45 -0800 | [diff] [blame] | 2 | parent.title=Articles |
| 3 | parent.link=../browser.html?tag=article |
Dirk Dougherty | 22558d0 | 2009-12-10 16:25:06 -0800 | [diff] [blame] | 4 | @jd:body |
| 5 | |
| 6 | |
Scott Main | a225e3b | 2010-05-11 17:43:43 -0700 | [diff] [blame] | 7 | <div id="qv-wrapper"> |
| 8 | <div id="qv"> |
| 9 | |
| 10 | <h2>See also</h2> |
| 11 | <ol> |
| 12 | <li><a href="{@docRoot}resources/articles/creating-input-method.html">Creating an Input |
| 13 | Method</a></li> |
| 14 | <li><a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a></li> |
| 15 | </ol> |
| 16 | |
| 17 | </div> |
| 18 | </div> |
| 19 | |
| 20 | |
Dirk Dougherty | 22558d0 | 2009-12-10 16:25:06 -0800 | [diff] [blame] | 21 | <p>Starting from Android 1.5, the Android platform offers an Input Method |
| 22 | Framework (IMF) that lets you create on-screen input methods such as software |
| 23 | keyboards. This article provide an overview of what Android input method editors |
| 24 | (IMEs) are and what an application needs to do to work well with them. The IMF |
| 25 | is designed to support new classes of Android devices, such as those without |
| 26 | hardware keyboards, so it is important that your application works well with the |
| 27 | IMF and offers a great experience for users.</p> |
| 28 | |
| 29 | <h3>What is an input method?</h3> |
| 30 | |
| 31 | <p>The Android IMF is designed to support a variety of IMEs, including soft |
| 32 | keyboard, hand-writing recognizers, and hard keyboard translators. Our focus, |
| 33 | however, will be on soft keyboards, since this is the kind of input method that |
| 34 | is currently part of the platform.</p> |
| 35 | |
| 36 | <p>A user will usually access the current IME by tapping on a text view to |
| 37 | edit, as shown here in the home screen:</p> |
| 38 | |
| 39 | <img style="width: 320px; height: 480px; margin-right: 10px;" src="images/on-screen-inputs_004.png"> |
| 40 | <img style="width: 320px; height: 480px;" src="images/on-screen-inputs.png"> |
| 41 | |
| 42 | <p>The soft keyboard is positioned at the bottom of the screen over the |
| 43 | application's window. To organize the available space between the application |
| 44 | and IME, we use a few approaches; the one shown here is called <em>pan and |
| 45 | scan</em>, and simply involves scrolling the application window around so that |
| 46 | the currently focused view is visible. This is the default mode, since it is the |
| 47 | safest for existing applications.</p> |
| 48 | |
| 49 | <p>Most often the preferred screen layout is a <em>resize</em>, where the |
| 50 | application's window is resized to be entirely visible. An example is shown |
| 51 | here, when composing an e-mail message:</p> |
| 52 | |
| 53 | <img style="width: 320px; height: 480px; margin-right: 10px;" src="images/on-screen-inputs_005.png"> |
| 54 | <img style="width: 320px; height: 480px;" src="images/on-screen-inputs_003.png"> |
| 55 | |
| 56 | <p>The size of the application window is changed so that none of it is hidden by |
| 57 | the IME, allowing full access to both the application and IME. This of course |
| 58 | only works for applications that have a resizeable area that can be reduced to |
| 59 | make enough space, but the vertical space in this mode is actually no less than |
| 60 | what is available in landscape orientation, so very often an application can |
| 61 | already accommodate it.</p> |
| 62 | |
| 63 | <p>The final major mode is <em>fullscreen</em> or <em>extract</em> |
| 64 | mode. This is used when the IME is too large to reasonably share space |
| 65 | with the underlying application. With the standard IMEs, you will only |
| 66 | encounter this situation when the screen is in a landscape orientation, |
| 67 | although other IMEs are free to use it whenever they desire. In this |
| 68 | case the application window is left as-is, and the IME simply displays |
| 69 | fullscreen on top of it, as shown here:</p> |
| 70 | |
| 71 | <img style="width: 480px; height: 320px; margin-right: 10px; margin-bottom: 10px;" src="images/on-screen-inputs_006.png"> |
| 72 | <img style="width: 480px; height: 320px;" src="images/on-screen-inputs_002.png"> |
| 73 | |
| 74 | <p>Because the IME is covering the application, it has its own editing area, |
| 75 | which shows the text actually contained in the application. There are also some |
| 76 | limited opportunities the application has to customize parts of the IME (the |
| 77 | "done" button at the top and enter key label at the bottom) to improve the user |
| 78 | experience.</p> |
| 79 | |
| 80 | <h3>Basic XML attributes for controlling IMEs</h3> |
| 81 | |
| 82 | <p>There are a number of things the system does to try to help existing |
| 83 | applications work with IMEs as well as possible, such as:</p> |
| 84 | |
| 85 | <ul> |
| 86 | <li>Use pan and scan mode by default, unless it can reasonably guess that |
| 87 | resize mode will work by the existence of lists, scroll views, etc.</li> |
| 88 | <li>Analyze the various existing TextView attributes to guess at the kind of |
| 89 | content (numbers, plain text, etc) to help the soft keyboard display an |
| 90 | appropriate key layout.</li> |
| 91 | <li>Assign a few default actions to the fullscreen IME, such as "next field" |
| 92 | and "done".</li> |
| 93 | </ul> |
| 94 | |
| 95 | <p>There are also some simple things you can do in your application that will |
| 96 | often greatly improve its user experience. Except where explicitly mentioned, |
| 97 | these will work in any Android platform version, even those previous to Android |
| 98 | 1.5 (since they will simply ignore these new options).</p> |
| 99 | |
| 100 | <h4>Specifying each EditText control's input type</h4> |
| 101 | |
| 102 | <p>The most important thing for an application to do is to use the new |
| 103 | <code>android:inputType</code> |
| 104 | attribute on each <code>EditText</code>. The attribute provides much richer |
| 105 | information |
| 106 | about the text content. This attribute actually replaces many existing |
| 107 | attributes (<code>android:</code><code>password</code>, |
| 108 | <code>android:</code><code>singleLine</code>, |
| 109 | <code>android:</code><code>numeric</code>, |
| 110 | <code>android:</code><code>phoneNumber</code>, |
| 111 | <code>android:</code><code>capitalize</code>, |
| 112 | <code>android:</code><code>autoText</code>, and |
| 113 | <code>android:</code><code>editable</code>). If you specify the older attributes |
| 114 | and the new <code>android:inputType</code> attribute, the system uses |
| 115 | <code>android:inputType</code> and ignores the others. </p> |
| 116 | |
| 117 | <p>The <code>android:inputType</code> attribute has three pieces:</p> |
| 118 | |
| 119 | <ul> |
| 120 | <li>The <em>class</em> is the overall interpretation of characters. The |
| 121 | currently supported classes are <code>text</code> (plain text), |
| 122 | <code>number</code> (decimal number), <code>phone</code> (phone number), and |
| 123 | <code>datetime</code> (a date or time).</li> |
| 124 | <li>The <em>variation</em> is a further refinement on the class. In the |
| 125 | attribute you will normally specify the class and variant together, with the |
| 126 | class as a prefix. For example, <code>textEmailAddress</code> is a text field |
| 127 | where the user will enter something that is an e-mail address (foo@bar.com) so |
| 128 | the key layout will have an '@' character in easy access, and |
| 129 | <code>numberSigned</code> is a numeric field with a sign. If only the class is |
| 130 | specified, then you get the default/generic variant.</li> |
| 131 | <li>Additional <em>flags</em> can be specified that supply further refinement. |
| 132 | These flags are specific to a class. For example, some flags for the |
| 133 | <code>text</code> class are <code>textCapSentences</code>, |
| 134 | <code>textAutoCorrect</code>, and <code>textMultiline</code>.</li> |
| 135 | </ul> |
| 136 | |
| 137 | <p>As an example, here is the new EditText for the IM application's message text view:</p> |
| 138 | |
| 139 | <pre> <EditText android:id="@+id/edtInput" |
| 140 | android:layout_width="0dip" |
| 141 | android:layout_height="wrap_content" |
| 142 | android:layout_weight="1" |
| 143 | android:inputType="textShortMessage|textAutoCorrect|textCapSentences|textMultiLine" |
| 144 | android:imeOptions="actionSend|flagNoEnterAction" |
| 145 | android:maxLines="4" |
| 146 | android:maxLength="2000" |
| 147 | android:hint="@string/compose_hint"/></pre> |
| 148 | |
| 149 | <p>A full description of all of the input types can be found in the |
| 150 | documentation. It is important to make use of the correct input types that are |
| 151 | available, so that the soft keyboard can use the optimal keyboard layout for the |
| 152 | text the user will be entering.</p> |
| 153 | |
| 154 | <h4>Enabling resize mode and other window features</h4> |
| 155 | |
| 156 | <p>The second most important thing for your app to do is to specify the overall |
| 157 | behavior of your window in relation to the input method. The most visible aspect |
| 158 | of this is controlling resize vs. pan and scan mode, but there are other things |
| 159 | you can do as well to improve your user experience.</p> |
| 160 | |
| 161 | <p>You will usually control this behavior through the |
| 162 | <code>android:windowSoftInputMode</code> attribute on each |
| 163 | <code><activity></code> definition in your |
| 164 | <code>AndroidManifest.xml</code>. Like the input type, there are a couple |
| 165 | different pieces of data that can be specified here by combining them |
| 166 | together:</p> |
| 167 | |
| 168 | <ul> |
| 169 | <li>The window adjustment mode is specified with either |
| 170 | <code>adjustResize</code> or <code>adjustPan</code>. It is highly recommended |
| 171 | that you always specify one or the other.</li> |
| 172 | <li>You can further control whether the IME will be shown automatically when |
| 173 | your activity is displayed and other situations where the user moves to it. The |
| 174 | system won't automatically show an IME by default, but in some cases it can be |
| 175 | convenient for the user if an application enables this behavior. You can request |
| 176 | this with <code>stateVisible</code>. There are also a number of other state |
| 177 | options for finer-grained control that you can find in the documentation.</li> |
| 178 | </ul> |
| 179 | |
| 180 | <p>A typical example of this field can be see in the edit contact activity, |
| 181 | which ensures it is resized and automatically displays the IME for the user:</p> |
| 182 | |
| 183 | <pre> <activity name="EditContactActivity" |
| 184 | android:windowSoftInputMode="stateVisible|adjustResize"> |
| 185 | ... |
| 186 | </activity></pre> |
| 187 | |
| 188 | <p class="note"><strong>Note:</strong>Starting from Android 1.5 (API Level 3), |
| 189 | the platform offers a new method, |
| 190 | {@link android.view.Window#setSoftInputMode(int mode)}, |
| 191 | that non-Activity windows can use to control their behavior. Calling this method |
| 192 | in your will make your application incompatible with previous versions of the |
| 193 | Android platform.</p> |
| 194 | |
| 195 | <h4>Controlling the action buttons</h4> |
| 196 | |
| 197 | <p>The final customization we will look at is the "action" buttons in the IME. |
| 198 | There are currently two types of actions:</p> |
| 199 | |
| 200 | <ul> |
| 201 | <li>The enter key on a soft keyboard is typically bound to an action when not |
| 202 | operating on a mult-line edit text. For example, on the G1 pressing the hard |
| 203 | enter key will typically move to the next field or the application will |
| 204 | intercept it to execute an action; with a soft keyboard, this overloading of the |
| 205 | enter key remains, since the enter button just sends an enter key event.</li> |
| 206 | <li>When in fullscreen mode, an IME may also put an additional action button to |
| 207 | the right of the text being edited, giving the user quick access to a common |
| 208 | application operation.</li> |
| 209 | </ul> |
| 210 | |
| 211 | <p>These options are controlled with the <code>android:imeOptions</code> |
| 212 | attribute on <code>TextView</code>. The value you supply here can be any |
| 213 | combination of:</p> |
| 214 | |
| 215 | <ul> |
| 216 | <li>One of the pre-defined action constants (<code>actionGo</code>, |
| 217 | <code>actionSearch</code>, <code>actionSend</code>, <code>actionNext</code>, |
| 218 | <code>actionDone</code>). If none of these are specified, the system will infer |
| 219 | either <code>actionNext</code> or <code>actionDone</code> depending on whether |
| 220 | there is a focusable field after this one; you can explicitly force no action |
| 221 | with <code>actionNone</code>.</li> |
| 222 | <li>The <code>flagNoEnterAction</code> option tells the IME that the action |
| 223 | should <em>not</em> be available on the enter key, even if the text itself is |
| 224 | not multi-line. This avoids having unrecoverable actions like (send) that can be |
| 225 | accidentally touched by the user while typing.</li> |
| 226 | <li>The <code>flagNoAccessoryAction</code> removes the action button from the |
| 227 | text area, leaving more room for text.</li><li>The <code>flagNoExtractUi</code> |
| 228 | completely removes the text area, allowing the application to be seen behind |
| 229 | it.</li> |
| 230 | </ul> |
| 231 | |
| 232 | <p>The previous IM application message view also provides an example of an |
| 233 | interesting use of <code>imeOptions</code>, to specify the send action but not |
| 234 | let it be shown on the enter key:</p> |
| 235 | |
| 236 | <pre>android:imeOptions="actionSend|flagNoEnterAction"</pre> |
| 237 | |
| 238 | <h3>APIs for controlling IMEs</h3> |
| 239 | |
| 240 | <p>For more advanced control over the IME, there are a variety of new APIs you |
| 241 | can use. Unless special care is taken (such as by using reflection), using these |
| 242 | APIs will cause your application to be incompatible with previous versions of |
| 243 | Android, and you should make sure you specify |
| 244 | <code>android:minSdkVersion="3"</code> in your manifest. For more information, |
| 245 | see the documentation for the <a |
| 246 | href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a |
| 247 | > manifest element.</p> |
| 248 | |
| 249 | <p>The primary API is the new <code>android.view.inputmethod.InputMethodManager</code> class, which you can retrieve with <code>Context.getSystemService()</code>. |
| 250 | It allows you to interact with the global input method state, such as |
| 251 | explicitly hiding or showing the current IME's input area.</p> |
| 252 | |
| 253 | <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> |
| 254 | class has grown corresponding methods to control these options on its |
| 255 | 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> |
| 256 | |
| 257 | <p>Most of the interaction between an active IME and application is done through the <code>android.view.inputmethod.InputConnection</code> |
| 258 | class. This is the API an application implement, which an IME calls to |
| 259 | perform the appropriate edit operations on the application. You won't |
| 260 | normally need to worry about this, since <code>TextView</code> provides its own implementation for itself.</p> |
| 261 | |
| 262 | <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> |
| 263 | structure with your input type, IME options, and other data); again, |
| 264 | most developers won't need to worry about this, since TextView takes |
| 265 | care of it for you.</p> |