public final class InputMethodManager extends Object
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:
android.R.attr#inputType
in your editable
text views, so that the input method will have enough context to help the
user in entering text into them.
android.R.attr#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).
android.R.attr#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 View.onCreateInputConnection(android.view.inputmethod.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
android.Manifest.permission#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.
Modifier and Type | Class and Description |
---|---|
static interface |
InputMethodManager.FinishedEventCallback
Callback that is invoked when an input event that was dispatched to
the IME has been finished.
|
Modifier and Type | Field and Description |
---|---|
static int |
CONTROL_START_INITIAL |
static int |
CONTROL_WINDOW_FIRST |
static int |
CONTROL_WINDOW_IS_TEXT_EDITOR |
static int |
CONTROL_WINDOW_VIEW_HAS_FOCUS |
static int |
HIDE_IMPLICIT_ONLY
Flag for
hideSoftInputFromWindow(android.os.IBinder, int) to indicate that the soft
input window should only be hidden if it was not explicitly shown
by the user. |
static int |
HIDE_NOT_ALWAYS
Flag for
hideSoftInputFromWindow(android.os.IBinder, int) to indicate that the soft
input window should normally be hidden, unless it was originally
shown with SHOW_FORCED . |
static 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. |
static 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. |
static 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. |
static 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. |
static int |
SHOW_FORCED
Flag for
showSoftInput(android.view.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. |
static int |
SHOW_IMPLICIT
Flag for
showSoftInput(android.view.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. |
Modifier and Type | Method and Description |
---|---|
void |
checkFocus() |
void |
dispatchGenericMotionEvent(Context context,
int seq,
MotionEvent motion,
InputMethodManager.FinishedEventCallback callback) |
void |
dispatchKeyEvent(Context context,
int seq,
KeyEvent key,
InputMethodManager.FinishedEventCallback callback) |
void |
dispatchTrackballEvent(Context context,
int seq,
MotionEvent motion,
InputMethodManager.FinishedEventCallback callback) |
void |
displayCompletions(View view,
CompletionInfo[] completions) |
void |
focusIn(View view)
Call this when a view receives focus.
|
void |
focusOut(View view)
Call this when a view loses focus.
|
IInputMethodClient |
getClient() |
InputMethodSubtype |
getCurrentInputMethodSubtype()
Returns the current input method subtype.
|
List<InputMethodInfo> |
getEnabledInputMethodList() |
List<InputMethodSubtype> |
getEnabledInputMethodSubtypeList(InputMethodInfo imi,
boolean allowsImplicitlySelectedSubtypes)
Returns a list of enabled input method subtypes for the specified input method info.
|
IInputContext |
getInputContext() |
List<InputMethodInfo> |
getInputMethodList() |
static InputMethodManager |
getInstance(Context context)
Retrieve the global InputMethodManager instance, creating it if it
doesn't already exist.
|
static InputMethodManager |
getInstance(Looper mainLooper)
Internally, the input method manager can't be context-dependent, so
we have this here for the places that need it.
|
InputMethodSubtype |
getLastInputMethodSubtype() |
Map<InputMethodInfo,List<InputMethodSubtype>> |
getShortcutInputMethodsAndSubtypes()
Returns a map of all shortcut input method info and their subtypes.
|
void |
hideSoftInputFromInputMethod(IBinder token,
int flags)
Close/hide the input method's soft input area, so the user no longer
sees it or can interact with it.
|
boolean |
hideSoftInputFromWindow(IBinder windowToken,
int flags)
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. |
boolean |
hideSoftInputFromWindow(IBinder windowToken,
int flags,
ResultReceiver resultReceiver)
Request to hide the soft input window from the context of the window
that is currently accepting input.
|
void |
hideStatusIcon(IBinder imeToken) |
boolean |
isAcceptingText()
Return true if the currently served view is accepting full text edits.
|
boolean |
isActive()
Return true if any view is currently active in the input method.
|
boolean |
isActive(View view)
Return true if the given view is the currently active view for the
input method.
|
boolean |
isFullscreenMode()
Allows you to discover whether the attached input method is running
in fullscreen mode.
|
boolean |
isWatchingCursor(View view)
Returns true if the current input method wants to watch the location
of the input editor's cursor in its window.
|
void |
notifySuggestionPicked(SuggestionSpan span,
String originalString,
int index) |
void |
onWindowFocus(View rootView,
View focusedView,
int softInputMode,
boolean first,
int windowFlags)
Called by ViewAncestor when its window gets input focus.
|
static InputMethodManager |
peekInstance()
Private optimization: retrieve the global InputMethodManager instance,
if it exists.
|
void |
registerSuggestionSpansForNotification(SuggestionSpan[] spans) |
void |
reportFinishInputConnection(InputConnection ic)
Called from the FINISH_INPUT_CONNECTION message above.
|
void |
restartInput(View view)
If the input method is currently connected to the given view,
restart it with its new contents.
|
void |
sendAppPrivateCommand(View view,
String action,
Bundle data)
Call
InputMethodSession.appPrivateCommand() on the current Input Method. |
void |
setAdditionalInputMethodSubtypes(String imiId,
InputMethodSubtype[] subtypes)
Set additional input method subtypes.
|
boolean |
setCurrentInputMethodSubtype(InputMethodSubtype subtype)
Switch to a new input method subtype of the current input method.
|
void |
setFullscreenMode(boolean fullScreen) |
void |
setImeWindowStatus(IBinder imeToken,
int vis,
int backDisposition) |
void |
setInputMethod(IBinder token,
String id)
Force switch to a new input method component.
|
void |
setInputMethodAndSubtype(IBinder token,
String id,
InputMethodSubtype subtype)
Force switch to a new input method and subtype.
|
void |
showInputMethodAndSubtypeEnabler(String imiId)
Show the settings for enabling subtypes of the specified input method.
|
void |
showInputMethodPicker() |
boolean |
showSoftInput(View view,
int flags)
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. |
boolean |
showSoftInput(View view,
int flags,
ResultReceiver resultReceiver)
Explicitly request that the current input method's soft input area be
shown to the user, if needed.
|
void |
showSoftInputFromInputMethod(IBinder token,
int flags)
Show the input method's soft input area, so the user
sees the input method window and can interact with it.
|
void |
showSoftInputUnchecked(int flags,
ResultReceiver resultReceiver) |
void |
showStatusIcon(IBinder imeToken,
String packageName,
int iconId) |
void |
startGettingWindowFocus(View rootView) |
boolean |
switchToLastInputMethod(IBinder imeToken)
Force switch to the last used input method and subtype.
|
boolean |
switchToNextInputMethod(IBinder imeToken,
boolean onlyCurrentIme)
Force switch to the next input method and subtype.
|
void |
toggleSoftInput(int showFlags,
int hideFlags) |
void |
toggleSoftInputFromWindow(IBinder windowToken,
int showFlags,
int hideFlags)
This method toggles the input method window display.
|
void |
updateCursor(View view,
int left,
int top,
int right,
int bottom)
Report the current cursor location in its window.
|
void |
updateExtractedText(View view,
int token,
ExtractedText text) |
void |
updateSelection(View view,
int selStart,
int selEnd,
int candidatesStart,
int candidatesEnd)
Report the current selection range.
|
void |
viewClicked(View view)
Notify the event when the user tapped or clicked the text view.
|
void |
windowDismissed(IBinder appWindowToken)
When the focused window is dismissed, this method is called to finish the
input method started before.
|
public static final int CONTROL_WINDOW_VIEW_HAS_FOCUS
public static final int CONTROL_WINDOW_IS_TEXT_EDITOR
public static final int CONTROL_WINDOW_FIRST
public static final int CONTROL_START_INITIAL
public static final int SHOW_IMPLICIT
showSoftInput(android.view.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.public static final int SHOW_FORCED
showSoftInput(android.view.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.public static final int RESULT_UNCHANGED_SHOWN
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.public static final int RESULT_UNCHANGED_HIDDEN
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.public static final int RESULT_SHOWN
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.public static final int RESULT_HIDDEN
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.public static final int HIDE_IMPLICIT_ONLY
hideSoftInputFromWindow(android.os.IBinder, int)
to indicate that the soft
input window should only be hidden if it was not explicitly shown
by the user.public static final int HIDE_NOT_ALWAYS
hideSoftInputFromWindow(android.os.IBinder, int)
to indicate that the soft
input window should normally be hidden, unless it was originally
shown with SHOW_FORCED
.public static InputMethodManager getInstance(Context context)
public static InputMethodManager getInstance(Looper mainLooper)
public static InputMethodManager peekInstance()
public IInputMethodClient getClient()
public IInputContext getInputContext()
public List<InputMethodInfo> getInputMethodList()
public List<InputMethodInfo> getEnabledInputMethodList()
public List<InputMethodSubtype> getEnabledInputMethodSubtypeList(InputMethodInfo imi, boolean allowsImplicitlySelectedSubtypes)
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.public void hideStatusIcon(IBinder imeToken)
public void setImeWindowStatus(IBinder imeToken, int vis, int backDisposition)
public void setFullscreenMode(boolean fullScreen)
public void registerSuggestionSpansForNotification(SuggestionSpan[] spans)
public void notifySuggestionPicked(SuggestionSpan span, String originalString, int index)
public boolean isFullscreenMode()
public boolean isActive(View view)
public boolean isActive()
public boolean isAcceptingText()
public void reportFinishInputConnection(InputConnection ic)
public void displayCompletions(View view, CompletionInfo[] completions)
public void updateExtractedText(View view, int token, ExtractedText text)
public boolean showSoftInput(View view, int flags)
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.public boolean showSoftInput(View view, int flags, ResultReceiver resultReceiver)
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
.public void showSoftInputUnchecked(int flags, ResultReceiver resultReceiver)
public boolean hideSoftInputFromWindow(IBinder windowToken, int flags)
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.public boolean hideSoftInputFromWindow(IBinder windowToken, int flags, ResultReceiver resultReceiver)
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
.public void toggleSoftInputFromWindow(IBinder windowToken, int showFlags, int hideFlags)
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.public void toggleSoftInput(int showFlags, int hideFlags)
public void restartInput(View view)
view
- The view whose text has changed.public void windowDismissed(IBinder appWindowToken)
public void focusIn(View view)
public void focusOut(View view)
public void checkFocus()
public void onWindowFocus(View rootView, View focusedView, int softInputMode, boolean first, int windowFlags)
public void startGettingWindowFocus(View rootView)
public void updateSelection(View view, int selStart, int selEnd, int candidatesStart, int candidatesEnd)
public void viewClicked(View view)
public boolean isWatchingCursor(View view)
public void updateCursor(View view, int left, int top, int right, int bottom)
public void sendAppPrivateCommand(View view, String action, Bundle data)
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.public void setInputMethod(IBinder token, String id)
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.public void setInputMethodAndSubtype(IBinder token, String id, InputMethodSubtype subtype)
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.public void hideSoftInputFromInputMethod(IBinder token, int flags)
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.public void showSoftInputFromInputMethod(IBinder token, int flags)
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.public void dispatchKeyEvent(Context context, int seq, KeyEvent key, InputMethodManager.FinishedEventCallback callback)
public void dispatchTrackballEvent(Context context, int seq, MotionEvent motion, InputMethodManager.FinishedEventCallback callback)
public void dispatchGenericMotionEvent(Context context, int seq, MotionEvent motion, InputMethodManager.FinishedEventCallback callback)
public void showInputMethodPicker()
public void showInputMethodAndSubtypeEnabler(String imiId)
imiId
- An input method, whose subtypes settings will be shown. If imiId is null,
subtypes of all input methods will be shown.public InputMethodSubtype getCurrentInputMethodSubtype()
public boolean setCurrentInputMethodSubtype(InputMethodSubtype subtype)
subtype
- A new input method subtype to switch.public Map<InputMethodInfo,List<InputMethodSubtype>> getShortcutInputMethodsAndSubtypes()
public boolean switchToLastInputMethod(IBinder imeToken)
imeToken
- Supplies the identifying token given to an input method when it was started,
which allows it to perform this operation on itself.public boolean switchToNextInputMethod(IBinder imeToken, boolean onlyCurrentIme)
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 IMEpublic void setAdditionalInputMethodSubtypes(String imiId, InputMethodSubtype[] subtypes)
InputMethodSubtype.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.public InputMethodSubtype getLastInputMethodSubtype()