InputConnection.java revision adb435835fb9a5f2bb74d29930b239dde18504a7
1/* 2 * Copyright (C) 2007-2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not 5 * use this file except in compliance with the License. You may obtain a copy of 6 * the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 13 * License for the specific language governing permissions and limitations under 14 * the License. 15 */ 16 17package android.view.inputmethod; 18 19import android.os.Bundle; 20import android.os.IBinder; 21import android.text.style.CorrectionSpan; 22import android.view.KeyCharacterMap; 23import android.view.KeyEvent; 24 25/** 26 * The InputConnection interface is the communication channel from an 27 * {@link InputMethod} back to the application that is receiving its input. It 28 * is used to perform such things as reading text around the cursor, 29 * committing text to the text box, and sending raw key events to the application. 30 * 31 * <p>Implementations of this interface should generally be done by 32 * subclassing {@link BaseInputConnection}. 33 */ 34public interface InputConnection { 35 /** 36 * Flag for use with {@link #getTextAfterCursor} and 37 * {@link #getTextBeforeCursor} to have style information returned along 38 * with the text. If not set, you will receive only the raw text. If 39 * set, you may receive a complex CharSequence of both text and style 40 * spans. 41 */ 42 static final int GET_TEXT_WITH_STYLES = 0x0001; 43 44 /** 45 * Flag for use with {@link #getExtractedText} to indicate you would 46 * like to receive updates when the extracted text changes. 47 */ 48 public static final int GET_EXTRACTED_TEXT_MONITOR = 0x0001; 49 50 /** 51 * Get <var>n</var> characters of text before the current cursor position. 52 * 53 * <p>This method may fail either if the input connection has become invalid 54 * (such as its process crashing) or the client is taking too long to 55 * respond with the text (it is given a couple seconds to return). 56 * In either case, a null is returned. 57 * 58 * @param n The expected length of the text. 59 * @param flags Supplies additional options controlling how the text is 60 * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}. 61 * 62 * @return Returns the text before the cursor position; the length of the 63 * returned text might be less than <var>n</var>. 64 */ 65 public CharSequence getTextBeforeCursor(int n, int flags); 66 67 /** 68 * Get <var>n</var> characters of text after the current cursor position. 69 * 70 * <p>This method may fail either if the input connection has become invalid 71 * (such as its process crashing) or the client is taking too long to 72 * respond with the text (it is given a couple seconds to return). 73 * In either case, a null is returned. 74 * 75 * @param n The expected length of the text. 76 * @param flags Supplies additional options controlling how the text is 77 * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}. 78 * 79 * @return Returns the text after the cursor position; the length of the 80 * returned text might be less than <var>n</var>. 81 */ 82 public CharSequence getTextAfterCursor(int n, int flags); 83 84 /** 85 * Gets the selected text, if any. 86 * 87 * <p>This method may fail if either the input connection has become 88 * invalid (such as its process crashing) or the client is taking too 89 * long to respond with the text (it is given a couple of seconds to return). 90 * In either case, a null is returned. 91 * 92 * @param flags Supplies additional options controlling how the text is 93 * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}. 94 * @return Returns the text that is currently selected, if any, or null if 95 * no text is selected. 96 */ 97 public CharSequence getSelectedText(int flags); 98 99 /** 100 * Retrieve the current capitalization mode in effect at the current 101 * cursor position in the text. See 102 * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode} for 103 * more information. 104 * 105 * <p>This method may fail either if the input connection has become invalid 106 * (such as its process crashing) or the client is taking too long to 107 * respond with the text (it is given a couple seconds to return). 108 * In either case, a 0 is returned. 109 * 110 * @param reqModes The desired modes to retrieve, as defined by 111 * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}. These 112 * constants are defined so that you can simply pass the current 113 * {@link EditorInfo#inputType TextBoxAttribute.contentType} value 114 * directly in to here. 115 * 116 * @return Returns the caps mode flags that are in effect. 117 */ 118 public int getCursorCapsMode(int reqModes); 119 120 /** 121 * Retrieve the current text in the input connection's editor, and monitor 122 * for any changes to it. This function returns with the current text, 123 * and optionally the input connection can send updates to the 124 * input method when its text changes. 125 * 126 * <p>This method may fail either if the input connection has become invalid 127 * (such as its process crashing) or the client is taking too long to 128 * respond with the text (it is given a couple seconds to return). 129 * In either case, a null is returned. 130 * 131 * @param request Description of how the text should be returned. 132 * @param flags Additional options to control the client, either 0 or 133 * {@link #GET_EXTRACTED_TEXT_MONITOR}. 134 * 135 * @return Returns an ExtractedText object describing the state of the 136 * text view and containing the extracted text itself. 137 */ 138 public ExtractedText getExtractedText(ExtractedTextRequest request, 139 int flags); 140 141 /** 142 * Delete <var>leftLength</var> characters of text before the current cursor 143 * position, and delete <var>rightLength</var> characters of text after the 144 * current cursor position, excluding composing text. 145 * 146 * @param leftLength The number of characters to be deleted before the 147 * current cursor position. 148 * @param rightLength The number of characters to be deleted after the 149 * current cursor position. 150 * 151 * @return Returns true on success, false if the input connection is no longer 152 * valid. 153 */ 154 public boolean deleteSurroundingText(int leftLength, int rightLength); 155 156 /** 157 * Set composing text around the current cursor position with the given text, 158 * and set the new cursor position. Any composing text set previously will 159 * be removed automatically. 160 * 161 * @param text The composing text with styles if necessary. If no style 162 * object attached to the text, the default style for composing text 163 * is used. See {#link android.text.Spanned} for how to attach style 164 * object to the text. {#link android.text.SpannableString} and 165 * {#link android.text.SpannableStringBuilder} are two 166 * implementations of the interface {#link android.text.Spanned}. 167 * @param newCursorPosition The new cursor position around the text. If 168 * > 0, this is relative to the end of the text - 1; if <= 0, this 169 * is relative to the start of the text. So a value of 1 will 170 * always advance you to the position after the full text being 171 * inserted. Note that this means you can't position the cursor 172 * within the text, because the editor can make modifications to 173 * the text you are providing so it is not possible to correctly 174 * specify locations there. 175 * 176 * @return Returns true on success, false if the input connection is no longer 177 * valid. 178 */ 179 public boolean setComposingText(CharSequence text, int newCursorPosition); 180 181 /** 182 * Mark a certain region of text as composing text. Any composing text set 183 * previously will be removed automatically. The default style for composing 184 * text is used. 185 * 186 * @param start the position in the text at which the composing region begins 187 * @param end the position in the text at which the composing region ends 188 * @return Returns true on success, false if the input connection is no longer 189 * valid. 190 */ 191 public boolean setComposingRegion(int start, int end); 192 193 /** 194 * Have the text editor finish whatever composing text is currently 195 * active. This simply leaves the text as-is, removing any special 196 * composing styling or other state that was around it. The cursor 197 * position remains unchanged. 198 */ 199 public boolean finishComposingText(); 200 201 /** 202 * Commit text to the text box and set the new cursor position. 203 * Any composing text set previously will be removed 204 * automatically. 205 * 206 * @param text The committed text. 207 * @param newCursorPosition The new cursor position around the text. If 208 * > 0, this is relative to the end of the text - 1; if <= 0, this 209 * is relative to the start of the text. So a value of 1 will 210 * always advance you to the position after the full text being 211 * inserted. Note that this means you can't position the cursor 212 * within the text, because the editor can make modifications to 213 * the text you are providing so it is not possible to correctly 214 * specify locations there. 215 * 216 * 217 * @return Returns true on success, false if the input connection is no longer 218 * valid. 219 */ 220 public boolean commitText(CharSequence text, int newCursorPosition); 221 222 /** 223 * Commit a completion the user has selected from the possible ones 224 * previously reported to {@link InputMethodSession#displayCompletions 225 * InputMethodSession.displayCompletions()}. This will result in the 226 * same behavior as if the user had selected the completion from the 227 * actual UI. 228 * 229 * @param text The committed completion. 230 * 231 * @return Returns true on success, false if the input connection is no longer 232 * valid. 233 */ 234 public boolean commitCompletion(CompletionInfo text); 235 236 /** 237 * Commit a correction automatically performed on the raw user's input. A typical example would 238 * be to correct typos using a dictionary. 239 * 240 * @param correctionInfo Detailed information about the correction. 241 * 242 * @return True on success, false if the input connection is no longer valid. 243 */ 244 public boolean commitCorrection(CorrectionInfo correctionInfo); 245 246 /** 247 * Set the selection of the text editor. To set the cursor position, 248 * start and end should have the same value. 249 * @return Returns true on success, false if the input connection is no longer 250 * valid. 251 */ 252 public boolean setSelection(int start, int end); 253 254 /** 255 * Have the editor perform an action it has said it can do. 256 * 257 * @param editorAction This must be one of the action constants for 258 * {@link EditorInfo#imeOptions EditorInfo.editorType}, such as 259 * {@link EditorInfo#IME_ACTION_GO EditorInfo.EDITOR_ACTION_GO}. 260 * 261 * @return Returns true on success, false if the input connection is no longer 262 * valid. 263 */ 264 public boolean performEditorAction(int editorAction); 265 266 /** 267 * Perform a context menu action on the field. The given id may be one of: 268 * {@link android.R.id#selectAll}, 269 * {@link android.R.id#startSelectingText}, {@link android.R.id#stopSelectingText}, 270 * {@link android.R.id#cut}, {@link android.R.id#copy}, 271 * {@link android.R.id#paste}, {@link android.R.id#copyUrl}, 272 * or {@link android.R.id#switchInputMethod} 273 */ 274 public boolean performContextMenuAction(int id); 275 276 /** 277 * Tell the editor that you are starting a batch of editor operations. 278 * The editor will try to avoid sending you updates about its state 279 * until {@link #endBatchEdit} is called. 280 */ 281 public boolean beginBatchEdit(); 282 283 /** 284 * Tell the editor that you are done with a batch edit previously 285 * initiated with {@link #endBatchEdit}. 286 */ 287 public boolean endBatchEdit(); 288 289 /** 290 * Send a key event to the process that is currently attached through 291 * this input connection. The event will be dispatched like a normal 292 * key event, to the currently focused; this generally is the view that 293 * is providing this InputConnection, but due to the asynchronous nature 294 * of this protocol that can not be guaranteed and the focus may have 295 * changed by the time the event is received. 296 * 297 * <p> 298 * This method can be used to send key events to the application. For 299 * example, an on-screen keyboard may use this method to simulate a hardware 300 * keyboard. There are three types of standard keyboards, numeric (12-key), 301 * predictive (20-key) and ALPHA (QWERTY). You can specify the keyboard type 302 * by specify the device id of the key event. 303 * 304 * <p> 305 * You will usually want to set the flag 306 * {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD} on all 307 * key event objects you give to this API; the flag will not be set 308 * for you. 309 * 310 * @param event The key event. 311 * 312 * @return Returns true on success, false if the input connection is no longer 313 * valid. 314 * 315 * @see KeyEvent 316 * @see KeyCharacterMap#NUMERIC 317 * @see KeyCharacterMap#PREDICTIVE 318 * @see KeyCharacterMap#ALPHA 319 */ 320 public boolean sendKeyEvent(KeyEvent event); 321 322 /** 323 * Clear the given meta key pressed states in the given input connection. 324 * 325 * @param states The states to be cleared, may be one or more bits as 326 * per {@link KeyEvent#getMetaState() KeyEvent.getMetaState()}. 327 * 328 * @return Returns true on success, false if the input connection is no longer 329 * valid. 330 */ 331 public boolean clearMetaKeyStates(int states); 332 333 /** 334 * Called by the IME to tell the client when it switches between fullscreen 335 * and normal modes. This will normally be called for you by the standard 336 * implementation of {@link android.inputmethodservice.InputMethodService}. 337 */ 338 public boolean reportFullscreenMode(boolean enabled); 339 340 /** 341 * API to send private commands from an input method to its connected 342 * editor. This can be used to provide domain-specific features that are 343 * only known between certain input methods and their clients. Note that 344 * because the InputConnection protocol is asynchronous, you have no way 345 * to get a result back or know if the client understood the command; you 346 * can use the information in {@link EditorInfo} to determine if 347 * a client supports a particular command. 348 * 349 * @param action Name of the command to be performed. This <em>must</em> 350 * be a scoped name, i.e. prefixed with a package name you own, so that 351 * different developers will not create conflicting commands. 352 * @param data Any data to include with the command. 353 * @return Returns true if the command was sent (whether or not the 354 * associated editor understood it), false if the input connection is no longer 355 * valid. 356 */ 357 public boolean performPrivateCommand(String action, Bundle data); 358 359 /** 360 * Add a correction span. 361 */ 362 public boolean setCorrectionSpan(IBinder token, CorrectionSpan correctionSpan, int start, 363 int end, int flags); 364} 365