1 page.title=Onscreen Input Methods 2 parent.title=Articles 3 parent.link=../browser.html?tag=article 4 @jd:body 5 6 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 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 (a] 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>
