PageRenderTime 62ms CodeModel.GetById 29ms RepoModel.GetById 0ms app.codeStats 0ms

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

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