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