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