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.annotation.SdkConstant;
20import android.annotation.SdkConstant.SdkConstantType;
21import android.inputmethodservice.InputMethodService;
22import android.os.IBinder;
23import 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 */
55public 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>&lt;{@link android.R.styleable#InputMethod input-method}&gt;</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    /**
224     * Notify that the input method subtype is being changed in the same input method.
225     * @param subtype New subtype of the notified input method
226     */
227    public void changeInputMethodSubtype(InputMethodSubtype subtype);
228}
229