1/* 2 * Copyright (C) 2007-2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not 5 * use this file except in compliance with the License. You may obtain a copy of 6 * the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 13 * License for the specific language governing permissions and limitations under 14 * the License. 15 */ 16 17package android.view.inputmethod; 18 19import android.os.Bundle; 20import android.os.Handler; 21import android.view.KeyCharacterMap; 22import android.view.KeyEvent; 23 24/** 25 * The InputConnection interface is the communication channel from an 26 * {@link InputMethod} back to the application that is receiving its 27 * input. It is used to perform such things as reading text around the 28 * cursor, committing text to the text box, and sending raw key events 29 * to the application. 30 * 31 * <p>Starting from API Level {@link android.os.Build.VERSION_CODES#N}, 32 * the system can deal with the situation where the application directly 33 * implements this class but one or more of the following methods are 34 * not implemented.</p> 35 * <ul> 36 * <li>{@link #getSelectedText(int)}, which was introduced in 37 * {@link android.os.Build.VERSION_CODES#GINGERBREAD}.</li> 38 * <li>{@link #setComposingRegion(int, int)}, which was introduced 39 * in {@link android.os.Build.VERSION_CODES#GINGERBREAD}.</li> 40 * <li>{@link #commitCorrection(CorrectionInfo)}, which was introduced 41 * in {@link android.os.Build.VERSION_CODES#HONEYCOMB}.</li> 42 * <li>{@link #requestCursorUpdates(int)}, which was introduced in 43 * {@link android.os.Build.VERSION_CODES#LOLLIPOP}.</li> 44 * <li>{@link #deleteSurroundingTextInCodePoints(int, int)}}, which 45 * was introduced in {@link android.os.Build.VERSION_CODES#N}.</li> 46 * <li>{@link #getHandler()}}, which was introduced in 47 * {@link android.os.Build.VERSION_CODES#N}.</li> 48 * <li>{@link #closeConnection()}}, which was introduced in 49 * {@link android.os.Build.VERSION_CODES#N}.</li> 50 * </ul> 51 * 52 * <h3>Implementing an IME or an editor</h3> 53 * <p>Text input is the result of the synergy of two essential components: 54 * an Input Method Engine (IME) and an editor. The IME can be a 55 * software keyboard, a handwriting interface, an emoji palette, a 56 * speech-to-text engine, and so on. There are typically several IMEs 57 * installed on any given Android device. In Android, IMEs extend 58 * {@link android.inputmethodservice.InputMethodService}. 59 * For more information about how to create an IME, see the 60 * <a href="{@docRoot}guide/topics/text/creating-input-method.html"> 61 * Creating an input method</a> guide. 62 * 63 * The editor is the component that receives text and displays it. 64 * Typically, this is an {@link android.widget.EditText} instance, but 65 * some applications may choose to implement their own editor for 66 * various reasons. This is a large and complicated task, and an 67 * application that does this needs to make sure the behavior is 68 * consistent with standard EditText behavior in Android. An editor 69 * needs to interact with the IME, receiving commands through 70 * this InputConnection interface, and sending commands through 71 * {@link android.view.inputmethod.InputMethodManager}. An editor 72 * should start by implementing 73 * {@link android.view.View#onCreateInputConnection(EditorInfo)} 74 * to return its own input connection.</p> 75 * 76 * <p>If you are implementing your own IME, you will need to call the 77 * methods in this interface to interact with the application. Be sure 78 * to test your IME with a wide range of applications, including 79 * browsers and rich text editors, as some may have peculiarities you 80 * need to deal with. Remember your IME may not be the only source of 81 * changes on the text, and try to be as conservative as possible in 82 * the data you send and as liberal as possible in the data you 83 * receive.</p> 84 * 85 * <p>If you are implementing your own editor, you will probably need 86 * to provide your own subclass of {@link BaseInputConnection} to 87 * answer to the commands from IMEs. Please be sure to test your 88 * editor with as many IMEs as you can as their behavior can vary a 89 * lot. Also be sure to test with various languages, including CJK 90 * languages and right-to-left languages like Arabic, as these may 91 * have different input requirements. When in doubt about the 92 * behavior you should adopt for a particular call, please mimic the 93 * default TextView implementation in the latest Android version, and 94 * if you decide to drift from it, please consider carefully that 95 * inconsistencies in text editor behavior is almost universally felt 96 * as a bad thing by users.</p> 97 * 98 * <h3>Cursors, selections and compositions</h3> 99 * <p>In Android, the cursor and the selection are one and the same 100 * thing. A "cursor" is just the special case of a zero-sized 101 * selection. As such, this documentation uses them 102 * interchangeably. Any method acting "before the cursor" would act 103 * before the start of the selection if there is one, and any method 104 * acting "after the cursor" would act after the end of the 105 * selection.</p> 106 * 107 * <p>An editor needs to be able to keep track of a currently 108 * "composing" region, like the standard edition widgets do. The 109 * composition is marked in a specific style: see 110 * {@link android.text.Spanned#SPAN_COMPOSING}. IMEs use this to help 111 * the user keep track of what part of the text they are currently 112 * focusing on, and interact with the editor using 113 * {@link InputConnection#setComposingText(CharSequence, int)}, 114 * {@link InputConnection#setComposingRegion(int, int)} and 115 * {@link InputConnection#finishComposingText()}. 116 * The composing region and the selection are completely independent 117 * of each other, and the IME may use them however they see fit.</p> 118 */ 119public interface InputConnection { 120 /** 121 * Flag for use with {@link #getTextAfterCursor} and 122 * {@link #getTextBeforeCursor} to have style information returned 123 * along with the text. If not set, {@link #getTextAfterCursor} 124 * sends only the raw text, without style or other spans. If set, 125 * it may return a complex CharSequence of both text and style 126 * spans. <strong>Editor authors</strong>: you should strive to 127 * send text with styles if possible, but it is not required. 128 */ 129 static final int GET_TEXT_WITH_STYLES = 0x0001; 130 131 /** 132 * Flag for use with {@link #getExtractedText} to indicate you 133 * would like to receive updates when the extracted text changes. 134 */ 135 public static final int GET_EXTRACTED_TEXT_MONITOR = 0x0001; 136 137 /** 138 * Get <var>n</var> characters of text before the current cursor 139 * position. 140 * 141 * <p>This method may fail either if the input connection has 142 * become invalid (such as its process crashing) or the editor is 143 * taking too long to respond with the text (it is given a couple 144 * seconds to return). In either case, null is returned. This 145 * method does not affect the text in the editor in any way, nor 146 * does it affect the selection or composing spans.</p> 147 * 148 * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the 149 * editor should return a {@link android.text.SpannableString} 150 * with all the spans set on the text.</p> 151 * 152 * <p><strong>IME authors:</strong> please consider this will 153 * trigger an IPC round-trip that will take some time. Assume this 154 * method consumes a lot of time. Also, please keep in mind the 155 * Editor may choose to return less characters than requested even 156 * if they are available for performance reasons.</p> 157 * 158 * <p><strong>Editor authors:</strong> please be careful of race 159 * conditions in implementing this call. An IME can make a change 160 * to the text and use this method right away; you need to make 161 * sure the returned value is consistent with the result of the 162 * latest edits. Also, you may return less than n characters if performance 163 * dictates so, but keep in mind IMEs are relying on this for many 164 * functions: you should not, for example, limit the returned value to 165 * the current line, and specifically do not return 0 characters unless 166 * the cursor is really at the start of the text.</p> 167 * 168 * @param n The expected length of the text. 169 * @param flags Supplies additional options controlling how the text is 170 * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}. 171 * @return the text before the cursor position; the length of the 172 * returned text might be less than <var>n</var>. 173 */ 174 public CharSequence getTextBeforeCursor(int n, int flags); 175 176 /** 177 * Get <var>n</var> characters of text after the current cursor 178 * position. 179 * 180 * <p>This method may fail either if the input connection has 181 * become invalid (such as its process crashing) or the client is 182 * taking too long to respond with the text (it is given a couple 183 * seconds to return). In either case, null is returned. 184 * 185 * <p>This method does not affect the text in the editor in any 186 * way, nor does it affect the selection or composing spans.</p> 187 * 188 * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the 189 * editor should return a {@link android.text.SpannableString} 190 * with all the spans set on the text.</p> 191 * 192 * <p><strong>IME authors:</strong> please consider this will 193 * trigger an IPC round-trip that will take some time. Assume this 194 * method consumes a lot of time.</p> 195 * 196 * <p><strong>Editor authors:</strong> please be careful of race 197 * conditions in implementing this call. An IME can make a change 198 * to the text and use this method right away; you need to make 199 * sure the returned value is consistent with the result of the 200 * latest edits. Also, you may return less than n characters if performance 201 * dictates so, but keep in mind IMEs are relying on this for many 202 * functions: you should not, for example, limit the returned value to 203 * the current line, and specifically do not return 0 characters unless 204 * the cursor is really at the end of the text.</p> 205 * 206 * @param n The expected length of the text. 207 * @param flags Supplies additional options controlling how the text is 208 * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}. 209 * 210 * @return the text after the cursor position; the length of the 211 * returned text might be less than <var>n</var>. 212 */ 213 public CharSequence getTextAfterCursor(int n, int flags); 214 215 /** 216 * Gets the selected text, if any. 217 * 218 * <p>This method may fail if either the input connection has 219 * become invalid (such as its process crashing) or the client is 220 * taking too long to respond with the text (it is given a couple 221 * of seconds to return). In either case, null is returned.</p> 222 * 223 * <p>This method must not cause any changes in the editor's 224 * state.</p> 225 * 226 * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the 227 * editor should return a {@link android.text.SpannableString} 228 * with all the spans set on the text.</p> 229 * 230 * <p><strong>IME authors:</strong> please consider this will 231 * trigger an IPC round-trip that will take some time. Assume this 232 * method consumes a lot of time.</p> 233 * 234 * <p><strong>Editor authors:</strong> please be careful of race 235 * conditions in implementing this call. An IME can make a change 236 * to the text or change the selection position and use this 237 * method right away; you need to make sure the returned value is 238 * consistent with the results of the latest edits.</p> 239 * 240 * @param flags Supplies additional options controlling how the text is 241 * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}. 242 * @return the text that is currently selected, if any, or null if 243 * no text is selected. In {@link android.os.Build.VERSION_CODES#N} and 244 * later, returns false when the target application does not implement 245 * this method. 246 */ 247 public CharSequence getSelectedText(int flags); 248 249 /** 250 * Retrieve the current capitalization mode in effect at the 251 * current cursor position in the text. See 252 * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode} 253 * for more information. 254 * 255 * <p>This method may fail either if the input connection has 256 * become invalid (such as its process crashing) or the client is 257 * taking too long to respond with the text (it is given a couple 258 * seconds to return). In either case, 0 is returned.</p> 259 * 260 * <p>This method does not affect the text in the editor in any 261 * way, nor does it affect the selection or composing spans.</p> 262 * 263 * <p><strong>Editor authors:</strong> please be careful of race 264 * conditions in implementing this call. An IME can change the 265 * cursor position and use this method right away; you need to make 266 * sure the returned value is consistent with the results of the 267 * latest edits and changes to the cursor position.</p> 268 * 269 * @param reqModes The desired modes to retrieve, as defined by 270 * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}. These 271 * constants are defined so that you can simply pass the current 272 * {@link EditorInfo#inputType TextBoxAttribute.contentType} value 273 * directly in to here. 274 * @return the caps mode flags that are in effect at the current 275 * cursor position. See TYPE_TEXT_FLAG_CAPS_* in {@link android.text.InputType}. 276 */ 277 public int getCursorCapsMode(int reqModes); 278 279 /** 280 * Retrieve the current text in the input connection's editor, and 281 * monitor for any changes to it. This function returns with the 282 * current text, and optionally the input connection can send 283 * updates to the input method when its text changes. 284 * 285 * <p>This method may fail either if the input connection has 286 * become invalid (such as its process crashing) or the client is 287 * taking too long to respond with the text (it is given a couple 288 * seconds to return). In either case, null is returned.</p> 289 * 290 * <p>Editor authors: as a general rule, try to comply with the 291 * fields in <code>request</code> for how many chars to return, 292 * but if performance or convenience dictates otherwise, please 293 * feel free to do what is most appropriate for your case. Also, 294 * if the 295 * {@link #GET_EXTRACTED_TEXT_MONITOR} flag is set, you should be 296 * calling 297 * {@link InputMethodManager#updateExtractedText(View, int, ExtractedText)} 298 * whenever you call 299 * {@link InputMethodManager#updateSelection(View, int, int, int, int)}.</p> 300 * 301 * @param request Description of how the text should be returned. 302 * {@link android.view.inputmethod.ExtractedTextRequest} 303 * @param flags Additional options to control the client, either 0 or 304 * {@link #GET_EXTRACTED_TEXT_MONITOR}. 305 306 * @return an {@link android.view.inputmethod.ExtractedText} 307 * object describing the state of the text view and containing the 308 * extracted text itself, or null if the input connection is no 309 * longer valid of the editor can't comply with the request for 310 * some reason. 311 */ 312 public ExtractedText getExtractedText(ExtractedTextRequest request, 313 int flags); 314 315 /** 316 * Delete <var>beforeLength</var> characters of text before the 317 * current cursor position, and delete <var>afterLength</var> 318 * characters of text after the current cursor position, excluding 319 * the selection. Before and after refer to the order of the 320 * characters in the string, not to their visual representation: 321 * this means you don't have to figure out the direction of the 322 * text and can just use the indices as-is. 323 * 324 * <p>The lengths are supplied in Java chars, not in code points 325 * or in glyphs.</p> 326 * 327 * <p>Since this method only operates on text before and after the 328 * selection, it can't affect the contents of the selection. This 329 * may affect the composing span if the span includes characters 330 * that are to be deleted, but otherwise will not change it. If 331 * some characters in the composing span are deleted, the 332 * composing span will persist but get shortened by however many 333 * chars inside it have been removed.</p> 334 * 335 * <p><strong>IME authors:</strong> please be careful not to 336 * delete only half of a surrogate pair. Also take care not to 337 * delete more characters than are in the editor, as that may have 338 * ill effects on the application. Calling this method will cause 339 * the editor to call 340 * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 341 * on your service after the batch input is over.</p> 342 * 343 * <p><strong>Editor authors:</strong> please be careful of race 344 * conditions in implementing this call. An IME can make a change 345 * to the text or change the selection position and use this 346 * method right away; you need to make sure the effects are 347 * consistent with the results of the latest edits. Also, although 348 * the IME should not send lengths bigger than the contents of the 349 * string, you should check the values for overflows and trim the 350 * indices to the size of the contents to avoid crashes. Since 351 * this changes the contents of the editor, you need to make the 352 * changes known to the input method by calling 353 * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 354 * but be careful to wait until the batch edit is over if one is 355 * in progress.</p> 356 * 357 * @param beforeLength The number of characters before the cursor to be deleted, in code unit. 358 * If this is greater than the number of existing characters between the beginning of the 359 * text and the cursor, then this method does not fail but deletes all the characters in 360 * that range. 361 * @param afterLength The number of characters after the cursor to be deleted, in code unit. 362 * If this is greater than the number of existing characters between the cursor and 363 * the end of the text, then this method does not fail but deletes all the characters in 364 * that range. 365 * @return true on success, false if the input connection is no longer valid. 366 */ 367 public boolean deleteSurroundingText(int beforeLength, int afterLength); 368 369 /** 370 * A variant of {@link #deleteSurroundingText(int, int)}. Major differences are: 371 * 372 * <ul> 373 * <li>The lengths are supplied in code points, not in Java chars or in glyphs.</> 374 * <li>This method does nothing if there are one or more invalid surrogate pairs in the 375 * requested range.</li> 376 * </ul> 377 * 378 * <p><strong>Editor authors:</strong> In addition to the requirement in 379 * {@link #deleteSurroundingText(int, int)}, make sure to do nothing when one ore more invalid 380 * surrogate pairs are found in the requested range.</p> 381 * 382 * @see #deleteSurroundingText(int, int) 383 * 384 * @param beforeLength The number of characters before the cursor to be deleted, in code points. 385 * If this is greater than the number of existing characters between the beginning of the 386 * text and the cursor, then this method does not fail but deletes all the characters in 387 * that range. 388 * @param afterLength The number of characters after the cursor to be deleted, in code points. 389 * If this is greater than the number of existing characters between the cursor and 390 * the end of the text, then this method does not fail but deletes all the characters in 391 * that range. 392 * @return true on success, false if the input connection is no longer valid. Returns 393 * {@code false} when the target application does not implement this method. 394 */ 395 public boolean deleteSurroundingTextInCodePoints(int beforeLength, int afterLength); 396 397 /** 398 * Replace the currently composing text with the given text, and 399 * set the new cursor position. Any composing text set previously 400 * will be removed automatically. 401 * 402 * <p>If there is any composing span currently active, all 403 * characters that it comprises are removed. The passed text is 404 * added in its place, and a composing span is added to this 405 * text. If there is no composing span active, the passed text is 406 * added at the cursor position (removing selected characters 407 * first if any), and a composing span is added on the new text. 408 * Finally, the cursor is moved to the location specified by 409 * <code>newCursorPosition</code>.</p> 410 * 411 * <p>This is usually called by IMEs to add or remove or change 412 * characters in the composing span. Calling this method will 413 * cause the editor to call 414 * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 415 * on the current IME after the batch input is over.</p> 416 * 417 * <p><strong>Editor authors:</strong> please keep in mind the 418 * text may be very similar or completely different than what was 419 * in the composing span at call time, or there may not be a 420 * composing span at all. Please note that although it's not 421 * typical use, the string may be empty. Treat this normally, 422 * replacing the currently composing text with an empty string. 423 * Also, be careful with the cursor position. IMEs rely on this 424 * working exactly as described above. Since this changes the 425 * contents of the editor, you need to make the changes known to 426 * the input method by calling 427 * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 428 * but be careful to wait until the batch edit is over if one is 429 * in progress. Note that this method can set the cursor position 430 * on either edge of the composing text or entirely outside it, 431 * but the IME may also go on to move the cursor position to 432 * within the composing text in a subsequent call so you should 433 * make no assumption at all: the composing text and the selection 434 * are entirely independent.</p> 435 * 436 * @param text The composing text with styles if necessary. If no style 437 * object attached to the text, the default style for composing text 438 * is used. See {@link android.text.Spanned} for how to attach style 439 * object to the text. {@link android.text.SpannableString} and 440 * {@link android.text.SpannableStringBuilder} are two 441 * implementations of the interface {@link android.text.Spanned}. 442 * @param newCursorPosition The new cursor position around the text. If 443 * > 0, this is relative to the end of the text - 1; if <= 0, this 444 * is relative to the start of the text. So a value of 1 will 445 * always advance you to the position after the full text being 446 * inserted. Note that this means you can't position the cursor 447 * within the text, because the editor can make modifications to 448 * the text you are providing so it is not possible to correctly 449 * specify locations there. 450 * @return true on success, false if the input connection is no longer 451 * valid. 452 */ 453 public boolean setComposingText(CharSequence text, int newCursorPosition); 454 455 /** 456 * Mark a certain region of text as composing text. If there was a 457 * composing region, the characters are left as they were and the 458 * composing span removed, as if {@link #finishComposingText()} 459 * has been called. The default style for composing text is used. 460 * 461 * <p>The passed indices are clipped to the contents bounds. If 462 * the resulting region is zero-sized, no region is marked and the 463 * effect is the same as that of calling {@link #finishComposingText()}. 464 * The order of start and end is not important. In effect, the 465 * region from start to end and the region from end to start is 466 * the same. Editor authors, be ready to accept a start that is 467 * greater than end.</p> 468 * 469 * <p>Since this does not change the contents of the text, editors should not call 470 * {@link InputMethodManager#updateSelection(View, int, int, int, int)} and 471 * IMEs should not receive 472 * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}. 473 * </p> 474 * 475 * <p>This has no impact on the cursor/selection position. It may 476 * result in the cursor being anywhere inside or outside the 477 * composing region, including cases where the selection and the 478 * composing region overlap partially or entirely.</p> 479 * 480 * @param start the position in the text at which the composing region begins 481 * @param end the position in the text at which the composing region ends 482 * @return true on success, false if the input connection is no longer 483 * valid. In {@link android.os.Build.VERSION_CODES#N} and later, false is returned when the 484 * target application does not implement this method. 485 */ 486 public boolean setComposingRegion(int start, int end); 487 488 /** 489 * Have the text editor finish whatever composing text is 490 * currently active. This simply leaves the text as-is, removing 491 * any special composing styling or other state that was around 492 * it. The cursor position remains unchanged. 493 * 494 * <p><strong>IME authors:</strong> be aware that this call may be 495 * expensive with some editors.</p> 496 * 497 * <p><strong>Editor authors:</strong> please note that the cursor 498 * may be anywhere in the contents when this is called, including 499 * in the middle of the composing span or in a completely 500 * unrelated place. It must not move.</p> 501 * 502 * @return true on success, false if the input connection 503 * is no longer valid. 504 */ 505 public boolean finishComposingText(); 506 507 /** 508 * Commit text to the text box and set the new cursor position. 509 * 510 * <p>This method removes the contents of the currently composing 511 * text and replaces it with the passed CharSequence, and then 512 * moves the cursor according to {@code newCursorPosition}. If there 513 * is no composing text when this method is called, the new text is 514 * inserted at the cursor position, removing text inside the selection 515 * if any. This behaves like calling 516 * {@link #setComposingText(CharSequence, int) setComposingText(text, newCursorPosition)} 517 * then {@link #finishComposingText()}.</p> 518 * 519 * <p>Calling this method will cause the editor to call 520 * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 521 * on the current IME after the batch input is over. 522 * <strong>Editor authors</strong>, for this to happen you need to 523 * make the changes known to the input method by calling 524 * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 525 * but be careful to wait until the batch edit is over if one is 526 * in progress.</p> 527 * 528 * @param text The text to commit. This may include styles. 529 * @param newCursorPosition The new cursor position around the text, 530 * in Java characters. If > 0, this is relative to the end 531 * of the text - 1; if <= 0, this is relative to the start 532 * of the text. So a value of 1 will always advance the cursor 533 * to the position after the full text being inserted. Note that 534 * this means you can't position the cursor within the text, 535 * because the editor can make modifications to the text 536 * you are providing so it is not possible to correctly specify 537 * locations there. 538 * @return true on success, false if the input connection is no longer 539 * valid. 540 */ 541 public boolean commitText(CharSequence text, int newCursorPosition); 542 543 /** 544 * Commit a completion the user has selected from the possible ones 545 * previously reported to {@link InputMethodSession#displayCompletions 546 * InputMethodSession#displayCompletions(CompletionInfo[])} or 547 * {@link InputMethodManager#displayCompletions 548 * InputMethodManager#displayCompletions(View, CompletionInfo[])}. 549 * This will result in the same behavior as if the user had 550 * selected the completion from the actual UI. In all other 551 * respects, this behaves like {@link #commitText(CharSequence, int)}. 552 * 553 * <p><strong>IME authors:</strong> please take care to send the 554 * same object that you received through 555 * {@link android.inputmethodservice.InputMethodService#onDisplayCompletions(CompletionInfo[])}. 556 * </p> 557 * 558 * <p><strong>Editor authors:</strong> if you never call 559 * {@link InputMethodSession#displayCompletions(CompletionInfo[])} or 560 * {@link InputMethodManager#displayCompletions(View, CompletionInfo[])} then 561 * a well-behaved IME should never call this on your input 562 * connection, but be ready to deal with misbehaving IMEs without 563 * crashing.</p> 564 * 565 * <p>Calling this method (with a valid {@link CompletionInfo} object) 566 * will cause the editor to call 567 * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 568 * on the current IME after the batch input is over. 569 * <strong>Editor authors</strong>, for this to happen you need to 570 * make the changes known to the input method by calling 571 * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 572 * but be careful to wait until the batch edit is over if one is 573 * in progress.</p> 574 * 575 * @param text The committed completion. 576 * @return true on success, false if the input connection is no longer 577 * valid. 578 */ 579 public boolean commitCompletion(CompletionInfo text); 580 581 /** 582 * Commit a correction automatically performed on the raw user's input. A 583 * typical example would be to correct typos using a dictionary. 584 * 585 * <p>Calling this method will cause the editor to call 586 * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 587 * on the current IME after the batch input is over. 588 * <strong>Editor authors</strong>, for this to happen you need to 589 * make the changes known to the input method by calling 590 * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 591 * but be careful to wait until the batch edit is over if one is 592 * in progress.</p> 593 * 594 * @param correctionInfo Detailed information about the correction. 595 * @return true on success, false if the input connection is no longer valid. 596 * In {@link android.os.Build.VERSION_CODES#N} and later, returns false 597 * when the target application does not implement this method. 598 */ 599 public boolean commitCorrection(CorrectionInfo correctionInfo); 600 601 /** 602 * Set the selection of the text editor. To set the cursor 603 * position, start and end should have the same value. 604 * 605 * <p>Since this moves the cursor, calling this method will cause 606 * the editor to call 607 * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 608 * on the current IME after the batch input is over. 609 * <strong>Editor authors</strong>, for this to happen you need to 610 * make the changes known to the input method by calling 611 * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 612 * but be careful to wait until the batch edit is over if one is 613 * in progress.</p> 614 * 615 * <p>This has no effect on the composing region which must stay 616 * unchanged. The order of start and end is not important. In 617 * effect, the region from start to end and the region from end to 618 * start is the same. Editor authors, be ready to accept a start 619 * that is greater than end.</p> 620 * 621 * @param start the character index where the selection should start. 622 * @param end the character index where the selection should end. 623 * @return true on success, false if the input connection is no longer 624 * valid. 625 */ 626 public boolean setSelection(int start, int end); 627 628 /** 629 * Have the editor perform an action it has said it can do. 630 * 631 * <p>This is typically used by IMEs when the user presses the key 632 * associated with the action.</p> 633 * 634 * @param editorAction This must be one of the action constants for 635 * {@link EditorInfo#imeOptions EditorInfo.editorType}, such as 636 * {@link EditorInfo#IME_ACTION_GO EditorInfo.EDITOR_ACTION_GO}. 637 * @return true on success, false if the input connection is no longer 638 * valid. 639 */ 640 public boolean performEditorAction(int editorAction); 641 642 /** 643 * Perform a context menu action on the field. The given id may be one of: 644 * {@link android.R.id#selectAll}, 645 * {@link android.R.id#startSelectingText}, {@link android.R.id#stopSelectingText}, 646 * {@link android.R.id#cut}, {@link android.R.id#copy}, 647 * {@link android.R.id#paste}, {@link android.R.id#copyUrl}, 648 * or {@link android.R.id#switchInputMethod} 649 */ 650 public boolean performContextMenuAction(int id); 651 652 /** 653 * Tell the editor that you are starting a batch of editor 654 * operations. The editor will try to avoid sending you updates 655 * about its state until {@link #endBatchEdit} is called. Batch 656 * edits nest. 657 * 658 * <p><strong>IME authors:</strong> use this to avoid getting 659 * calls to 660 * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 661 * corresponding to intermediate state. Also, use this to avoid 662 * flickers that may arise from displaying intermediate state. Be 663 * sure to call {@link #endBatchEdit} for each call to this, or 664 * you may block updates in the editor.</p> 665 * 666 * <p><strong>Editor authors:</strong> while a batch edit is in 667 * progress, take care not to send updates to the input method and 668 * not to update the display. IMEs use this intensively to this 669 * effect. Also please note that batch edits need to nest 670 * correctly.</p> 671 * 672 * @return true if a batch edit is now in progress, false otherwise. Since 673 * this method starts a batch edit, that means it will always return true 674 * unless the input connection is no longer valid. 675 */ 676 public boolean beginBatchEdit(); 677 678 /** 679 * Tell the editor that you are done with a batch edit previously 680 * initiated with {@link #beginBatchEdit}. This ends the latest 681 * batch only. 682 * 683 * <p><strong>IME authors:</strong> make sure you call this 684 * exactly once for each call to {@link #beginBatchEdit}.</p> 685 * 686 * <p><strong>Editor authors:</strong> please be careful about 687 * batch edit nesting. Updates still to be held back until the end 688 * of the last batch edit.</p> 689 * 690 * @return true if there is still a batch edit in progress after closing 691 * the latest one (in other words, if the nesting count is > 0), false 692 * otherwise or if the input connection is no longer valid. 693 */ 694 public boolean endBatchEdit(); 695 696 /** 697 * Send a key event to the process that is currently attached 698 * through this input connection. The event will be dispatched 699 * like a normal key event, to the currently focused view; this 700 * generally is the view that is providing this InputConnection, 701 * but due to the asynchronous nature of this protocol that can 702 * not be guaranteed and the focus may have changed by the time 703 * the event is received. 704 * 705 * <p>This method can be used to send key events to the 706 * application. For example, an on-screen keyboard may use this 707 * method to simulate a hardware keyboard. There are three types 708 * of standard keyboards, numeric (12-key), predictive (20-key) 709 * and ALPHA (QWERTY). You can specify the keyboard type by 710 * specify the device id of the key event.</p> 711 * 712 * <p>You will usually want to set the flag 713 * {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD} 714 * on all key event objects you give to this API; the flag will 715 * not be set for you.</p> 716 * 717 * <p>Note that it's discouraged to send such key events in normal 718 * operation; this is mainly for use with 719 * {@link android.text.InputType#TYPE_NULL} type text fields. Use 720 * the {@link #commitText} family of methods to send text to the 721 * application instead.</p> 722 * 723 * @param event The key event. 724 * @return true on success, false if the input connection is no longer 725 * valid. 726 * 727 * @see KeyEvent 728 * @see KeyCharacterMap#NUMERIC 729 * @see KeyCharacterMap#PREDICTIVE 730 * @see KeyCharacterMap#ALPHA 731 */ 732 public boolean sendKeyEvent(KeyEvent event); 733 734 /** 735 * Clear the given meta key pressed states in the given input 736 * connection. 737 * 738 * <p>This can be used by the IME to clear the meta key states set 739 * by a hardware keyboard with latched meta keys, if the editor 740 * keeps track of these.</p> 741 * 742 * @param states The states to be cleared, may be one or more bits as 743 * per {@link KeyEvent#getMetaState() KeyEvent.getMetaState()}. 744 * @return true on success, false if the input connection is no longer 745 * valid. 746 */ 747 public boolean clearMetaKeyStates(int states); 748 749 /** 750 * Called by the IME to tell the client when it switches between 751 * fullscreen and normal modes. This will normally be called for 752 * you by the standard implementation of 753 * {@link android.inputmethodservice.InputMethodService}. 754 * 755 * @return true on success, false if the input connection is no longer 756 * valid. 757 */ 758 public boolean reportFullscreenMode(boolean enabled); 759 760 /** 761 * API to send private commands from an input method to its 762 * connected editor. This can be used to provide domain-specific 763 * features that are only known between certain input methods and 764 * their clients. Note that because the InputConnection protocol 765 * is asynchronous, you have no way to get a result back or know 766 * if the client understood the command; you can use the 767 * information in {@link EditorInfo} to determine if a client 768 * supports a particular command. 769 * 770 * @param action Name of the command to be performed. This <em>must</em> 771 * be a scoped name, i.e. prefixed with a package name you own, so that 772 * different developers will not create conflicting commands. 773 * @param data Any data to include with the command. 774 * @return true if the command was sent (whether or not the 775 * associated editor understood it), false if the input connection is no longer 776 * valid. 777 */ 778 public boolean performPrivateCommand(String action, Bundle data); 779 780 /** 781 * The editor is requested to call 782 * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)} at 783 * once, as soon as possible, regardless of cursor/anchor position changes. This flag can be 784 * used together with {@link #CURSOR_UPDATE_MONITOR}. 785 */ 786 public static final int CURSOR_UPDATE_IMMEDIATE = 1 << 0; 787 788 /** 789 * The editor is requested to call 790 * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)} 791 * whenever cursor/anchor position is changed. To disable monitoring, call 792 * {@link InputConnection#requestCursorUpdates(int)} again with this flag off. 793 * <p> 794 * This flag can be used together with {@link #CURSOR_UPDATE_IMMEDIATE}. 795 * </p> 796 */ 797 public static final int CURSOR_UPDATE_MONITOR = 1 << 1; 798 799 /** 800 * Called by the input method to ask the editor for calling back 801 * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)} to 802 * notify cursor/anchor locations. 803 * 804 * @param cursorUpdateMode {@link #CURSOR_UPDATE_IMMEDIATE} and/or 805 * {@link #CURSOR_UPDATE_MONITOR}. Pass {@code 0} to disable the effect of 806 * {@link #CURSOR_UPDATE_MONITOR}. 807 * @return {@code true} if the request is scheduled. {@code false} to indicate that when the 808 * application will not call 809 * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)}. 810 * In {@link android.os.Build.VERSION_CODES#N} and later, returns {@code false} also when the 811 * target application does not implement this method. 812 */ 813 public boolean requestCursorUpdates(int cursorUpdateMode); 814 815 /** 816 * Called by the {@link InputMethodManager} to enable application developers to specify a 817 * dedicated {@link Handler} on which incoming IPC method calls from input methods will be 818 * dispatched. 819 * 820 * <p>Note: This does nothing when called from input methods.</p> 821 * 822 * @return {@code null} to use the default {@link Handler}. 823 */ 824 public Handler getHandler(); 825 826 /** 827 * Called by the system up to only once to notify that the system is about to invalidate 828 * connection between the input method and the application. 829 * 830 * <p><strong>Editor authors</strong>: You can clear all the nested batch edit right now and 831 * you no longer need to handle subsequent callbacks on this connection, including 832 * {@link #beginBatchEdit()}}. Note that although the system tries to call this method whenever 833 * possible, there may be a chance that this method is not called in some exceptional 834 * situations.</p> 835 * 836 * <p>Note: This does nothing when called from input methods.</p> 837 */ 838 public void closeConnection(); 839} 840