| java.lang.Object | |
| ↳ | android.view.inputmethod.InputMethodManager |
Central system API to the overall input method framework (IMF) architecture,
which arbitrates interaction between applications and the current input method.
You can retrieve an instance of this interface with
Context.getSystemService().
Topics covered here:
There are three primary parties involved in the input method framework (IMF) architecture:
In most cases, applications that are using the standard
TextView or its subclasses will have little they need
to do to work well with soft input methods. The main things you need to
be aware of are:
inputType in your editable
text views, so that the input method will have enough context to help the
user in entering text into them.
windowSoftInputMode
attribute on your activity or the corresponding values on windows you
create to help the system determine whether to pan or resize (it will
try to determine this automatically but may get it wrong).
windowSoftInputMode
attribute.
More finer-grained control is available through the APIs here to directly interact with the IMF and its IME -- either showing or hiding the input area, letting the user pick an input method, etc.
For the rare people amongst us writing their own text editors, you
will need to implement onCreateInputConnection(EditorInfo)
to return a new instance of your own InputConnection interface
allowing the IME to interact with your editor.
An input method (IME) is implemented
as a Service, typically deriving from
InputMethodService. It must provide
the core InputMethod interface, though this is normally handled by
InputMethodService and implementors will
only need to deal with the higher-level API there.
InputMethodService class for
more information on implementing IMEs.
There are a lot of security issues associated with input methods, since they essentially have freedom to completely drive the UI and monitor everything the user enters. The Android input method framework also allows arbitrary third party IMEs, so care must be taken to restrict their selection and interactions.
Here are some key points about the security architecture behind the IMF:
Only the system is allowed to directly access an IME's
InputMethod interface, via the
BIND_INPUT_METHOD permission. This is
enforced in the system by not binding to an input method service that does
not require this permission, so the system can guarantee no other untrusted
clients are accessing the current input method outside of its control.
There may be many client processes of the IMF, but only one may be active at a time. The inactive clients can not interact with key parts of the IMF through the mechanisms described below.
Clients of an input method are only given access to its
InputMethodSession interface. One instance of this interface is
created for each client, and only calls from the session associated with
the active client will be processed by the current IME. This is enforced
by AbstractInputMethodService for normal
IMEs, but must be explicitly handled by an IME that is customizing the
raw InputMethodSession implementation.
Only the active client's InputConnection will accept
operations. The IMF tells each client process whether it is active, and
the framework enforces that in inactive processes calls on to the current
InputConnection will be ignored. This ensures that the current IME can
only deliver events and text edits to the UI that the user sees as
being in focus.
An IME can never interact with an InputConnection while
the screen is off. This is enforced by making all clients inactive while
the screen is off, and prevents bad IMEs from driving the UI when the user
can not be aware of its behavior.
A client application can ask that the system let the user pick a new IME, but can not programmatically switch to one itself. This avoids malicious applications from switching the user to their own IME, which remains running when the user navigates away to another application. An IME, on the other hand, is allowed to programmatically switch the system to another IME, since it already has full control of user input.
The user must explicitly enable a new IME in settings before they can switch to it, to confirm with the system that they know about it and want to make it available for use.
| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| int | HIDE_IMPLICIT_ONLY | Flag for hideSoftInputFromWindow(IBinder, int) to indicate that the soft
input window should only be hidden if it was not explicitly shown
by the user. |
|||||||||
| int | HIDE_NOT_ALWAYS | Flag for hideSoftInputFromWindow(IBinder, int) to indicate that the soft
input window should normally be hidden, unless it was originally
shown with SHOW_FORCED. |
|||||||||
| int | RESULT_HIDDEN | Flag for the ResultReceiver result code from
showSoftInput(View, int, ResultReceiver) and
hideSoftInputFromWindow(IBinder, int, ResultReceiver): the
state of the soft input window changed from shown to hidden. |
|||||||||
| int | RESULT_SHOWN | Flag for the ResultReceiver result code from
showSoftInput(View, int, ResultReceiver) and
hideSoftInputFromWindow(IBinder, int, ResultReceiver): the
state of the soft input window changed from hidden to shown. |
|||||||||
| int | RESULT_UNCHANGED_HIDDEN | Flag for the ResultReceiver result code from
showSoftInput(View, int, ResultReceiver) and
hideSoftInputFromWindow(IBinder, int, ResultReceiver): the
state of the soft input window was unchanged and remains hidden. |
|||||||||
| int | RESULT_UNCHANGED_SHOWN | Flag for the ResultReceiver result code from
showSoftInput(View, int, ResultReceiver) and
hideSoftInputFromWindow(IBinder, int, ResultReceiver): the
state of the soft input window was unchanged and remains shown. |
|||||||||
| int | SHOW_FORCED | Flag for showSoftInput(View, int) to indicate that the user has forced
the input method open (such as by long-pressing menu) so it should
not be closed until they explicitly do so. |
|||||||||
| int | SHOW_IMPLICIT | Flag for showSoftInput(View, int) to indicate that this is an implicit
request to show the input window, not as the result of a direct request
by the user. |
|||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Returns the current input method subtype.
| |||||||||||
Returns a list of enabled input method subtypes for the specified input method info.
| |||||||||||
Returns a map of all shortcut input method info and their subtypes.
| |||||||||||
Close/hide the input method's soft input area, so the user no longer
sees it or can interact with it.
| |||||||||||
Synonym for
hideSoftInputFromWindow(IBinder, int, ResultReceiver)
without a result: request to hide the soft input window from the
context of the window that is currently accepting input. | |||||||||||
Request to hide the soft input window from the context of the window
that is currently accepting input.
| |||||||||||
Return true if the currently served view is accepting full text edits.
| |||||||||||
Return true if the given view is the currently active view for the
input method.
| |||||||||||
Return true if any view is currently active in the input method.
| |||||||||||
Allows you to discover whether the attached input method is running
in fullscreen mode.
| |||||||||||
Returns true if the current input method wants to watch the location
of the input editor's cursor in its window.
| |||||||||||
If the input method is currently connected to the given view,
restart it with its new contents.
| |||||||||||
Call
InputMethodSession.appPrivateCommand() on the current Input Method. | |||||||||||
Set additional input method subtypes.
| |||||||||||
Switch to a new input method subtype of the current input method.
| |||||||||||
Force switch to a new input method component.
| |||||||||||
Force switch to a new input method and subtype.
| |||||||||||
Returns true if the current IME needs to offer the users ways to switch to a next input
method (e.g.
| |||||||||||
Show the settings for enabling subtypes of the specified input method.
| |||||||||||
Explicitly request that the current input method's soft input area be
shown to the user, if needed.
| |||||||||||
Synonym for
showSoftInput(View, int, ResultReceiver) without
a result receiver: explicitly request that the current input method's
soft input area be shown to the user, if needed. | |||||||||||
Show the input method's soft input area, so the user
sees the input method window and can interact with it.
| |||||||||||
Force switch to the last used input method and subtype.
| |||||||||||
Force switch to the next input method and subtype.
| |||||||||||
This method toggles the input method window display.
| |||||||||||
Report the current cursor location in its window.
| |||||||||||
Report the current selection range.
| |||||||||||
Notify the event when the user tapped or clicked the text view.
| |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
Flag for hideSoftInputFromWindow(IBinder, int) to indicate that the soft
input window should only be hidden if it was not explicitly shown
by the user.
Flag for hideSoftInputFromWindow(IBinder, int) to indicate that the soft
input window should normally be hidden, unless it was originally
shown with SHOW_FORCED.
Flag for the ResultReceiver result code from
showSoftInput(View, int, ResultReceiver) and
hideSoftInputFromWindow(IBinder, int, ResultReceiver): the
state of the soft input window changed from shown to hidden.
Flag for the ResultReceiver result code from
showSoftInput(View, int, ResultReceiver) and
hideSoftInputFromWindow(IBinder, int, ResultReceiver): the
state of the soft input window changed from hidden to shown.
Flag for the ResultReceiver result code from
showSoftInput(View, int, ResultReceiver) and
hideSoftInputFromWindow(IBinder, int, ResultReceiver): the
state of the soft input window was unchanged and remains hidden.
Flag for the ResultReceiver result code from
showSoftInput(View, int, ResultReceiver) and
hideSoftInputFromWindow(IBinder, int, ResultReceiver): the
state of the soft input window was unchanged and remains shown.
Flag for showSoftInput(View, int) to indicate that the user has forced
the input method open (such as by long-pressing menu) so it should
not be closed until they explicitly do so.
Flag for showSoftInput(View, int) to indicate that this is an implicit
request to show the input window, not as the result of a direct request
by the user. The window may not be shown in this case.
Returns the current input method subtype. This subtype is one of the subtypes in the current input method. This method returns null when the current input method doesn't have any input method subtype.
Returns a list of enabled input method subtypes for the specified input method info.
| imi | An input method info whose subtypes list will be returned. |
|---|---|
| allowsImplicitlySelectedSubtypes | A boolean flag to allow to return the implicitly selected subtypes. If an input method info doesn't have enabled subtypes, the framework will implicitly enable subtypes according to the current system language. |
Returns a map of all shortcut input method info and their subtypes.
Close/hide the input method's soft input area, so the user no longer sees it or can interact with it. This can only be called from the currently active input method, as validated by the given token.
| token | Supplies the identifying token given to an input method when it was started, which allows it to perform this operation on itself. |
|---|---|
| flags | Provides additional operating flags. Currently may be
0 or have the HIDE_IMPLICIT_ONLY,
HIDE_NOT_ALWAYS bit set.
|
Synonym for hideSoftInputFromWindow(IBinder, int, ResultReceiver)
without a result: request to hide the soft input window from the
context of the window that is currently accepting input.
| windowToken | The token of the window that is making the request,
as returned by View.getWindowToken(). |
|---|---|
| flags | Provides additional operating flags. Currently may be
0 or have the HIDE_IMPLICIT_ONLY bit set.
|
Request to hide the soft input window from the context of the window that is currently accepting input. This should be called as a result of the user doing some actually than fairly explicitly requests to have the input window hidden.
| windowToken | The token of the window that is making the request,
as returned by View.getWindowToken(). |
|---|---|
| flags | Provides additional operating flags. Currently may be
0 or have the HIDE_IMPLICIT_ONLY bit set. |
| resultReceiver | If non-null, this will be called by the IME when
it has processed your request to tell you what it has done. The result
code you receive may be either RESULT_UNCHANGED_SHOWN,
RESULT_UNCHANGED_HIDDEN, RESULT_SHOWN, or
RESULT_HIDDEN.
|
Return true if the currently served view is accepting full text edits. If false, it has no input connection, so can only handle raw key events.
Return true if the given view is the currently active view for the input method.
Return true if any view is currently active in the input method.
Allows you to discover whether the attached input method is running in fullscreen mode. Return true if it is fullscreen, entirely covering your UI, else returns false.
Returns true if the current input method wants to watch the location of the input editor's cursor in its window.
If the input method is currently connected to the given view, restart it with its new contents. You should call this when the text within your view changes outside of the normal input method or key input flow, such as when an application calls TextView.setText().
| view | The view whose text has changed. |
|---|
Call InputMethodSession.appPrivateCommand() on the current Input Method.
| view | Optional View that is sending the command, or null if you want to send the command regardless of the view that is attached to the input method. |
|---|---|
| action | Name of the command to be performed. This must be a scoped name, i.e. prefixed with a package name you own, so that different developers will not create conflicting commands. |
| data | Any data to include with the command. |
Set additional input method subtypes. Only a process which shares the same uid with the IME
can add additional input method subtypes to the IME.
Please note that a subtype's status is stored in the system.
For example, enabled subtypes are remembered by the framework even after they are removed
by using this method. If you re-add the same subtypes again,
they will just get enabled. If you want to avoid such conflicts, for instance, you may
want to create a "different" new subtype even with the same locale and mode,
by changing its extra value. The different subtype won't get affected by the stored past
status. (You may want to take a look at hashCode() to refer
to the current implementation.)
| imiId | Id of InputMethodInfo which additional input method subtypes will be added to. |
|---|---|
| subtypes | subtypes will be added as additional subtypes of the current input method. |
Switch to a new input method subtype of the current input method.
| subtype | A new input method subtype to switch. |
|---|
Force switch to a new input method component. This can only be called from an application or a service which has a token of the currently active input method.
| token | Supplies the identifying token given to an input method when it was started, which allows it to perform this operation on itself. |
|---|---|
| id | The unique identifier for the new input method to be switched to. |
Force switch to a new input method and subtype. This can only be called from an application or a service which has a token of the currently active input method.
| token | Supplies the identifying token given to an input method when it was started, which allows it to perform this operation on itself. |
|---|---|
| id | The unique identifier for the new input method to be switched to. |
| subtype | The new subtype of the new input method to be switched to. |
Returns true if the current IME needs to offer the users ways to switch to a next input
method (e.g. a globe key.).
When an IME sets supportsSwitchingToNextInputMethod and this method returns true,
the IME has to offer ways to to invoke switchToNextInputMethod(IBinder, boolean) accordingly.
Note that the system determines the most appropriate next input method and subtype in order to provide the consistent user experience in switching between IMEs and subtypes.
| imeToken | Supplies the identifying token given to an input method when it was started, which allows it to perform this operation on itself. |
|---|
Show the settings for enabling subtypes of the specified input method.
| imiId | An input method, whose subtypes settings will be shown. If imiId is null, subtypes of all input methods will be shown. |
|---|
Explicitly request that the current input method's soft input area be shown to the user, if needed. Call this if the user interacts with your view in such a way that they have expressed they would like to start performing input into it.
| view | The currently focused view, which would like to receive soft keyboard input. |
|---|---|
| flags | Provides additional operating flags. Currently may be
0 or have the SHOW_IMPLICIT bit set. |
| resultReceiver | If non-null, this will be called by the IME when
it has processed your request to tell you what it has done. The result
code you receive may be either RESULT_UNCHANGED_SHOWN,
RESULT_UNCHANGED_HIDDEN, RESULT_SHOWN, or
RESULT_HIDDEN.
|
Synonym for showSoftInput(View, int, ResultReceiver) without
a result receiver: explicitly request that the current input method's
soft input area be shown to the user, if needed.
| view | The currently focused view, which would like to receive soft keyboard input. |
|---|---|
| flags | Provides additional operating flags. Currently may be
0 or have the SHOW_IMPLICIT bit set.
|
Show the input method's soft input area, so the user sees the input method window and can interact with it. This can only be called from the currently active input method, as validated by the given token.
| token | Supplies the identifying token given to an input method when it was started, which allows it to perform this operation on itself. |
|---|---|
| flags | Provides additional operating flags. Currently may be
0 or have the SHOW_IMPLICIT or
SHOW_FORCED bit set.
|
Force switch to the last used input method and subtype. If the last input method didn't have any subtypes, the framework will simply switch to the last input method with no subtype specified.
| imeToken | Supplies the identifying token given to an input method when it was started, which allows it to perform this operation on itself. |
|---|
Force switch to the next input method and subtype. If there is no IME enabled except current IME and subtype, do nothing.
| imeToken | Supplies the identifying token given to an input method when it was started, which allows it to perform this operation on itself. |
|---|---|
| onlyCurrentIme | if true, the framework will find the next subtype which belongs to the current IME |
This method toggles the input method window display. If the input window is already displayed, it gets hidden. If not the input window will be displayed.
| windowToken | The token of the window that is making the request,
as returned by View.getWindowToken(). |
|---|---|
| showFlags | Provides additional operating flags. May be
0 or have the SHOW_IMPLICIT,
SHOW_FORCED bit set. |
| hideFlags | Provides additional operating flags. May be
0 or have the HIDE_IMPLICIT_ONLY,
HIDE_NOT_ALWAYS bit set.
|
Report the current cursor location in its window.
Report the current selection range.
Notify the event when the user tapped or clicked the text view.