InputConnection.java revision da996f390e17e16f2dfa60e972e7ebc4f868f37e
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.text.Spanned; 21import android.view.KeyCharacterMap; 22import android.view.KeyEvent; 23 24/** 25 * The InputConnection interface is the communication channel from an 26 * {@link InputMethod} back to the application that is receiving its input. It 27 * is used to perform such things as reading text around the cursor, 28 * committing text to the text box, and sending raw key events to the application. 29 * 30 * <p>Implementations of this interface should generally be done by 31 * subclassing {@link BaseInputConnection}. 32 */ 33public 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 /** 84 * Retrieve the current capitalization mode in effect at the current 85 * cursor position in the text. See 86 * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode} for 87 * more information. 88 * 89 * <p>This method may fail either if the input connection has become invalid 90 * (such as its process crashing) or the client is taking too long to 91 * respond with the text (it is given a couple seconds to return). 92 * In either case, a 0 is returned. 93 * 94 * @param reqModes The desired modes to retrieve, as defined by 95 * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}. These 96 * constants are defined so that you can simply pass the current 97 * {@link EditorInfo#inputType TextBoxAttribute.contentType} value 98 * directly in to here. 99 * 100 * @return Returns the caps mode flags that are in effect. 101 */ 102 public int getCursorCapsMode(int reqModes); 103 104 /** 105 * Retrieve the current text in the input connection's editor, and monitor 106 * for any changes to it. This function returns with the current text, 107 * and optionally the input connection can send updates to the 108 * input method when its text changes. 109 * 110 * <p>This method may fail either if the input connection has become invalid 111 * (such as its process crashing) or the client is taking too long to 112 * respond with the text (it is given a couple seconds to return). 113 * In either case, a null is returned. 114 * 115 * @param request Description of how the text should be returned. 116 * @param flags Additional options to control the client, either 0 or 117 * {@link #GET_EXTRACTED_TEXT_MONITOR}. 118 * 119 * @return Returns an ExtractedText object describing the state of the 120 * text view and containing the extracted text itself. 121 */ 122 public ExtractedText getExtractedText(ExtractedTextRequest request, 123 int flags); 124 125 /** 126 * Delete <var>leftLength</var> characters of text before the current cursor 127 * position, and delete <var>rightLength</var> characters of text after the 128 * current cursor position, excluding composing text. 129 * 130 * @param leftLength The number of characters to be deleted before the 131 * current cursor position. 132 * @param rightLength The number of characters to be deleted after the 133 * current cursor position. 134 * 135 * @return Returns true on success, false if the input connection is no longer 136 * valid. 137 */ 138 boolean deleteSurroundingText(int leftLength, int rightLength); 139 140 /** 141 * Set composing text around the current cursor position with the given text, 142 * and set the new cursor position. Any composing text set previously will 143 * be removed automatically. 144 * 145 * @param text The composing text with styles if necessary. If no style 146 * object attached to the text, the default style for composing text 147 * is used. See {#link android.text.Spanned} for how to attach style 148 * object to the text. {#link android.text.SpannableString} and 149 * {#link android.text.SpannableStringBuilder} are two 150 * implementations of the interface {#link android.text.Spanned}. 151 * @param newCursorPosition The new cursor position within the 152 * <var>text</var>. 153 * 154 * @return Returns true on success, false if the input connection is no longer 155 * valid. 156 */ 157 public boolean setComposingText(CharSequence text, int newCursorPosition); 158 159 /** 160 * Have the text editor finish whatever composing text is currently 161 * active. This simply leaves the text as-is, removing any special 162 * composing styling or other state that was around it. The cursor 163 * position remains unchanged. 164 */ 165 public boolean finishComposingText(); 166 167 /** 168 * Commit text to the text box and set the new cursor position. 169 * Any composing text set previously will be removed 170 * automatically. 171 * 172 * @param text The committed text. 173 * @param newCursorPosition The new cursor position within the 174 * <var>text</var>. 175 * 176 * 177 * @return Returns true on success, false if the input connection is no longer 178 * valid. 179 */ 180 public boolean commitText(CharSequence text, int newCursorPosition); 181 182 /** 183 * Commit a completion the user has selected from the possible ones 184 * previously reported to {@link InputMethodSession#displayCompletions 185 * InputMethodSession.displayCompletions()}. This will result in the 186 * same behavior as if the user had selected the completion from the 187 * actual UI. 188 * 189 * @param text The committed completion. 190 * 191 * @return Returns true on success, false if the input connection is no longer 192 * valid. 193 */ 194 public boolean commitCompletion(CompletionInfo text); 195 196 /** 197 * Set the selection of the text editor. To set the cursor position, 198 * start and end should have the same value. 199 */ 200 public boolean setSelection(int start, int end); 201 202 /** 203 * Perform a context menu action on the field. The given id may be one of: 204 * {@link android.R.id#selectAll}, 205 * {@link android.R.id#startSelectingText}, {@link android.R.id#stopSelectingText}, 206 * {@link android.R.id#cut}, {@link android.R.id#copy}, 207 * {@link android.R.id#paste}, {@link android.R.id#copyUrl}, 208 * or {@link android.R.id#switchInputMethod} 209 */ 210 public boolean performContextMenuAction(int id); 211 212 /** 213 * Tell the editor that you are starting a batch of editor operations. 214 * The editor will try to avoid sending you updates about its state 215 * until {@link #endBatchEdit} is called. 216 */ 217 public boolean beginBatchEdit(); 218 219 /** 220 * Tell the editor that you are done with a batch edit previously 221 * initiated with {@link #endBatchEdit}. 222 */ 223 public boolean endBatchEdit(); 224 225 /** 226 * Send a key event to the process that is currently attached through 227 * this input connection. The event will be dispatched like a normal 228 * key event, to the currently focused; this generally is the view that 229 * is providing this InputConnection, but due to the asynchronous nature 230 * of this protocol that can not be guaranteed and the focus may have 231 * changed by the time the event is received. 232 * 233 * <p> 234 * This method can be used to send key events to the application. For 235 * example, an on-screen keyboard may use this method to simulate a hardware 236 * keyboard. There are three types of standard keyboards, numeric (12-key), 237 * predictive (20-key) and ALPHA (QWERTY). You can specify the keyboard type 238 * by specify the device id of the key event. 239 * 240 * <p> 241 * You will usually want to set the flag 242 * {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD} on all 243 * key event objects you give to this API; the flag will not be set 244 * for you. 245 * 246 * @param event The key event. 247 * 248 * @return Returns true on success, false if the input connection is no longer 249 * valid. 250 * 251 * @see KeyEvent 252 * @see KeyCharacterMap#NUMERIC 253 * @see KeyCharacterMap#PREDICTIVE 254 * @see KeyCharacterMap#ALPHA 255 */ 256 public boolean sendKeyEvent(KeyEvent event); 257 258 /** 259 * Clear the given meta key pressed states in the given input connection. 260 * 261 * @param states The states to be cleared, may be one or more bits as 262 * per {@link KeyEvent#getMetaState() KeyEvent.getMetaState()}. 263 * 264 * @return Returns true on success, false if the input connection is no longer 265 * valid. 266 */ 267 public boolean clearMetaKeyStates(int states); 268 269 /** 270 * Called by the IME to tell the client when it switches between fullscreen 271 * and normal modes. This will normally be called for you by the standard 272 * implementation of {@link android.inputmethodservice.InputMethodService}. 273 */ 274 public boolean reportFullscreenMode(boolean enabled); 275 276 /** 277 * API to send private commands from an input method to its connected 278 * editor. This can be used to provide domain-specific features that are 279 * only known between certain input methods and their clients. Note that 280 * because the InputConnection protocol is asynchronous, you have no way 281 * to get a result back or know if the client understood the command; you 282 * can use the information in {@link EditorInfo} to determine if 283 * a client supports a particular command. 284 * 285 * @param action Name of the command to be performed. This <em>must</em> 286 * be a scoped name, i.e. prefixed with a package name you own, so that 287 * different developers will not create conflicting commands. 288 * @param data Any data to include with the command. 289 * @return Returns true if the command was sent (whether or not the 290 * associated editor understood it), false if the input connection is no longer 291 * valid. 292 */ 293 public boolean performPrivateCommand(String action, Bundle data); 294} 295