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