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