/*
* Copyright (C) 2007-2008 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package android.view.inputmethod;
import android.inputmethodservice.InputMethodService;
import android.os.IBinder;
import android.os.ResultReceiver;
/**
* The InputMethod interface represents an input method which can generate key
* events and text, such as digital, email addresses, CJK characters, other
* language characters, and etc., while handling various input events, and send
* the text back to the application that requests text input. See
* {@link InputMethodManager} for more general information about the
* architecture.
*
* <p>Applications will not normally use this interface themselves, instead
* relying on the standard interaction provided by
* {@link android.widget.TextView} and {@link android.widget.EditText}.
*
* <p>Those implementing input methods should normally do so by deriving from
* {@link InputMethodService} or one of its subclasses. When implementing
* an input method, the service component containing it must also supply
* a {@link #SERVICE_META_DATA} meta-data field, referencing an XML resource
* providing details about the input method. All input methods also must
* require that clients hold the
* {@link android.Manifest.permission#BIND_INPUT_METHOD} in order to interact
* with the service; if this is not required, the system will not use that
* input method, because it can not trust that it is not compromised.
*
* <p>The InputMethod interface is actually split into two parts: the interface
* here is the top-level interface to the input method, providing all
* access to it, which only the system can access (due to the BIND_INPUT_METHOD
* permission requirement). In addition its method
* {@link #createSession(android.view.inputmethod.InputMethod.SessionCallback)}
* can be called to instantate a secondary {@link InputMethodSession} interface
* which is what clients use to communicate with the input method.
*/
public interface InputMethod {
/**
* This is the interface name that a service implementing an input
* method should say that it supports -- that is, this is the action it
* uses for its intent filter. (Note: this name is used because this
* interface should be moved to the view package.)
*/
public static final String SERVICE_INTERFACE = "android.view.InputMethod";
/**
* Name under which an InputMethod service component publishes information
* about itself. This meta-data must reference an XML resource containing
* an
* <code><{@link android.R.styleable#InputMethod input-method}></code>
* tag.
*/
public static final String SERVICE_META_DATA = "android.view.im";
public interface SessionCallback {
public void sessionCreated(InputMethodSession session);
}
/**
* Called first thing after an input method is created, this supplies a
* unique token for the session it has with the system service. It is
* needed to identify itself with the service to validate its operations.
* This token <strong>must not</strong> be passed to applications, since
* it grants special priviledges that should not be given to applications.
*
* <p>Note: to protect yourself from malicious clients, you should only
* accept the first token given to you. Any after that may come from the
* client.
*/
public void attachToken(IBinder token);
/**
* Bind a new application environment in to the input method, so that it
* can later start and stop input processing.
* Typically this method is called when this input method is enabled in an
* application for the first time.
*
* @param binding Information about the application window that is binding
* to the input method.
*
* @see InputBinding
* @see #unbindInput()
*/
public void bindInput(InputBinding binding);
/**
* Unbind an application environment, called when the information previously
* set by {@link #bindInput} is no longer valid for this input method.
*
* <p>
* Typically this method is called when the application changes to be
* non-foreground.
*/
public void unbindInput();
/**
* This method is called when the application starts to receive text and it
* is ready for this input method to process received events and send result
* text back to the application.
*
* @param inputConnection Optional specific input connection for
* communicating with the text box; if null, you should use the generic
* bound input connection.
* @param info Information about the text box (typically, an EditText)
* that requests input.
*
* @see EditorInfo
*/
public void startInput(InputConnection inputConnection, EditorInfo info);
/**
* This method is called when the state of this input method needs to be
* reset.
*
* <p>
* Typically, this method is called when the input focus is moved from one
* text box to another.
*
* @param inputConnection Optional specific input connection for
* communicating with the text box; if null, you should use the generic
* bound input connection.
* @param attribute The attribute of the text box (typically, a EditText)
* that requests input.
*
* @see EditorInfo
*/
public void restartInput(InputConnection inputConnection, EditorInfo attribute);
/**
* Create a new {@link InputMethodSession} that can be handed to client
* applications for interacting with the input method. You can later
* use {@link #revokeSession(InputMethodSession)} to destroy the session
* so that it can no longer be used by any clients.
*
* @param callback Interface that is called with the newly created session.
*/
public void createSession(SessionCallback callback);
/**
* Control whether a particular input method session is active.
*
* @param session The {@link InputMethodSession} previously provided through
* SessionCallback.sessionCreated() that is to be changed.
*/
public void setSessionEnabled(InputMethodSession session, boolean enabled);
/**
* Disable and destroy a session that was previously created with
* {@link #createSession(android.view.inputmethod.InputMethod.SessionCallback)}.
* After this call, the given session interface is no longer active and
* calls on it will fail.
*
* @param session The {@link InputMethodSession} previously provided through
* SessionCallback.sessionCreated() that is to be revoked.
*/
public void revokeSession(InputMethodSession session);
/**
* Flag for {@link #showSoftInput}: this show has been explicitly
* requested by the user. If not set, the system has decided it may be
* a good idea to show the input method based on a navigation operation
* in the UI.
*/
public static final int SHOW_EXPLICIT = 0x00001;
/**
* Flag for {@link #showSoftInput}: this show has been forced to
* happen by the user. If set, the input method should remain visible
* until deliberated dismissed by the user in its UI.
*/
public static final int SHOW_FORCED = 0x00002;
/**
* Request that any soft input part of the input method be shown to the user.
*
* @param flags Provides additional information about the show request.
* Currently may be 0 or have the bit {@link #SHOW_EXPLICIT} set.
* @param resultReceiver The client requesting the show may wish to
* be told the impact of their request, which should be supplied here.
* The result code should be
* {@link InputMethodManager#RESULT_UNCHANGED_SHOWN InputMethodManager.RESULT_UNCHANGED_SHOWN},
* {@link InputMethodManager#RESULT_UNCHANGED_HIDDEN InputMethodManager.RESULT_UNCHANGED_HIDDEN},
* {@link InputMethodManager#RESULT_SHOWN InputMethodManager.RESULT_SHOWN}, or
* {@link InputMethodManager#RESULT_HIDDEN InputMethodManager.RESULT_HIDDEN}.
*/
public void showSoftInput(int flags, ResultReceiver resultReceiver);
/**
* Request that any soft input part of the input method be hidden from the user.
* @param flags Provides additional information about the show request.
* Currently always 0.
* @param resultReceiver The client requesting the show may wish to
* be told the impact of their request, which should be supplied here.
* The result code should be
* {@link InputMethodManager#RESULT_UNCHANGED_SHOWN InputMethodManager.RESULT_UNCHANGED_SHOWN},
* {@link InputMethodManager#RESULT_UNCHANGED_HIDDEN InputMethodManager.RESULT_UNCHANGED_HIDDEN},
* {@link InputMethodManager#RESULT_SHOWN InputMethodManager.RESULT_SHOWN}, or
* {@link InputMethodManager#RESULT_HIDDEN InputMethodManager.RESULT_HIDDEN}.
*/
public void hideSoftInput(int flags, ResultReceiver resultReceiver);
}
|
