/core/java/android/view/inputmethod/InputMethod.java

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