InputConnection.java revision f1e484acb594a726fb57ad0ae4cfe902c7f35858
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 * Get <var>n</var> characters of text before the current cursor position. 36 * 37 * <p>This method may fail either if the input connection has become invalid 38 * (such as its process crashing) or the client is taking too long to 39 * respond with the text (it is given a couple seconds to return). 40 * In either case, a null is returned. 41 * 42 * @param n The expected length of the text. 43 * 44 * @return Returns the text before the cursor position; the length of the 45 * returned text might be less than <var>n</var>. 46 */ 47 public CharSequence getTextBeforeCursor(int n); 48 49 /** 50 * Get <var>n</var> characters of text after 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 * 59 * @return Returns the text after the cursor position; the length of the 60 * returned text might be less than <var>n</var>. 61 */ 62 public CharSequence getTextAfterCursor(int n); 63 64 /** 65 * Retrieve the current capitalization mode in effect at the current 66 * cursor position in the text. See 67 * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode} for 68 * more information. 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 0 is returned. 74 * 75 * @param reqModes The desired modes to retrieve, as defined by 76 * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}. These 77 * constants are defined so that you can simply pass the current 78 * {@link EditorInfo#inputType TextBoxAttribute.contentType} value 79 * directly in to here. 80 * 81 * @return Returns the caps mode flags that are in effect. 82 */ 83 public int getCursorCapsMode(int reqModes); 84 85 public static final int EXTRACTED_TEXT_MONITOR = 0x0001; 86 87 /** 88 * Retrieve the current text in the input connection's editor, and monitor 89 * for any changes to it. This function returns with the current text, 90 * and optionally the input connection can send updates to the 91 * input method when its text changes. 92 * 93 * <p>This method may fail either if the input connection has become invalid 94 * (such as its process crashing) or the client is taking too long to 95 * respond with the text (it is given a couple seconds to return). 96 * In either case, a null is returned. 97 * 98 * @param request Description of how the text should be returned. 99 * @param flags Additional options to control the client, either 0 or 100 * {@link #EXTRACTED_TEXT_MONITOR}. 101 * 102 * @return Returns an ExtractedText object describing the state of the 103 * text view and containing the extracted text itself. 104 */ 105 public ExtractedText getExtractedText(ExtractedTextRequest request, 106 int flags); 107 108 /** 109 * Delete <var>leftLength</var> characters of text before the current cursor 110 * position, and delete <var>rightLength</var> characters of text after the 111 * current cursor position, excluding composing text. 112 * 113 * @param leftLength The number of characters to be deleted before the 114 * current cursor position. 115 * @param rightLength The number of characters to be deleted after the 116 * current cursor position. 117 * 118 * @return Returns true on success, false if the input connection is no longer 119 * valid. 120 */ 121 boolean deleteSurroundingText(int leftLength, int rightLength); 122 123 /** 124 * Set composing text around the current cursor position with the given text, 125 * and set the new cursor position. Any composing text set previously will 126 * be removed automatically. 127 * 128 * @param text The composing text with styles if necessary. If no style 129 * object attached to the text, the default style for composing text 130 * is used. See {#link android.text.Spanned} for how to attach style 131 * object to the text. {#link android.text.SpannableString} and 132 * {#link android.text.SpannableStringBuilder} are two 133 * implementations of the interface {#link android.text.Spanned}. 134 * @param newCursorPosition The new cursor position within the 135 * <var>text</var>. 136 * 137 * @return Returns true on success, false if the input connection is no longer 138 * valid. 139 */ 140 public boolean setComposingText(CharSequence text, int newCursorPosition); 141 142 /** 143 * Have the text editor finish whatever composing text is currently 144 * active. This simple leaves the text as-is, removing any special 145 * composing styling or other state that was around it. The cursor 146 * position remains unchanged. 147 */ 148 public boolean finishComposingText(); 149 150 /** 151 * Commit text to the text box and set the new cursor position. 152 * Any composing text set previously will be removed 153 * automatically. 154 * 155 * @param text The committed text. 156 * @param newCursorPosition The new cursor position within the 157 * <var>text</var>. 158 * 159 * 160 * @return Returns true on success, false if the input connection is no longer 161 * valid. 162 */ 163 public boolean commitText(CharSequence text, int newCursorPosition); 164 165 /** 166 * Commit a completion the user has selected from the possible ones 167 * previously reported to {@link InputMethodSession#displayCompletions 168 * InputMethodSession.displayCompletions()}. This will result in the 169 * same behavior as if the user had selected the completion from the 170 * actual UI. 171 * 172 * @param text The committed completion. 173 * 174 * @return Returns true on success, false if the input connection is no longer 175 * valid. 176 */ 177 public boolean commitCompletion(CompletionInfo text); 178 179 /** 180 * Tell the editor that you are starting a batch of editor operations. 181 * The editor will try to avoid sending you updates about its state 182 * until {@link #endBatchEdit} is called. 183 */ 184 public boolean beginBatchEdit(); 185 186 /** 187 * Tell the editor that you are done with a batch edit previously 188 * initiated with {@link #endBatchEdit}. 189 */ 190 public boolean endBatchEdit(); 191 192 /** 193 * Send a key event to the process that is currently attached through 194 * this input connection. The event will be dispatched like a normal 195 * key event, to the currently focused; this generally is the view that 196 * is providing this InputConnection, but due to the asynchronous nature 197 * of this protocol that can not be guaranteed and the focus may have 198 * changed by the time the event is received. 199 * 200 * <p> 201 * This method can be used to send key events to the application. For 202 * example, an on-screen keyboard may use this method to simulate a hardware 203 * keyboard. There are three types of standard keyboards, numeric (12-key), 204 * predictive (20-key) and ALPHA (QWERTY). You can specify the keyboard type 205 * by specify the device id of the key event. 206 * 207 * <p> 208 * You will usually want to set the flag 209 * {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD} on all 210 * key event objects you give to this API; the flag will not be set 211 * for you. 212 * 213 * @param event The key event. 214 * 215 * @return Returns true on success, false if the input connection is no longer 216 * valid. 217 * 218 * @see KeyEvent 219 * @see KeyCharacterMap#NUMERIC 220 * @see KeyCharacterMap#PREDICTIVE 221 * @see KeyCharacterMap#ALPHA 222 */ 223 public boolean sendKeyEvent(KeyEvent event); 224 225 /** 226 * Clear the given meta key pressed states in the given input connection. 227 * 228 * @param states The states to be cleared, may be one or more bits as 229 * per {@link KeyEvent#getMetaState() KeyEvent.getMetaState()}. 230 * 231 * @return Returns true on success, false if the input connection is no longer 232 * valid. 233 */ 234 public boolean clearMetaKeyStates(int states); 235 236 /** 237 * API to send private commands from an input method to its connected 238 * editor. This can be used to provide domain-specific features that are 239 * only known between certain input methods and their clients. Note that 240 * because the InputConnection protocol is asynchronous, you have no way 241 * to get a result back or know if the client understood the command; you 242 * can use the information in {@link EditorInfo} to determine if 243 * a client supports a particular command. 244 * 245 * @param action Name of the command to be performed. This <em>must</em> 246 * be a scoped name, i.e. prefixed with a package name you own, so that 247 * different developers will not create conflicting commands. 248 * @param data Any data to include with the command. 249 * @return Returns true if the command was sent (whether or not the 250 * associated editor understood it), false if the input connection is no longer 251 * valid. 252 */ 253 public boolean performPrivateCommand(String action, Bundle data); 254 255 /** 256 * Show an icon in the status bar. 257 * 258 * @param packageName The package holding the icon resource to be shown. 259 * @param resId The resource id of the icon to show. 260 * 261 * @return Returns true on success, false if the input connection is no longer 262 * valid. 263 */ 264 public boolean showStatusIcon(String packageName, int resId); 265 266 /** 267 * Hide the icon shown in the status bar. 268 * 269 * @return Returns true on success, false if the input connection is no longer 270 * valid. 271 */ 272 public boolean hideStatusIcon(); 273} 274