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.annotation.MainThread; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.annotation.SdkConstant; 23 import android.annotation.SdkConstant.SdkConstantType; 24 import android.inputmethodservice.InputMethodService; 25 import android.os.IBinder; 26 import android.os.RemoteException; 27 import android.os.ResultReceiver; 28 import android.util.Log; 29 import android.view.View; 30 31 import com.android.internal.inputmethod.IInputMethodPrivilegedOperations; 32 import com.android.internal.view.IInlineSuggestionsRequestCallback; 33 import com.android.internal.view.InlineSuggestionsRequestInfo; 34 35 /** 36 * The InputMethod interface represents an input method which can generate key 37 * events and text, such as digital, email addresses, CJK characters, other 38 * language characters, and etc., while handling various input events, and send 39 * the text back to the application that requests text input. See 40 * {@link InputMethodManager} for more general information about the 41 * architecture. 42 * 43 * <p>Applications will not normally use this interface themselves, instead 44 * relying on the standard interaction provided by 45 * {@link android.widget.TextView} and {@link android.widget.EditText}. 46 * 47 * <p>Those implementing input methods should normally do so by deriving from 48 * {@link InputMethodService} or one of its subclasses. When implementing 49 * an input method, the service component containing it must also supply 50 * a {@link #SERVICE_META_DATA} meta-data field, referencing an XML resource 51 * providing details about the input method. All input methods also must 52 * require that clients hold the 53 * {@link android.Manifest.permission#BIND_INPUT_METHOD} in order to interact 54 * with the service; if this is not required, the system will not use that 55 * input method, because it can not trust that it is not compromised. 56 * 57 * <p>The InputMethod interface is actually split into two parts: the interface 58 * here is the top-level interface to the input method, providing all 59 * access to it, which only the system can access (due to the BIND_INPUT_METHOD 60 * permission requirement). In addition its method 61 * {@link #createSession(android.view.inputmethod.InputMethod.SessionCallback)} 62 * can be called to instantate a secondary {@link InputMethodSession} interface 63 * which is what clients use to communicate with the input method. 64 */ 65 public interface InputMethod { 66 /** @hide **/ 67 public static final String TAG = "InputMethod"; 68 /** 69 * This is the interface name that a service implementing an input 70 * method should say that it supports -- that is, this is the action it 71 * uses for its intent filter. 72 * To be supported, the service must also require the 73 * {@link android.Manifest.permission#BIND_INPUT_METHOD} permission so 74 * that other applications can not abuse it. 75 */ 76 @SdkConstant(SdkConstantType.SERVICE_ACTION) 77 public static final String SERVICE_INTERFACE = "android.view.InputMethod"; 78 79 /** 80 * Name under which an InputMethod service component publishes information 81 * about itself. This meta-data must reference an XML resource containing 82 * an 83 * <code><{@link android.R.styleable#InputMethod input-method}></code> 84 * tag. 85 */ 86 public static final String SERVICE_META_DATA = "android.view.im"; 87 88 public interface SessionCallback { sessionCreated(InputMethodSession session)89 public void sessionCreated(InputMethodSession session); 90 } 91 92 /** 93 * Called first thing after an input method is created, this supplies a 94 * unique token for the session it has with the system service as well as 95 * IPC endpoint to do some other privileged operations. 96 * 97 * @param token special token for the system to identify 98 * {@link InputMethodService} 99 * @param displayId The id of the display that current IME shown. 100 * Used for {{@link #updateInputMethodDisplay(int)}} 101 * @param privilegedOperations IPC endpoint to do some privileged 102 * operations that are allowed only to the 103 * current IME. 104 * @param configChanges {@link InputMethodInfo#getConfigChanges()} declared by IME. 105 * @hide 106 */ 107 @MainThread initializeInternal(IBinder token, int displayId, IInputMethodPrivilegedOperations privilegedOperations, int configChanges)108 default void initializeInternal(IBinder token, int displayId, 109 IInputMethodPrivilegedOperations privilegedOperations, int configChanges) { 110 updateInputMethodDisplay(displayId); 111 attachToken(token); 112 } 113 114 /** 115 * Called to notify the IME that Autofill Frameworks requested an inline suggestions request. 116 * 117 * @param requestInfo information needed to create an {@link InlineSuggestionsRequest}. 118 * @param cb {@link IInlineSuggestionsRequestCallback} used to pass back the request object. 119 * 120 * @hide 121 */ onCreateInlineSuggestionsRequest(InlineSuggestionsRequestInfo requestInfo, IInlineSuggestionsRequestCallback cb)122 default void onCreateInlineSuggestionsRequest(InlineSuggestionsRequestInfo requestInfo, 123 IInlineSuggestionsRequestCallback cb) { 124 try { 125 cb.onInlineSuggestionsUnsupported(); 126 } catch (RemoteException e) { 127 Log.w(TAG, "Failed to call onInlineSuggestionsUnsupported.", e); 128 } 129 } 130 131 /** 132 * Called first thing after an input method is created, this supplies a 133 * unique token for the session it has with the system service. It is 134 * needed to identify itself with the service to validate its operations. 135 * This token <strong>must not</strong> be passed to applications, since 136 * it grants special priviledges that should not be given to applications. 137 * 138 * <p>The system guarantees that this method is called back between 139 * {@link InputMethodService#onCreate()} and {@link InputMethodService#onDestroy()} 140 * at most once. 141 */ 142 @MainThread attachToken(IBinder token)143 public void attachToken(IBinder token); 144 145 /** 146 * Update context display according to given displayId. 147 * 148 * @param displayId The id of the display that need to update for context. 149 * @hide 150 */ 151 @MainThread updateInputMethodDisplay(int displayId)152 default void updateInputMethodDisplay(int displayId) { 153 } 154 155 /** 156 * Bind a new application environment in to the input method, so that it 157 * can later start and stop input processing. 158 * Typically this method is called when this input method is enabled in an 159 * application for the first time. 160 * 161 * @param binding Information about the application window that is binding 162 * to the input method. 163 * 164 * @see InputBinding 165 * @see #unbindInput() 166 */ 167 @MainThread bindInput(InputBinding binding)168 public void bindInput(InputBinding binding); 169 170 /** 171 * Unbind an application environment, called when the information previously 172 * set by {@link #bindInput} is no longer valid for this input method. 173 * 174 * <p> 175 * Typically this method is called when the application changes to be 176 * non-foreground. 177 */ 178 @MainThread unbindInput()179 public void unbindInput(); 180 181 /** 182 * This method is called when the application starts to receive text and it 183 * is ready for this input method to process received events and send result 184 * text back to the application. 185 * 186 * @param inputConnection Optional specific input connection for 187 * communicating with the text box; if null, you should use the generic 188 * bound input connection. 189 * @param info Information about the text box (typically, an EditText) 190 * that requests input. 191 * 192 * @see EditorInfo 193 */ 194 @MainThread startInput(InputConnection inputConnection, EditorInfo info)195 public void startInput(InputConnection inputConnection, EditorInfo info); 196 197 /** 198 * This method is called when the state of this input method needs to be 199 * reset. 200 * 201 * <p> 202 * Typically, this method is called when the input focus is moved from one 203 * text box to another. 204 * 205 * @param inputConnection Optional specific input connection for 206 * communicating with the text box; if null, you should use the generic 207 * bound input connection. 208 * @param attribute The attribute of the text box (typically, a EditText) 209 * that requests input. 210 * 211 * @see EditorInfo 212 */ 213 @MainThread restartInput(InputConnection inputConnection, EditorInfo attribute)214 public void restartInput(InputConnection inputConnection, EditorInfo attribute); 215 216 /** 217 * This method is called when {@code {@link #startInput(InputConnection, EditorInfo)} or 218 * {@code {@link #restartInput(InputConnection, EditorInfo)} needs to be dispatched. 219 * 220 * <p>Note: This method is hidden because the {@code startInputToken} that this method is 221 * dealing with is one of internal details, which should not be exposed to the IME developers. 222 * If you override this method, you are responsible for not breaking existing IMEs that expect 223 * {@link #startInput(InputConnection, EditorInfo)} to be still called back.</p> 224 * 225 * @param inputConnection optional specific input connection for communicating with the text 226 * box; if {@code null}, you should use the generic bound input 227 * connection 228 * @param editorInfo information about the text box (typically, an EditText) that requests input 229 * @param restarting {@code false} if this corresponds to 230 * {@link #startInput(InputConnection, EditorInfo)}. Otherwise this 231 * corresponds to {@link #restartInput(InputConnection, EditorInfo)}. 232 * @param startInputToken a token that identifies a logical session that starts with this method 233 * call. Some internal IPCs such as {@link 234 * InputMethodManager#setImeWindowStatus(IBinder, IBinder, int, int)} 235 * require this token to work, and you have to keep the token alive until 236 * the next {@link #startInput(InputConnection, EditorInfo, IBinder)} as 237 * long as your implementation of {@link InputMethod} relies on such 238 * IPCs 239 * @see #startInput(InputConnection, EditorInfo) 240 * @see #restartInput(InputConnection, EditorInfo) 241 * @see EditorInfo 242 * @hide 243 */ 244 @MainThread dispatchStartInputWithToken(@ullable InputConnection inputConnection, @NonNull EditorInfo editorInfo, boolean restarting, @NonNull IBinder startInputToken)245 default void dispatchStartInputWithToken(@Nullable InputConnection inputConnection, 246 @NonNull EditorInfo editorInfo, boolean restarting, 247 @NonNull IBinder startInputToken) { 248 if (restarting) { 249 restartInput(inputConnection, editorInfo); 250 } else { 251 startInput(inputConnection, editorInfo); 252 } 253 } 254 255 /** 256 * Create a new {@link InputMethodSession} that can be handed to client 257 * applications for interacting with the input method. You can later 258 * use {@link #revokeSession(InputMethodSession)} to destroy the session 259 * so that it can no longer be used by any clients. 260 * 261 * @param callback Interface that is called with the newly created session. 262 */ 263 @MainThread createSession(SessionCallback callback)264 public void createSession(SessionCallback callback); 265 266 /** 267 * Control whether a particular input method session is active. 268 * 269 * @param session The {@link InputMethodSession} previously provided through 270 * SessionCallback.sessionCreated() that is to be changed. 271 */ 272 @MainThread setSessionEnabled(InputMethodSession session, boolean enabled)273 public void setSessionEnabled(InputMethodSession session, boolean enabled); 274 275 /** 276 * Disable and destroy a session that was previously created with 277 * {@link #createSession(android.view.inputmethod.InputMethod.SessionCallback)}. 278 * After this call, the given session interface is no longer active and 279 * calls on it will fail. 280 * 281 * @param session The {@link InputMethodSession} previously provided through 282 * SessionCallback.sessionCreated() that is to be revoked. 283 */ 284 @MainThread revokeSession(InputMethodSession session)285 public void revokeSession(InputMethodSession session); 286 287 /** 288 * Flag for {@link #showSoftInput}: this show has been explicitly 289 * requested by the user. If not set, the system has decided it may be 290 * a good idea to show the input method based on a navigation operation 291 * in the UI. 292 */ 293 public static final int SHOW_EXPLICIT = 0x00001; 294 295 /** 296 * Flag for {@link #showSoftInput}: this show has been forced to 297 * happen by the user. If set, the input method should remain visible 298 * until deliberated dismissed by the user in its UI. 299 */ 300 public static final int SHOW_FORCED = 0x00002; 301 302 /** 303 * Request that any soft input part of the input method be shown to the user. 304 * 305 * @param flags Provides additional information about the show request. 306 * Currently may be 0 or have the bit {@link #SHOW_EXPLICIT} set. 307 * @param resultReceiver The client requesting the show may wish to 308 * be told the impact of their request, which should be supplied here. 309 * The result code should be 310 * {@link InputMethodManager#RESULT_UNCHANGED_SHOWN InputMethodManager.RESULT_UNCHANGED_SHOWN}, 311 * {@link InputMethodManager#RESULT_UNCHANGED_HIDDEN InputMethodManager.RESULT_UNCHANGED_HIDDEN}, 312 * {@link InputMethodManager#RESULT_SHOWN InputMethodManager.RESULT_SHOWN}, or 313 * {@link InputMethodManager#RESULT_HIDDEN InputMethodManager.RESULT_HIDDEN}. 314 * @param showInputToken an opaque {@link android.os.Binder} token to identify which API call 315 * of {@link InputMethodManager#showSoftInput(View, int)} is associated with 316 * this callback. 317 * @hide 318 */ 319 @MainThread showSoftInputWithToken(int flags, ResultReceiver resultReceiver, IBinder showInputToken)320 default public void showSoftInputWithToken(int flags, ResultReceiver resultReceiver, 321 IBinder showInputToken) { 322 showSoftInput(flags, resultReceiver); 323 } 324 325 /** 326 * Request that any soft input part of the input method be shown to the user. 327 * 328 * @param flags Provides additional information about the show request. 329 * Currently may be 0 or have the bit {@link #SHOW_EXPLICIT} set. 330 * @param resultReceiver The client requesting the show may wish to 331 * be told the impact of their request, which should be supplied here. 332 * The result code should be 333 * {@link InputMethodManager#RESULT_UNCHANGED_SHOWN InputMethodManager.RESULT_UNCHANGED_SHOWN}, 334 * {@link InputMethodManager#RESULT_UNCHANGED_HIDDEN InputMethodManager.RESULT_UNCHANGED_HIDDEN}, 335 * {@link InputMethodManager#RESULT_SHOWN InputMethodManager.RESULT_SHOWN}, or 336 * {@link InputMethodManager#RESULT_HIDDEN InputMethodManager.RESULT_HIDDEN}. 337 */ 338 @MainThread showSoftInput(int flags, ResultReceiver resultReceiver)339 public void showSoftInput(int flags, ResultReceiver resultReceiver); 340 341 /** 342 * Request that any soft input part of the input method be hidden from the user. 343 * @param flags Provides additional information about the show request. 344 * Currently always 0. 345 * @param resultReceiver The client requesting the show may wish to 346 * be told the impact of their request, which should be supplied here. 347 * The result code should be 348 * {@link InputMethodManager#RESULT_UNCHANGED_SHOWN InputMethodManager.RESULT_UNCHANGED_SHOWN}, 349 * {@link InputMethodManager#RESULT_UNCHANGED_HIDDEN InputMethodManager.RESULT_UNCHANGED_HIDDEN}, 350 * {@link InputMethodManager#RESULT_SHOWN InputMethodManager.RESULT_SHOWN}, or 351 * {@link InputMethodManager#RESULT_HIDDEN InputMethodManager.RESULT_HIDDEN}. 352 * @param hideInputToken an opaque {@link android.os.Binder} token to identify which API call 353 * of {@link InputMethodManager#hideSoftInputFromWindow(IBinder, int)}} is associated 354 * with this callback. 355 * @hide 356 */ 357 @MainThread hideSoftInputWithToken(int flags, ResultReceiver resultReceiver, IBinder hideInputToken)358 public void hideSoftInputWithToken(int flags, ResultReceiver resultReceiver, 359 IBinder hideInputToken); 360 361 /** 362 * Request that any soft input part of the input method be hidden from the user. 363 * @param flags Provides additional information about the show request. 364 * Currently always 0. 365 * @param resultReceiver The client requesting the show may wish to 366 * be told the impact of their request, which should be supplied here. 367 * The result code should be 368 * {@link InputMethodManager#RESULT_UNCHANGED_SHOWN InputMethodManager.RESULT_UNCHANGED_SHOWN}, 369 * {@link InputMethodManager#RESULT_UNCHANGED_HIDDEN 370 * InputMethodManager.RESULT_UNCHANGED_HIDDEN}, 371 * {@link InputMethodManager#RESULT_SHOWN InputMethodManager.RESULT_SHOWN}, or 372 * {@link InputMethodManager#RESULT_HIDDEN InputMethodManager.RESULT_HIDDEN}. 373 */ 374 @MainThread hideSoftInput(int flags, ResultReceiver resultReceiver)375 public void hideSoftInput(int flags, ResultReceiver resultReceiver); 376 377 /** 378 * Notify that the input method subtype is being changed in the same input method. 379 * @param subtype New subtype of the notified input method 380 */ 381 @MainThread changeInputMethodSubtype(InputMethodSubtype subtype)382 public void changeInputMethodSubtype(InputMethodSubtype subtype); 383 384 /** 385 * Update token of the client window requesting {@link #showSoftInput(int, ResultReceiver)} 386 * @param showInputToken placeholder app window token for window requesting 387 * {@link InputMethodManager#showSoftInput(View, int)} 388 * @hide 389 */ setCurrentShowInputToken(IBinder showInputToken)390 public void setCurrentShowInputToken(IBinder showInputToken); 391 392 /** 393 * Update token of the client window requesting {@link #hideSoftInput(int, ResultReceiver)} 394 * @param hideInputToken placeholder app window token for window requesting 395 * {@link InputMethodManager#hideSoftInputFromWindow(IBinder, int)} 396 * @hide 397 */ setCurrentHideInputToken(IBinder hideInputToken)398 public void setCurrentHideInputToken(IBinder hideInputToken); 399 400 } 401