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