1page.title=Creating an Input Method 2parent.title=Articles 3parent.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/on-screen-inputs.html">Onscreen Input Methods</a></li> 13 <li><a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a></li> 14 </ol> 15 16</div> 17</div> 18 19 20<p>To create an input method (IME) for entering text into text fields 21and other Views, you need to extend the {@link android.inputmethodservice.InputMethodService}. 22class. This class provides much of the basic implementation for an input 23method, in terms of managing the state and visibility of the input method and 24communicating with the currently visible activity.</p> 25 26<p>A good starting point would be the SoftKeyboard sample code provided as part 27of the SDK. You can modify the sample code to start building your own input 28method.</p> 29 30<p>An input method is packaged like any other application or service. In the 31<code>AndroidManifest.xml</code> file, you declare the input method as a 32service, with the appropriate intent filter and any associated meta data:</p> 33 34<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" 35 package="com.example.fastinput"> 36 37 <application android:label="@string/app_label"><br> 38 <!-- Declares the input method service --> 39 <service android:name="FastInputIME" 40 android:label="@string/fast_input_label" 41 android:permission="android.permission.BIND_INPUT_METHOD"> 42 <intent-filter> 43 <action android:name="android.view.InputMethod" /> 44 </intent-filter> 45 <meta-data android:name="android.view.im" android:resource="@xml/method" /> 46 </service> 47 48 <!-- Optional activities. A good idea to have some user settings. --> 49 <activity android:name="FastInputIMESettings" android:label="@string/fast_input_settings"> 50 <intent-filter> 51 <action android:name="android.intent.action.MAIN"/> 52 </intent-filter> 53 </activity> 54 </application> 55</manifest></pre> 56 57<p>If your input method allows the user to tweak some settings, you should 58provide a settings activity that can be launched from the Settings application. 59This is optional and you may choose to provide all user settings directly in 60your IME's UI.</p> 61 62<p>The typical life-cycle of an <code>InputMethodService</code> looks like 63this:</p> 64 65<p><img src="images/ime_003.png" style="border: medium none ; width: 374px; height: 871px;"></p> 66 67<h3>Visual Elements</h3> 68 69<p>There are two main visual elements for an input method—the input view and the 70candidates view. You don't have to follow this style though, if one of them is 71not relevant to your input method experience.</p> 72 73<h4>Input View</h4> 74 75<p>This is where the user can input text either in the form of keypresses, 76handwriting or other gestures. When the input method is displayed for the first 77time, <code>InputMethodService.onCreateInputView()</code> will be called. Create 78and return the view hierarchy that you would like to display in the input method 79window.</p> 80 81<h4>Candidates View</h4> 82 83<p>This is where potential word corrections or completions are presented to the 84user for selection. Again, this may or may not be relevant to your input method 85and you can return <code>null</code> from calls to 86<code>InputMethodService.onCreateCandidatesView()</code>, which is the default 87behavior.</p> 88 89<h3>Designing for the different Input Types</h3> 90 91<p>An application's text fields can have different input types specified on 92them, such as free form text, numeric, URL, email address and search. When you 93implement a new input method, you need to be aware of the different input types. 94Input methods are not automatically switched for different input types and so 95you need to support all types in your IME. However, the IME is not responsible 96for validating the input sent to the application. That's the responsibility of 97the application.</p> 98 99<p>For example, the LatinIME provided with the Android platform provides 100different layouts for text and phone number entry:</p> 101 102<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> 103 104<p><code>InputMethodService.onStartInputView()</code> is called with an<code> 105EditorInfo</code> object that contains details about the input type and other 106attributes of the application's text field.</p><p>(<code>EditorInfo.inputType 107& EditorInfo.TYPE_CLASS_MASK</code>) can be one of many different values, 108including:</p> 109 110<ul> 111<li><code>TYPE_CLASS_NUMBER</code></li> 112<li><code>TYPE_CLASS_DATETIME</code></li> 113<li><code>TYPE_CLASS_PHONE</code></li> 114<li><code>TYPE_CLASS_TEXT</code></li> 115</ul> 116 117<p>See <code>android.text.InputType</code> for more details.</p> 118 119<p><code>EditorInfo.inputType</code> can contain other masked bits that 120indicate the class variation and other flags. For example, 121<code>TYPE_TEXT_VARIATION_PASSWORD</code> or <code>TYPE_TEXT_VARIATION_URI</code> 122or <code>TYPE_TEXT_FLAG_AUTO_COMPLETE</code>.</p> 123 124<h4>Password fields</h4> 125 126<p>Pay 127specific attention when sending text to password fields. Make sure that 128the password is not visible within your UI — neither in the input 129view or the candidates view. Also, do not save the password anywhere without 130explicitly informing the user.</p> 131 132<h3>Landscape vs. portrait</h3> 133 134<p>The UI needs to be able to scale between landscape and portrait orientations. 135In non-fullscreen IME mode, leave sufficient space for the application to show 136the text field and any associated context. Preferably, no more than half the 137screen should be occupied by the IME. In fullscreen IME mode this is not an 138issue.</p> 139 140<h3>Sending text to the application</h3> 141 142<p>There are two ways to send text to the application. You can either send 143individual key events or you can edit the text around the cursor in the 144application's text field.</p> 145 146<p>To send a key event, you can simply construct KeyEvent objects and call 147<code>InputConnection.sendKeyEvent()</code>. Here are some examples:</p> 148 149<pre>InputConnection ic = getCurrentInputConnection(); 150long eventTime = SystemClock.uptimeMillis(); 151ic.sendKeyEvent(new KeyEvent(eventTime, eventTime, 152 KeyEvent.ACTION_DOWN, keyEventCode, 0, 0, 0, 0, 153 KeyEvent.FLAG_SOFT_KEYBOARD|KeyEvent.FLAG_KEEP_TOUCH_MODE)); 154ic.sendKeyEvent(new KeyEvent(SystemClock.uptimeMillis(), eventTime, 155 KeyEvent.ACTION_UP, keyEventCode, 0, 0, 0, 0, 156 KeyEvent.FLAG_SOFT_KEYBOARD|KeyEvent.FLAG_KEEP_TOUCH_MODE));</pre> 157 158<p>Or use the convenience method:</p> 159 160<pre>InputMethodService.sendDownUpKeyEvents(keyEventCode);</pre> 161 162<p class="note"><strong>Note</strong>: 163It is recommended to use the above method for certain fields such as 164phone number fields because of filters that may be applied to the text 165after each key press. Return key and delete key should also be sent as 166raw key events for certain input types, as applications may be watching 167for specific key events in order to perform an action.</p> 168 169<p>When editing text in a text field, some of the more useful methods on 170<code>android.view.inputmethod.InputConnection</code> are:</p> 171 172<ul> 173<li><code>getTextBeforeCursor()</code></li> 174<li><code>getTextAfterCursor()</code></li> 175<li><code>deleteSurroundingText()</code></li> 176<li><code>commitText()</code></li> 177</ul> 178 179<p>For example, let's say the text "Fell" is to the left of the cursor 180and you want to replace it with "Hello!":</p> 181 182<pre>InputConnection ic = getCurrentInputConnection(); 183ic.deleteSurroundingText(4, 0); 184ic.commitText("Hello", 1); 185ic.commitText("!", 1);</pre> 186 187<h4>Composing text before committing</h4> 188 189<p>If your input method does some kind of text prediction or requires multiple 190steps to compose a word or glyph, you can show the progress in the text field 191until the user commits the word and then you can replace the partial composition 192with the completed text. The text that is being composed will be highlighted in 193the text field in some fashion, such as an underline.</p> 194 195<pre>InputConnection ic = getCurrentInputConnection(); 196ic.setComposingText("Composi", 1); 197... 198ic.setComposingText("Composin", 1); 199... 200ic.commitText("Composing ", 1);</pre> 201 202<p><img style="width: 320px; height: 98px; margin-bottom: 10px;" src="images/ime_006.png"> 203<img style="width: 320px; height: 97px; margin-bottom: 10px;" src="images/ime_005.png"> 204<img style="width: 320px; height: 97px;" src="images/ime_004.png"></p> 205 206<h3>Intercepting hard key events</h3> 207 208<p>Even though the input method window doesn't have explicit focus, it receives 209hard key events first and can choose to consume them or forward them along to 210the application. For instance, you may want to consume the directional keys to 211navigate within your UI for candidate selection during composition. Or you may 212want to trap the back key to dismiss any popups originating from the input 213method window. To intercept hard keys, override 214<code>InputMethodService.onKeyDown()</code> and 215<code>InputMethodService.onKeyUp().</code> Remember to call 216<code>super.onKey</code>* if you don't want to consume a certain key 217yourself.</p> 218 219<h3>Other considerations</h3> 220 221<ul> 222<li>Provide a way for the user to easily bring up any associated settings 223directly from the input method UI</li> 224<li>Provide 225a way for the user to switch to a different input method (multiple 226input methods may be installed) directly from the input method UI.</li> 227<li>Bring 228up the UI quickly - preload or lazy-load any large resources so that 229the user sees the input method quickly on tapping on a text field. And 230cache any resources and views for subsequent invocations of the input 231method.</li> 232<li>On the flip side, any large memory allocations should 233be released soon after the input method window is hidden so that 234applications can have sufficient memory to run. Consider using a 235delayed message to release resources if the input method is in a hidden 236state for a few seconds.</li> 237<li>Make sure that most common characters 238can be entered using the input method, as users may use punctuation in 239passwords or user names and they shouldn't be stuck in a situation 240where they can't enter a certain character in order to gain access into 241a password-locked device.</li> 242</ul> 243 244<h3>Samples</h3> 245 246<p>For a real world example, with support for multiple input types and text 247prediction, see the <a id="ccpb" 248href="http://android.git.kernel.org/?p=platform/packages/inputmethods/LatinIME. 249git;a=tree" title="LatinIME source code online">LatinIME source code</a>. The 250Android SDK also includes a SoftKeyboard sample as well.</p> 251
