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