19066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/* 29066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Copyright (C) 2007-2008 The Android Open Source Project 3e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); you may not 59066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * use this file except in compliance with the License. You may obtain a copy of 69066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the License at 7e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 89066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 9e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Unless required by applicable law or agreed to in writing, software 119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * License for the specific language governing permissions and limitations under 149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the License. 159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpackage android.view.inputmethod; 189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.os.Bundle; 209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.view.KeyCharacterMap; 219066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectimport android.view.KeyEvent; 229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 239066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/** 249066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * The InputConnection interface is the communication channel from an 25e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethod} back to the application that is receiving its 26e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * input. It is used to perform such things as reading text around the 27e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * cursor, committing text to the text box, and sending raw key events 28e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * to the application. 29e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 30e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Applications should never directly implement this interface, but 31e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * instead subclass from {@link BaseInputConnection}. This will ensure 32e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * that the application does not break when new methods are added to 33e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the interface.</p> 34e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 35e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <h3>Implementing an IME or an editor</h3> 36e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Text input is the result of the synergy of two essential components: 37e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * an Input Method Engine (IME) and an editor. The IME can be a 38e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * software keyboard, a handwriting interface, an emoji palette, a 39e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * speech-to-text engine, and so on. There are typically several IMEs 40e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * installed on any given Android device. In Android, IMEs extend 41e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService}. 42e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * For more information about how to create an IME, see the 43e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <a href="{@docRoot}guide/topics/text/creating-input-method.html"> 44e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Creating an input method</a> guide. 45e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 46e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * The editor is the component that receives text and displays it. 47e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Typically, this is an {@link android.widget.EditText} instance, but 48e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * some applications may choose to implement their own editor for 49e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * various reasons. This is a large and complicated task, and an 50e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * application that does this needs to make sure the behavior is 51e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * consistent with standard EditText behavior in Android. An editor 52e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * needs to interact with the IME, receiving commands through 53e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * this InputConnection interface, and sending commands through 54e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.view.inputmethod.InputMethodManager}. An editor 55e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * should start by implementing 56e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.view.View#onCreateInputConnection(EditorInfo)} 57e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * to return its own input connection.</p> 58e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 59e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>If you are implementing your own IME, you will need to call the 60e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * methods in this interface to interact with the application. Be sure 61e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * to test your IME with a wide range of applications, including 62e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * browsers and rich text editors, as some may have peculiarities you 63e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * need to deal with. Remember your IME may not be the only source of 64e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * changes on the text, and try to be as conservative as possible in 65e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the data you send and as liberal as possible in the data you 66e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * receive.</p> 67e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 68e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>If you are implementing your own editor, you will probably need 69e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * to provide your own subclass of {@link BaseInputConnection} to 70e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * answer to the commands from IMEs. Please be sure to test your 71e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * editor with as many IMEs as you can as their behavior can vary a 72e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * lot. Also be sure to test with various languages, including CJK 73e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * languages and right-to-left languages like Arabic, as these may 74e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * have different input requirements. When in doubt about the 75e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * behavior you should adopt for a particular call, please mimic the 76e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * default TextView implementation in the latest Android version, and 77e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * if you decide to drift from it, please consider carefully that 78e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * inconsistencies in text edition behavior is almost universally felt 79e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * as a bad thing by users.</p> 80e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 81e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <h3>Cursors, selections and compositions</h3> 82e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>In Android, the cursor and the selection are one and the same 83e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * thing. A "cursor" is just the special case of a zero-sized 84e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * selection. As such, this documentation uses them 85e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * interchangeably. Any method acting "before the cursor" would act 86e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * before the start of the selection if there is one, and any method 87e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * acting "after the cursor" would act after the end of the 88e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * selection.</p> 89e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 90e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>An editor needs to be able to keep track of a currently 91e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * "composing" region, like the standard edition widgets do. The 92e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * composition is marked in a specific style: see 93e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.text.Spanned#SPAN_COMPOSING}. IMEs use this to help 94e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the user keep track of what part of the text they are currently 95e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * focusing on, and interact with the editor using 96e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputConnection#setComposingText(CharSequence, int)}, 97e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputConnection#setComposingRegion(int, int)} and 98e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputConnection#finishComposingText()}. 99e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * The composing region and the selection are completely independent 100e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * of each other, and the IME may use them however they see fit.</p> 1019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic interface InputConnection { 1039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Flag for use with {@link #getTextAfterCursor} and 105e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link #getTextBeforeCursor} to have style information returned 106e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * along with the text. If not set, {@link #getTextAfterCursor} 107e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * sends only the raw text, without style or other spans. If set, 108e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * it may return a complex CharSequence of both text and style 109e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * spans. <strong>Editor authors</strong>: you should strive to 110e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * send text with styles if possible, but it is not required. 1119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project static final int GET_TEXT_WITH_STYLES = 0x0001; 113e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 1149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 115e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Flag for use with {@link #getExtractedText} to indicate you 116e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * would like to receive updates when the extracted text changes. 1179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public static final int GET_EXTRACTED_TEXT_MONITOR = 0x0001; 119e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 1209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 121e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Get <var>n</var> characters of text before the current cursor 122e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * position. 123e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 124e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method may fail either if the input connection has 125e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * become invalid (such as its process crashing) or the editor is 126e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * taking too long to respond with the text (it is given a couple 127e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * seconds to return). In either case, null is returned. This 128e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * method does not affect the text in the editor in any way, nor 129e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * does it affect the selection or composing spans.</p> 130e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 131e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the 132e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * editor should return a {@link android.text.SpannableString} 133e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * with all the spans set on the text.</p> 134e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 135e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>IME authors:</strong> please consider this will 136e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * trigger an IPC round-trip that will take some time. Assume this 137e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * method consumes a lot of time. Also, please keep in mind the 138e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Editor may choose to return less characters than requested even 139e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * if they are available for performance reasons.</p> 140e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 141e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> please be careful of race 142e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * conditions in implementing this call. An IME can make a change 143e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * to the text and use this method right away; you need to make 144e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * sure the returned value is consistent with the result of the 145e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * latest edits. 146e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 1479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param n The expected length of the text. 1489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param flags Supplies additional options controlling how the text is 149e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}. 150e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return the text before the cursor position; the length of the 1519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * returned text might be less than <var>n</var>. 1529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1539066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public CharSequence getTextBeforeCursor(int n, int flags); 1549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1559066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 156e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Get <var>n</var> characters of text after the current cursor 157e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * position. 158e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 159e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method may fail either if the input connection has 160e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * become invalid (such as its process crashing) or the client is 161e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * taking too long to respond with the text (it is given a couple 162e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * seconds to return). In either case, null is returned. 163e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 164e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method does not affect the text in the editor in any 165e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * way, nor does it affect the selection or composing spans.</p> 166e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 167e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the 168e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * editor should return a {@link android.text.SpannableString} 169e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * with all the spans set on the text.</p> 170e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 171e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>IME authors:</strong> please consider this will 172e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * trigger an IPC round-trip that will take some time. Assume this 173e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * method consumes a lot of time.</p> 174e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 175e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> please be careful of race 176e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * conditions in implementing this call. An IME can make a change 177e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * to the text and use this method right away; you need to make 178e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * sure the returned value is consistent with the result of the 179e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * latest edits.</p> 180e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 1819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param n The expected length of the text. 1829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param flags Supplies additional options controlling how the text is 183e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}. 184e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 185e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return the text after the cursor position; the length of the 1869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * returned text might be less than <var>n</var>. 1879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public CharSequence getTextAfterCursor(int n, int flags); 1899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 191a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani * Gets the selected text, if any. 192a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani * 193e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method may fail if either the input connection has 194e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * become invalid (such as its process crashing) or the client is 195e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * taking too long to respond with the text (it is given a couple 196e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * of seconds to return). In either case, null is returned.</p> 197e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 198e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method must not cause any changes in the editor's 199e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * state.</p> 200e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 201e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the 202e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * editor should return a {@link android.text.SpannableString} 203e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * with all the spans set on the text.</p> 204e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 205e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>IME authors:</strong> please consider this will 206e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * trigger an IPC round-trip that will take some time. Assume this 207e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * method consumes a lot of time.</p> 208e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 209e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> please be careful of race 210e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * conditions in implementing this call. An IME can make a change 211e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * to the text or change the selection position and use this 212e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * method right away; you need to make sure the returned value is 213e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * consistent with the results of the latest edits.</p> 214a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani * 215a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani * @param flags Supplies additional options controlling how the text is 216e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}. 217e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return the text that is currently selected, if any, or null if 218a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani * no text is selected. 219a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani */ 220a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani public CharSequence getSelectedText(int flags); 221a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani 222a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani /** 223e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Retrieve the current capitalization mode in effect at the 224e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * current cursor position in the text. See 225e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode} 226e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * for more information. 227e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 228e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method may fail either if the input connection has 229e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * become invalid (such as its process crashing) or the client is 230e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * taking too long to respond with the text (it is given a couple 231e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * seconds to return). In either case, 0 is returned.</p> 232e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 233e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method does not affect the text in the editor in any 234e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * way, nor does it affect the selection or composing spans.</p> 235e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 236e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> please be careful of race 237e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * conditions in implementing this call. An IME can change the 238e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * cursor position and use this method right away; you need to make 239e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * sure the returned value is consistent with the results of the 240e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * latest edits and changes to the cursor position.</p> 241e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 2429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param reqModes The desired modes to retrieve, as defined by 243e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}. These 2449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * constants are defined so that you can simply pass the current 2459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link EditorInfo#inputType TextBoxAttribute.contentType} value 2469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * directly in to here. 247e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return the caps mode flags that are in effect at the current 248e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * cursor position. See TYPE_TEXT_FLAG_CAPS_* in {@link android.text.InputType}. 2499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public int getCursorCapsMode(int reqModes); 251e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 2529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 253e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Retrieve the current text in the input connection's editor, and 254e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * monitor for any changes to it. This function returns with the 255e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * current text, and optionally the input connection can send 256e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * updates to the input method when its text changes. 257e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 258e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method may fail either if the input connection has 259e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * become invalid (such as its process crashing) or the client is 260e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * taking too long to respond with the text (it is given a couple 261e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * seconds to return). In either case, null is returned.</p> 262e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 263e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Editor authors: as a general rule, try to comply with the 264e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * fields in <code>request</code> for how many chars to return, 265e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * but if performance or convenience dictates otherwise, please 266e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * feel free to do what is most appropriate for your case. Also, 267e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * if the 268e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link #GET_EXTRACTED_TEXT_MONITOR} flag is set, you should be 269e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * calling 270e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#updateExtractedText(View, int, ExtractedText)} 271e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * whenever you call 272e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#updateSelection(View, int, int, int, int)}.</p> 273e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 2749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param request Description of how the text should be returned. 275e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.view.inputmethod.ExtractedTextRequest} 2769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param flags Additional options to control the client, either 0 or 2779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link #GET_EXTRACTED_TEXT_MONITOR}. 278e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 279e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return an {@link android.view.inputmethod.ExtractedText} 280e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * object describing the state of the text view and containing the 281e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * extracted text itself, or null if the input connection is no 282e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * longer valid of the editor can't comply with the request for 283e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * some reason. 2849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 2859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public ExtractedText getExtractedText(ExtractedTextRequest request, 2869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project int flags); 2879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 2889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 289e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Delete <var>beforeLength</var> characters of text before the 290e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * current cursor position, and delete <var>afterLength</var> 291e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * characters of text after the current cursor position, excluding 292e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the selection. Before and after refer to the order of the 293e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * characters in the string, not to their visual representation: 294e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * this means you don't have to figure out the direction of the 295e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * text and can just use the indices as-is. 296e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 297e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>The lengths are supplied in Java chars, not in code points 298e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * or in glyphs.</p> 299e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 300e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Since this method only operates on text before and after the 301e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * selection, it can't affect the contents of the selection. This 302e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * may affect the composing span if the span includes characters 303e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * that are to be deleted, but otherwise will not change it. If 304e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * some characters in the composing span are deleted, the 305e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * composing span will persist but get shortened by however many 306e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * chars inside it have been removed.</p> 307e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 308e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>IME authors:</strong> please be careful not to 309e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * delete only half of a surrogate pair. Also take care not to 310e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * delete more characters than are in the editor, as that may have 311e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * ill effects on the application. Calling this method will cause 312e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the editor to call 313e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 314e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * on your service after the batch input is over.</p> 315e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 316e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> please be careful of race 317e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * conditions in implementing this call. An IME can make a change 318e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * to the text or change the selection position and use this 319e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * method right away; you need to make sure the effects are 320e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * consistent with the results of the latest edits. Also, although 321e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the IME should not send lengths bigger than the contents of the 322e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * string, you should check the values for overflows and trim the 323e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * indices to the size of the contents to avoid crashes. Since 324e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * this changes the contents of the editor, you need to make the 325e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * changes known to the input method by calling 326e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 327e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * but be careful to wait until the batch edit is over if one is 328e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * in progress.</p> 3290c95dd3f4f02564fab9b86a221bbcbb4aafc2981Fabrice Di Meglio * 3300c95dd3f4f02564fab9b86a221bbcbb4aafc2981Fabrice Di Meglio * @param beforeLength The number of characters to be deleted before the 3319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * current cursor position. 3320c95dd3f4f02564fab9b86a221bbcbb4aafc2981Fabrice Di Meglio * @param afterLength The number of characters to be deleted after the 3339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * current cursor position. 334e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 3359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * valid. 3369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3370c95dd3f4f02564fab9b86a221bbcbb4aafc2981Fabrice Di Meglio public boolean deleteSurroundingText(int beforeLength, int afterLength); 3389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 340e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Set composing text around the current cursor position with the 341e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * given text, and set the new cursor position. Any composing text 342e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * set previously will be removed automatically. 343e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 344e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>If there is any composing span currently active, all 345e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * characters that it comprises are removed. The passed text is 346e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * added in its place, and a composing span is added to this 347e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * text. Finally, the cursor is moved to the location specified by 348e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <code>newCursorPosition</code>.</p> 349e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 350e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This is usually called by IMEs to add or remove or change 351e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * characters in the composing span. Calling this method will 352e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * cause the editor to call 353e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 354e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * on the current IME after the batch input is over.</p> 355e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 356e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> please keep in mind the 357e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * text may be very similar or completely different than what was 358e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * in the composing span at call time, or there may not be a 359e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * composing span at all. Please note that although it's not 360e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * typical use, the string may be empty. Treat this normally, 361e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * replacing the currently composing text with an empty string. 362e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Also, be careful with the cursor position. IMEs rely on this 363e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * working exactly as described above. Since this changes the 364e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * contents of the editor, you need to make the changes known to 365e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the input method by calling 366e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 367e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * but be careful to wait until the batch edit is over if one is 368e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * in progress. Note that this method can set the cursor position 369e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * on either edge of the composing text or entirely outside it, 370e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * but the IME may also go on to move the cursor position to 371e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * within the composing text in a subsequent call so you should 372e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * make no assumption at all: the composing text and the selection 373e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * are entirely independent.</p> 374e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 3759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param text The composing text with styles if necessary. If no style 3769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * object attached to the text, the default style for composing text 377e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * is used. See {@link android.text.Spanned} for how to attach style 378e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * object to the text. {@link android.text.SpannableString} and 379e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.text.SpannableStringBuilder} are two 380e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * implementations of the interface {@link android.text.Spanned}. 381e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @param newCursorPosition The new cursor position around the text. If 3829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * > 0, this is relative to the end of the text - 1; if <= 0, this 383e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * is relative to the start of the text. So a value of 1 will 3849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * always advance you to the position after the full text being 385e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * inserted. Note that this means you can't position the cursor 3869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * within the text, because the editor can make modifications to 3879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the text you are providing so it is not possible to correctly 3889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * specify locations there. 389e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 3909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * valid. 3919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 3929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean setComposingText(CharSequence text, int newCursorPosition); 3939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 395e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Mark a certain region of text as composing text. If there was a 396e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * composing region, the characters are left as they were and the 397e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * composing span removed, as if {@link #finishComposingText()} 398e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * has been called. The default style for composing text is used. 399e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 400e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>The passed indices are clipped to the contents bounds. If 401e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the resulting region is zero-sized, no region is marked and the 402e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * effect is the same as that of calling {@link #finishComposingText()}. 403e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * The order of start and end is not important. In effect, the 404e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * region from start to end and the region from end to start is 405e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the same. Editor authors, be ready to accept a start that is 406e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * greater than end.</p> 407e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 408e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Since this does not change the contents of the text, editors should not call 409e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#updateSelection(View, int, int, int, int)} and 410e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * IMEs should not receive 411e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)}. 412e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * </p> 413e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 414e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This has no impact on the cursor/selection position. It may 415e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * result in the cursor being anywhere inside or outside the 416e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * composing region, including cases where the selection and the 417e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * composing region overlap partially or entirely.</p> 418a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani * 419a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani * @param start the position in the text at which the composing region begins 420a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani * @param end the position in the text at which the composing region ends 421e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 422a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani * valid. 423a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani */ 424a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani public boolean setComposingRegion(int start, int end); 425a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani 426a90b7f0125389b9e1040d2be82aad4ef74ea6071Amith Yamasani /** 427e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Have the text editor finish whatever composing text is 428e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * currently active. This simply leaves the text as-is, removing 429e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * any special composing styling or other state that was around 430e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * it. The cursor position remains unchanged. 431e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 432e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>IME authors:</strong> be aware that this call may be 433e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * expensive with some editors.</p> 434e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 435e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> please note that the cursor 436e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * may be anywhere in the contents when this is called, including 437e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * in the middle of the composing span or in a completely 438e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * unrelated place. It must not move.</p> 439e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 440e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection 441e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * is no longer valid. 4429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 4439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean finishComposingText(); 444e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 4459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Commit text to the text box and set the new cursor position. 447e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 448e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method removes the contents of the currently composing 449e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * text and replaces it with the passed CharSequence, and then 450e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * moves the cursor according to {@code newCursorPosition}. 451e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * This behaves like calling 452e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link #setComposingText(CharSequence, int) setComposingText(text, newCursorPosition)} 453e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * then {@link #finishComposingText()}.</p> 454e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 455e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Calling this method will cause the editor to call 456e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 457e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * on the current IME after the batch input is over. 458e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <strong>Editor authors</strong>, for this to happen you need to 459e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * make the changes known to the input method by calling 460e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 461e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * but be careful to wait until the batch edit is over if one is 462e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * in progress.</p> 463e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 464e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @param text The committed text. This may include styles. 465e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @param newCursorPosition The new cursor position around the text. If 4669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * > 0, this is relative to the end of the text - 1; if <= 0, this 467e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * is relative to the start of the text. So a value of 1 will 4689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * always advance you to the position after the full text being 469e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * inserted. Note that this means you can't position the cursor 4709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * within the text, because the editor can make modifications to 4719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * the text you are providing so it is not possible to correctly 4729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * specify locations there. 473e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 4749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * valid. 4759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 4769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean commitText(CharSequence text, int newCursorPosition); 4779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 4799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Commit a completion the user has selected from the possible ones 4809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * previously reported to {@link InputMethodSession#displayCompletions 481e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * InputMethodSession#displayCompletions(CompletionInfo[])} or 482e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#displayCompletions 483e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * InputMethodManager#displayCompletions(View, CompletionInfo[])}. 484e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * This will result in the same behavior as if the user had 485e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * selected the completion from the actual UI. In all other 486e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * respects, this behaves like {@link #commitText(CharSequence, int)}. 487e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 488e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>IME authors:</strong> please take care to send the 489e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * same object that you received through 490e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService#onDisplayCompletions(CompletionInfo[])}. 491e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * </p> 492e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 493e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> if you never call 494e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodSession#displayCompletions(CompletionInfo[])} or 495e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#displayCompletions(View, CompletionInfo[])} then 496e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * a well-behaved IME should never call this on your input 497e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * connection, but be ready to deal with misbehaving IMEs without 498e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * crashing.</p> 499e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 500e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Calling this method (with a valid {@link CompletionInfo} object) 501e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * will cause the editor to call 502e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 503e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * on the current IME after the batch input is over. 504e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <strong>Editor authors</strong>, for this to happen you need to 505e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * make the changes known to the input method by calling 506e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 507e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * but be careful to wait until the batch edit is over if one is 508e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * in progress.</p> 509e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 5109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param text The committed completion. 511e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 5129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * valid. 5139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean commitCompletion(CompletionInfo text); 5159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 517e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Commit a correction automatically performed on the raw user's input. A 518e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * typical example would be to correct typos using a dictionary. 519cf9cf2f40efc4ccf3f73e6fdb07725d9c00c4f91Gilles Debunne * 520e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Calling this method will cause the editor to call 521e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 522e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * on the current IME after the batch input is over. 523e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <strong>Editor authors</strong>, for this to happen you need to 524e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * make the changes known to the input method by calling 525e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 526e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * but be careful to wait until the batch edit is over if one is 527e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * in progress.</p> 528cf9cf2f40efc4ccf3f73e6fdb07725d9c00c4f91Gilles Debunne * 529e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @param correctionInfo Detailed information about the correction. 530e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer valid. 531cf9cf2f40efc4ccf3f73e6fdb07725d9c00c4f91Gilles Debunne */ 532cf9cf2f40efc4ccf3f73e6fdb07725d9c00c4f91Gilles Debunne public boolean commitCorrection(CorrectionInfo correctionInfo); 533cf9cf2f40efc4ccf3f73e6fdb07725d9c00c4f91Gilles Debunne 534cf9cf2f40efc4ccf3f73e6fdb07725d9c00c4f91Gilles Debunne /** 535e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Set the selection of the text editor. To set the cursor 536e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * position, start and end should have the same value. 537e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 538e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Since this moves the cursor, calling this method will cause 539e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the editor to call 540e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 541e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * on the current IME after the batch input is over. 542e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <strong>Editor authors</strong>, for this to happen you need to 543e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * make the changes known to the input method by calling 544e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link InputMethodManager#updateSelection(View, int, int, int, int)}, 545e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * but be careful to wait until the batch edit is over if one is 546e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * in progress.</p> 547e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 548e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This has no effect on the composing region which must stay 549e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * unchanged. The order of start and end is not important. In 550e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * effect, the region from start to end and the region from end to 551e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * start is the same. Editor authors, be ready to accept a start 552e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * that is greater than end.</p> 553e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 554e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @param start the character index where the selection should start. 555e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @param end the character index where the selection should end. 556e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 5579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * valid. 5589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean setSelection(int start, int end); 560e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 5619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 5629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Have the editor perform an action it has said it can do. 563e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 564e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This is typically used by IMEs when the user presses the key 565e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * associated with the action.</p> 566e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 5679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param editorAction This must be one of the action constants for 5689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link EditorInfo#imeOptions EditorInfo.editorType}, such as 5699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link EditorInfo#IME_ACTION_GO EditorInfo.EDITOR_ACTION_GO}. 570e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 5719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * valid. 5729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean performEditorAction(int editorAction); 574e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 5759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 576e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Perform a context menu action on the field. The given id may be one of: 5779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.R.id#selectAll}, 5789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.R.id#startSelectingText}, {@link android.R.id#stopSelectingText}, 5799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.R.id#cut}, {@link android.R.id#copy}, 5809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * {@link android.R.id#paste}, {@link android.R.id#copyUrl}, 5819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * or {@link android.R.id#switchInputMethod} 5829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 5839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean performContextMenuAction(int id); 584e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 5859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 586e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Tell the editor that you are starting a batch of editor 587e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * operations. The editor will try to avoid sending you updates 588e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * about its state until {@link #endBatchEdit} is called. Batch 589e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * edits nest. 590e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 591e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>IME authors:</strong> use this to avoid getting 592e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * calls to 593e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int, int, int)} 594e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * corresponding to intermediate state. Also, use this to avoid 595e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * flickers that may arise from displaying intermediate state. Be 596e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * sure to call {@link #endBatchEdit} for each call to this, or 597e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * you may block updates in the editor.</p> 598e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 599e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> while a batch edit is in 600e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * progress, take care not to send updates to the input method and 601e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * not to update the display. IMEs use this intensively to this 602e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * effect. Also please note that batch edits need to nest 603e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * correctly.</p> 604e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 605e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true if a batch edit is now in progress, false otherwise. Since 606e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * this method starts a batch edit, that means it will always return true 607e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * unless the input connection is no longer valid. 6089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 6099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean beginBatchEdit(); 610e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 6119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 6129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Tell the editor that you are done with a batch edit previously 613e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * initiated with {@link #beginBatchEdit}. This ends the latest 614e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * batch only. 615e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 616e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>IME authors:</strong> make sure you call this 617e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * exactly once for each call to {@link #beginBatchEdit}.</p> 618e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 619e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p><strong>Editor authors:</strong> please be careful about 620e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * batch edit nesting. Updates still to be held back until the end 621e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * of the last batch edit.</p> 622e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 623e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true if there is still a batch edit in progress after closing 624e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the latest one (in other words, if the nesting count is > 0), false 625e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * otherwise or if the input connection is no longer valid. 6269066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 6279066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean endBatchEdit(); 628e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 6299066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 630e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Send a key event to the process that is currently attached 631e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * through this input connection. The event will be dispatched 632e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * like a normal key event, to the currently focused view; this 633e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * generally is the view that is providing this InputConnection, 634e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * but due to the asynchronous nature of this protocol that can 635e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * not be guaranteed and the focus may have changed by the time 636e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the event is received. 637e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 638e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This method can be used to send key events to the 639e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * application. For example, an on-screen keyboard may use this 640e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * method to simulate a hardware keyboard. There are three types 641e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * of standard keyboards, numeric (12-key), predictive (20-key) 642e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * and ALPHA (QWERTY). You can specify the keyboard type by 643e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * specify the device id of the key event.</p> 644e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 645e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>You will usually want to set the flag 646e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD} 647e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * on all key event objects you give to this API; the flag will 648e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * not be set for you.</p> 649e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 650e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>Note that it's discouraged to send such key events in normal 651e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * operation; this is mainly for use with 652e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.text.InputType#TYPE_NULL} type text fields. Use 653e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * the {@link #commitText} family of methods to send text to the 654e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * application instead.</p> 655e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 6569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param event The key event. 657e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 6589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * valid. 659e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 6609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see KeyEvent 6619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see KeyCharacterMap#NUMERIC 6629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see KeyCharacterMap#PREDICTIVE 6639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @see KeyCharacterMap#ALPHA 6649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 6659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean sendKeyEvent(KeyEvent event); 6669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 6679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 668e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Clear the given meta key pressed states in the given input 669e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * connection. 670e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 671e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * <p>This can be used by the IME to clear the meta key states set 672e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * by a hardware keyboard with latched meta keys, if the editor 673e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * keeps track of these.</p> 674e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 6759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param states The states to be cleared, may be one or more bits as 6769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * per {@link KeyEvent#getMetaState() KeyEvent.getMetaState()}. 677e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 6789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * valid. 6799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 6809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean clearMetaKeyStates(int states); 681e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 6829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 683e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * Called by the IME to tell the client when it switches between 684e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * fullscreen and normal modes. This will normally be called for 685e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * you by the standard implementation of 686e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * {@link android.inputmethodservice.InputMethodService}. 687e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 688e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true on success, false if the input connection is no longer 689e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * valid. 6909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 6919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean reportFullscreenMode(boolean enabled); 692e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard 6939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 694e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * API to send private commands from an input method to its 695e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * connected editor. This can be used to provide domain-specific 696e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * features that are only known between certain input methods and 697e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * their clients. Note that because the InputConnection protocol 698e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * is asynchronous, you have no way to get a result back or know 699e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * if the client understood the command; you can use the 700e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * information in {@link EditorInfo} to determine if a client 701e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * supports a particular command. 702e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * 703e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @param action Name of the command to be performed. This <em>must</em> 7049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * be a scoped name, i.e. prefixed with a package name you own, so that 7059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * different developers will not create conflicting commands. 7069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * @param data Any data to include with the command. 707e811de2d6cd736b36a2a2ff552e6893a4a021045Jean Chalard * @return true if the command was sent (whether or not the 7089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * associated editor understood it), false if the input connection is no longer 7099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * valid. 7109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 7119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean performPrivateCommand(String action, Bundle data); 7129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 713