1 /* 2 * Copyright (C) 2007-2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not 5 * use this file except in compliance with the License. You may obtain a copy of 6 * the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 13 * License for the specific language governing permissions and limitations under 14 * the License. 15 */ 16 17 package android.view.inputmethod; 18 19 import android.os.Bundle; 20 import android.view.KeyCharacterMap; 21 import android.view.KeyEvent; 22 23 /** 24 * The InputConnection interface is the communication channel from an 25 * {@link InputMethod} back to the application that is receiving its 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>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. 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 */ getTextBeforeCursor(int n, int flags)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 */ getTextAfterCursor(int n, int flags)81 public CharSequence getTextAfterCursor(int n, int flags); 82 83 /** 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 */ getSelectedText(int flags)96 public CharSequence getSelectedText(int flags); 97 98 /** 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 */ getCursorCapsMode(int reqModes)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 */ getExtractedText(ExtractedTextRequest request, int flags)137 public ExtractedText getExtractedText(ExtractedTextRequest request, 138 int flags); 139 140 /** 141 * Delete <var>beforeLength</var> characters of text before the current cursor 142 * position, and delete <var>afterLength</var> characters of text after the 143 * current cursor position, excluding composing text. Before and after refer 144 * to the order of the characters in the string, not to their visual representation. 145 * 146 * 147 * @param beforeLength The number of characters to be deleted before the 148 * current cursor position. 149 * @param afterLength The number of characters to be deleted after the 150 * current cursor position. 151 * 152 * @return Returns true on success, false if the input connection is no longer 153 * valid. 154 */ deleteSurroundingText(int beforeLength, int afterLength)155 public boolean deleteSurroundingText(int beforeLength, int afterLength); 156 157 /** 158 * Set composing text around the current cursor position with the given text, 159 * and set the new cursor position. Any composing text set previously will 160 * be removed automatically. 161 * 162 * @param text The composing text with styles if necessary. If no style 163 * object attached to the text, the default style for composing text 164 * is used. See {#link android.text.Spanned} for how to attach style 165 * object to the text. {#link android.text.SpannableString} and 166 * {#link android.text.SpannableStringBuilder} are two 167 * implementations of the interface {#link android.text.Spanned}. 168 * @param newCursorPosition The new cursor position around the text. If 169 * > 0, this is relative to the end of the text - 1; if <= 0, this 170 * is relative to the start of the text. So a value of 1 will 171 * always advance you to the position after the full text being 172 * inserted. Note that this means you can't position the cursor 173 * within the text, because the editor can make modifications to 174 * the text you are providing so it is not possible to correctly 175 * specify locations there. 176 * 177 * @return Returns true on success, false if the input connection is no longer 178 * valid. 179 */ setComposingText(CharSequence text, int newCursorPosition)180 public boolean setComposingText(CharSequence text, int newCursorPosition); 181 182 /** 183 * Mark a certain region of text as composing text. Any composing text set 184 * previously will be removed automatically. The default style for composing 185 * text is used. 186 * 187 * @param start the position in the text at which the composing region begins 188 * @param end the position in the text at which the composing region ends 189 * @return Returns true on success, false if the input connection is no longer 190 * valid. 191 */ setComposingRegion(int start, int end)192 public boolean setComposingRegion(int start, int end); 193 194 /** 195 * Have the text editor finish whatever composing text is currently 196 * active. This simply leaves the text as-is, removing any special 197 * composing styling or other state that was around it. The cursor 198 * position remains unchanged. 199 */ finishComposingText()200 public boolean finishComposingText(); 201 202 /** 203 * Commit text to the text box and set the new cursor position. 204 * Any composing text set previously will be removed 205 * automatically. 206 * 207 * @param text The committed text. 208 * @param newCursorPosition The new cursor position around the text. If 209 * > 0, this is relative to the end of the text - 1; if <= 0, this 210 * is relative to the start of the text. So a value of 1 will 211 * always advance you to the position after the full text being 212 * inserted. Note that this means you can't position the cursor 213 * within the text, because the editor can make modifications to 214 * the text you are providing so it is not possible to correctly 215 * specify locations there. 216 * 217 * 218 * @return Returns true on success, false if the input connection is no longer 219 * valid. 220 */ commitText(CharSequence text, int newCursorPosition)221 public boolean commitText(CharSequence text, int newCursorPosition); 222 223 /** 224 * Commit a completion the user has selected from the possible ones 225 * previously reported to {@link InputMethodSession#displayCompletions 226 * InputMethodSession.displayCompletions()}. This will result in the 227 * same behavior as if the user had selected the completion from the 228 * actual UI. 229 * 230 * @param text The committed completion. 231 * 232 * @return Returns true on success, false if the input connection is no longer 233 * valid. 234 */ commitCompletion(CompletionInfo text)235 public boolean commitCompletion(CompletionInfo text); 236 237 /** 238 * Commit a correction automatically performed on the raw user's input. A typical example would 239 * be to correct typos using a dictionary. 240 * 241 * @param correctionInfo Detailed information about the correction. 242 * 243 * @return True on success, false if the input connection is no longer valid. 244 */ commitCorrection(CorrectionInfo correctionInfo)245 public boolean commitCorrection(CorrectionInfo correctionInfo); 246 247 /** 248 * Set the selection of the text editor. To set the cursor position, 249 * start and end should have the same value. 250 * @return Returns true on success, false if the input connection is no longer 251 * valid. 252 */ setSelection(int start, int end)253 public boolean setSelection(int start, int end); 254 255 /** 256 * Have the editor perform an action it has said it can do. 257 * 258 * @param editorAction This must be one of the action constants for 259 * {@link EditorInfo#imeOptions EditorInfo.editorType}, such as 260 * {@link EditorInfo#IME_ACTION_GO EditorInfo.EDITOR_ACTION_GO}. 261 * 262 * @return Returns true on success, false if the input connection is no longer 263 * valid. 264 */ performEditorAction(int editorAction)265 public boolean performEditorAction(int editorAction); 266 267 /** 268 * Perform a context menu action on the field. The given id may be one of: 269 * {@link android.R.id#selectAll}, 270 * {@link android.R.id#startSelectingText}, {@link android.R.id#stopSelectingText}, 271 * {@link android.R.id#cut}, {@link android.R.id#copy}, 272 * {@link android.R.id#paste}, {@link android.R.id#copyUrl}, 273 * or {@link android.R.id#switchInputMethod} 274 */ performContextMenuAction(int id)275 public boolean performContextMenuAction(int id); 276 277 /** 278 * Tell the editor that you are starting a batch of editor operations. 279 * The editor will try to avoid sending you updates about its state 280 * until {@link #endBatchEdit} is called. 281 */ beginBatchEdit()282 public boolean beginBatchEdit(); 283 284 /** 285 * Tell the editor that you are done with a batch edit previously 286 * initiated with {@link #beginBatchEdit}. 287 */ endBatchEdit()288 public boolean endBatchEdit(); 289 290 /** 291 * Send a key event to the process that is currently attached through 292 * this input connection. The event will be dispatched like a normal 293 * key event, to the currently focused; this generally is the view that 294 * is providing this InputConnection, but due to the asynchronous nature 295 * of this protocol that can not be guaranteed and the focus may have 296 * changed by the time the event is received. 297 * 298 * <p> 299 * This method can be used to send key events to the application. For 300 * example, an on-screen keyboard may use this method to simulate a hardware 301 * keyboard. There are three types of standard keyboards, numeric (12-key), 302 * predictive (20-key) and ALPHA (QWERTY). You can specify the keyboard type 303 * by specify the device id of the key event. 304 * 305 * <p> 306 * You will usually want to set the flag 307 * {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD} on all 308 * key event objects you give to this API; the flag will not be set 309 * for you. 310 * 311 * <p>Note that it's discouraged to send such key events in normal operation; 312 * this is mainly for use with {@link android.text.InputType#TYPE_NULL} type 313 * text fields. Use the {@link #commitText} family of methods to send text 314 * to the application instead. 315 * @param event The key event. 316 * 317 * @return Returns true on success, false if the input connection is no longer 318 * valid. 319 * 320 * @see KeyEvent 321 * @see KeyCharacterMap#NUMERIC 322 * @see KeyCharacterMap#PREDICTIVE 323 * @see KeyCharacterMap#ALPHA 324 */ sendKeyEvent(KeyEvent event)325 public boolean sendKeyEvent(KeyEvent event); 326 327 /** 328 * Clear the given meta key pressed states in the given input connection. 329 * 330 * @param states The states to be cleared, may be one or more bits as 331 * per {@link KeyEvent#getMetaState() KeyEvent.getMetaState()}. 332 * 333 * @return Returns true on success, false if the input connection is no longer 334 * valid. 335 */ clearMetaKeyStates(int states)336 public boolean clearMetaKeyStates(int states); 337 338 /** 339 * Called by the IME to tell the client when it switches between fullscreen 340 * and normal modes. This will normally be called for you by the standard 341 * implementation of {@link android.inputmethodservice.InputMethodService}. 342 */ reportFullscreenMode(boolean enabled)343 public boolean reportFullscreenMode(boolean enabled); 344 345 /** 346 * API to send private commands from an input method to its connected 347 * editor. This can be used to provide domain-specific features that are 348 * only known between certain input methods and their clients. Note that 349 * because the InputConnection protocol is asynchronous, you have no way 350 * to get a result back or know if the client understood the command; you 351 * can use the information in {@link EditorInfo} to determine if 352 * a client supports a particular command. 353 * 354 * @param action Name of the command to be performed. This <em>must</em> 355 * be a scoped name, i.e. prefixed with a package name you own, so that 356 * different developers will not create conflicting commands. 357 * @param data Any data to include with the command. 358 * @return Returns true if the command was sent (whether or not the 359 * associated editor understood it), false if the input connection is no longer 360 * valid. 361 */ performPrivateCommand(String action, Bundle data)362 public boolean performPrivateCommand(String action, Bundle data); 363 } 364