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