public class InputConnectionWrapper extends Object implements InputConnection
CURSOR_UPDATE_IMMEDIATE, CURSOR_UPDATE_MONITOR, GET_EXTRACTED_TEXT_MONITOR, GET_TEXT_WITH_STYLES, INPUT_CONTENT_GRANT_READ_URI_PERMISSION
Constructor and Description |
---|
InputConnectionWrapper(WeakReference<AbstractInputMethodService> inputMethodService,
IInputContext inputContext,
int missingMethods) |
Modifier and Type | Method and Description |
---|---|
boolean |
beginBatchEdit()
Tell the editor that you are starting a batch of editor
operations.
|
boolean |
clearMetaKeyStates(int states)
Clear the given meta key pressed states in the given input
connection.
|
void |
closeConnection()
Called by the system up to only once to notify that the system is about to invalidate
connection between the input method and the application.
|
boolean |
commitCompletion(CompletionInfo text)
Commit a completion the user has selected from the possible ones
previously reported to
InputMethodSession#displayCompletions(CompletionInfo[]) or
InputMethodManager#displayCompletions(View, CompletionInfo[]) . |
boolean |
commitContent(InputContentInfo inputContentInfo,
int flags,
Bundle opts)
Called by the input method to commit content such as a PNG image to the editor.
|
boolean |
commitCorrection(CorrectionInfo correctionInfo)
Commit a correction automatically performed on the raw user's input.
|
boolean |
commitText(CharSequence text,
int newCursorPosition)
Commit text to the text box and set the new cursor position.
|
boolean |
deleteSurroundingText(int beforeLength,
int afterLength)
Delete beforeLength characters of text before the
current cursor position, and delete afterLength
characters of text after the current cursor position, excluding
the selection.
|
boolean |
deleteSurroundingTextInCodePoints(int beforeLength,
int afterLength)
A variant of
InputConnection.deleteSurroundingText(int, int) . |
boolean |
endBatchEdit()
Tell the editor that you are done with a batch edit previously
initiated with
InputConnection.beginBatchEdit() . |
boolean |
finishComposingText()
Have the text editor finish whatever composing text is
currently active.
|
int |
getCursorCapsMode(int reqModes)
Retrieve the current capitalization mode in effect at the
current cursor position in the text.
|
ExtractedText |
getExtractedText(ExtractedTextRequest request,
int flags)
Retrieve the current text in the input connection's editor, and
monitor for any changes to it.
|
Handler |
getHandler()
Called by the
InputMethodManager to enable application developers to specify a
dedicated Handler on which incoming IPC method calls from input methods will be
dispatched. |
CharSequence |
getSelectedText(int flags)
Gets the selected text, if any.
|
CharSequence |
getTextAfterCursor(int length,
int flags)
Get n characters of text after the current cursor
position.
|
CharSequence |
getTextBeforeCursor(int length,
int flags)
Get n characters of text before the current cursor
position.
|
boolean |
performContextMenuAction(int id)
Perform a context menu action on the field.
|
boolean |
performEditorAction(int actionCode)
Have the editor perform an action it has said it can do.
|
boolean |
performPrivateCommand(String action,
Bundle data)
API to send private commands from an input method to its
connected editor.
|
boolean |
reportFullscreenMode(boolean enabled)
Called by the IME to tell the client when it switches between
fullscreen and normal modes.
|
boolean |
requestCursorUpdates(int cursorUpdateMode)
Called by the input method to ask the editor for calling back
InputMethodManager.updateCursorAnchorInfo(android.view.View, CursorAnchorInfo) to
notify cursor/anchor locations. |
boolean |
sendKeyEvent(KeyEvent event)
Send a key event to the process that is currently attached
through this input connection.
|
boolean |
setComposingRegion(int start,
int end)
Mark a certain region of text as composing text.
|
boolean |
setComposingText(CharSequence text,
int newCursorPosition)
Replace the currently composing text with the given text, and
set the new cursor position.
|
boolean |
setSelection(int start,
int end)
Set the selection of the text editor.
|
String |
toString()
Returns a string representation of the object.
|
public InputConnectionWrapper(WeakReference<AbstractInputMethodService> inputMethodService, IInputContext inputContext, int missingMethods)
public CharSequence getTextAfterCursor(int length, int flags)
InputConnection
This method may fail either if the input connection has become invalid (such as its process crashing) or the client is taking too long to respond with the text (it is given a couple seconds to return). In either case, null is returned.
This method does not affect the text in the editor in any way, nor does it affect the selection or composing spans.
If InputConnection.GET_TEXT_WITH_STYLES
is supplied as flags, the
editor should return a SpannableString
with all the spans set on the text.
IME authors: please consider this will trigger an IPC round-trip that will take some time. Assume this method consumes a lot of time.
Editor authors: please be careful of race conditions in implementing this call. An IME can make a change to the text and use this method right away; you need to make sure the returned value is consistent with the result of the latest edits. Also, you may return less than n characters if performance dictates so, but keep in mind IMEs are relying on this for many functions: you should not, for example, limit the returned value to the current line, and specifically do not return 0 characters unless the cursor is really at the end of the text.
getTextAfterCursor
in interface InputConnection
length
- The expected length of the text.flags
- Supplies additional options controlling how the text is
returned. May be either 0 or InputConnection.GET_TEXT_WITH_STYLES
.public CharSequence getTextBeforeCursor(int length, int flags)
InputConnection
This method may fail either if the input connection has become invalid (such as its process crashing) or the editor is taking too long to respond with the text (it is given a couple seconds to return). In either case, null is returned. This method does not affect the text in the editor in any way, nor does it affect the selection or composing spans.
If InputConnection.GET_TEXT_WITH_STYLES
is supplied as flags, the
editor should return a SpannableString
with all the spans set on the text.
IME authors: please consider this will trigger an IPC round-trip that will take some time. Assume this method consumes a lot of time. Also, please keep in mind the Editor may choose to return less characters than requested even if they are available for performance reasons.
Editor authors: please be careful of race conditions in implementing this call. An IME can make a change to the text and use this method right away; you need to make sure the returned value is consistent with the result of the latest edits. Also, you may return less than n characters if performance dictates so, but keep in mind IMEs are relying on this for many functions: you should not, for example, limit the returned value to the current line, and specifically do not return 0 characters unless the cursor is really at the start of the text.
getTextBeforeCursor
in interface InputConnection
length
- The expected length of the text.flags
- Supplies additional options controlling how the text is
returned. May be either 0 or InputConnection.GET_TEXT_WITH_STYLES
.public CharSequence getSelectedText(int flags)
InputConnection
This method may fail if either the input connection has become invalid (such as its process crashing) or the client is taking too long to respond with the text (it is given a couple of seconds to return). In either case, null is returned.
This method must not cause any changes in the editor's state.
If InputConnection.GET_TEXT_WITH_STYLES
is supplied as flags, the
editor should return a SpannableString
with all the spans set on the text.
IME authors: please consider this will trigger an IPC round-trip that will take some time. Assume this method consumes a lot of time.
Editor authors: please be careful of race conditions in implementing this call. An IME can make a change to the text or change the selection position and use this method right away; you need to make sure the returned value is consistent with the results of the latest edits.
getSelectedText
in interface InputConnection
flags
- Supplies additional options controlling how the text is
returned. May be either 0 or InputConnection.GET_TEXT_WITH_STYLES
.Build.VERSION_CODES.N
and
later, returns false when the target application does not implement
this method.public int getCursorCapsMode(int reqModes)
InputConnection
TextUtils.getCapsMode
for more information.
This method may fail either if the input connection has become invalid (such as its process crashing) or the client is taking too long to respond with the text (it is given a couple seconds to return). In either case, 0 is returned.
This method does not affect the text in the editor in any way, nor does it affect the selection or composing spans.
Editor authors: please be careful of race conditions in implementing this call. An IME can change the cursor position and use this method right away; you need to make sure the returned value is consistent with the results of the latest edits and changes to the cursor position.
getCursorCapsMode
in interface InputConnection
reqModes
- The desired modes to retrieve, as defined by
TextUtils.getCapsMode
. These
constants are defined so that you can simply pass the current
TextBoxAttribute.contentType
value
directly in to here.InputType
.public ExtractedText getExtractedText(ExtractedTextRequest request, int flags)
InputConnection
This method may fail either if the input connection has become invalid (such as its process crashing) or the client is taking too long to respond with the text (it is given a couple seconds to return). In either case, null is returned.
Editor authors: as a general rule, try to comply with the
fields in request
for how many chars to return,
but if performance or convenience dictates otherwise, please
feel free to do what is most appropriate for your case. Also,
if the
InputConnection.GET_EXTRACTED_TEXT_MONITOR
flag is set, you should be
calling
InputMethodManager.updateExtractedText(View, int, ExtractedText)
whenever you call
InputMethodManager.updateSelection(View, int, int, int, int)
.
getExtractedText
in interface InputConnection
request
- Description of how the text should be returned.
ExtractedTextRequest
flags
- Additional options to control the client, either 0 or
InputConnection.GET_EXTRACTED_TEXT_MONITOR
.ExtractedText
object describing the state of the text view and containing the
extracted text itself, or null if the input connection is no
longer valid of the editor can't comply with the request for
some reason.public boolean commitText(CharSequence text, int newCursorPosition)
InputConnection
This method removes the contents of the currently composing
text and replaces it with the passed CharSequence, and then
moves the cursor according to newCursorPosition
. If there
is no composing text when this method is called, the new text is
inserted at the cursor position, removing text inside the selection
if any. This behaves like calling
setComposingText(text, newCursorPosition)
then InputConnection.finishComposingText()
.
Calling this method will cause the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors, for this to happen you need to
make the changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
commitText
in interface InputConnection
text
- The text to commit. This may include styles.newCursorPosition
- The new cursor position around the text,
in Java characters. If > 0, this is relative to the end
of the text - 1; if <= 0, this is relative to the start
of the text. So a value of 1 will always advance the cursor
to the position after the full text being inserted. Note that
this means you can't position the cursor within the text,
because the editor can make modifications to the text
you are providing so it is not possible to correctly specify
locations there.public boolean commitCompletion(CompletionInfo text)
InputConnection
InputMethodSession#displayCompletions(CompletionInfo[])
or
InputMethodManager#displayCompletions(View, CompletionInfo[])
.
This will result in the same behavior as if the user had
selected the completion from the actual UI. In all other
respects, this behaves like InputConnection.commitText(CharSequence, int)
.
IME authors: please take care to send the
same object that you received through
InputMethodService.onDisplayCompletions(CompletionInfo[])
.
Editor authors: if you never call
InputMethodSession.displayCompletions(CompletionInfo[])
or
InputMethodManager.displayCompletions(View, CompletionInfo[])
then
a well-behaved IME should never call this on your input
connection, but be ready to deal with misbehaving IMEs without
crashing.
Calling this method (with a valid CompletionInfo
object)
will cause the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors, for this to happen you need to
make the changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
commitCompletion
in interface InputConnection
text
- The committed completion.public boolean commitCorrection(CorrectionInfo correctionInfo)
InputConnection
Calling this method will cause the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors, for this to happen you need to
make the changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
commitCorrection
in interface InputConnection
correctionInfo
- Detailed information about the correction.Build.VERSION_CODES.N
and later, returns false
when the target application does not implement this method.public boolean setSelection(int start, int end)
InputConnection
Since this moves the cursor, calling this method will cause
the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors, for this to happen you need to
make the changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
This has no effect on the composing region which must stay unchanged. The order of start and end is not important. In effect, the region from start to end and the region from end to start is the same. Editor authors, be ready to accept a start that is greater than end.
setSelection
in interface InputConnection
start
- the character index where the selection should start.end
- the character index where the selection should end.public boolean performEditorAction(int actionCode)
InputConnection
This is typically used by IMEs when the user presses the key associated with the action.
performEditorAction
in interface InputConnection
actionCode
- This must be one of the action constants for
EditorInfo.editorType
, such as
EditorInfo.EDITOR_ACTION_GO
.public boolean performContextMenuAction(int id)
InputConnection
android.R.id#selectAll
,
android.R.id#startSelectingText
, android.R.id#stopSelectingText
,
android.R.id#cut
, android.R.id#copy
,
android.R.id#paste
, android.R.id#copyUrl
,
or android.R.id#switchInputMethod
performContextMenuAction
in interface InputConnection
public boolean setComposingRegion(int start, int end)
InputConnection
InputConnection.finishComposingText()
has been called. The default style for composing text is used.
The passed indices are clipped to the contents bounds. If
the resulting region is zero-sized, no region is marked and the
effect is the same as that of calling InputConnection.finishComposingText()
.
The order of start and end is not important. In effect, the
region from start to end and the region from end to start is
the same. Editor authors, be ready to accept a start that is
greater than end.
Since this does not change the contents of the text, editors should not call
InputMethodManager.updateSelection(View, int, int, int, int)
and
IMEs should not receive
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
.
This has no impact on the cursor/selection position. It may result in the cursor being anywhere inside or outside the composing region, including cases where the selection and the composing region overlap partially or entirely.
setComposingRegion
in interface InputConnection
start
- the position in the text at which the composing region beginsend
- the position in the text at which the composing region endsBuild.VERSION_CODES.N
and later, false is returned when the
target application does not implement this method.public boolean setComposingText(CharSequence text, int newCursorPosition)
InputConnection
If there is any composing span currently active, all
characters that it comprises are removed. The passed text is
added in its place, and a composing span is added to this
text. If there is no composing span active, the passed text is
added at the cursor position (removing selected characters
first if any), and a composing span is added on the new text.
Finally, the cursor is moved to the location specified by
newCursorPosition
.
This is usually called by IMEs to add or remove or change
characters in the composing span. Calling this method will
cause the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on the current IME after the batch input is over.
Editor authors: please keep in mind the
text may be very similar or completely different than what was
in the composing span at call time, or there may not be a
composing span at all. Please note that although it's not
typical use, the string may be empty. Treat this normally,
replacing the currently composing text with an empty string.
Also, be careful with the cursor position. IMEs rely on this
working exactly as described above. Since this changes the
contents of the editor, you need to make the changes known to
the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress. Note that this method can set the cursor position
on either edge of the composing text or entirely outside it,
but the IME may also go on to move the cursor position to
within the composing text in a subsequent call so you should
make no assumption at all: the composing text and the selection
are entirely independent.
setComposingText
in interface InputConnection
text
- The composing text with styles if necessary. If no style
object attached to the text, the default style for composing text
is used. See Spanned
for how to attach style
object to the text. SpannableString
and
SpannableStringBuilder
are two
implementations of the interface Spanned
.newCursorPosition
- The new cursor position around the text. If
> 0, this is relative to the end of the text - 1; if <= 0, this
is relative to the start of the text. So a value of 1 will
always advance you to the position after the full text being
inserted. Note that this means you can't position the cursor
within the text, because the editor can make modifications to
the text you are providing so it is not possible to correctly
specify locations there.public boolean finishComposingText()
InputConnection
IME authors: be aware that this call may be expensive with some editors.
Editor authors: please note that the cursor may be anywhere in the contents when this is called, including in the middle of the composing span or in a completely unrelated place. It must not move.
finishComposingText
in interface InputConnection
public boolean beginBatchEdit()
InputConnection
InputConnection.endBatchEdit()
is called. Batch
edits nest.
IME authors: use this to avoid getting
calls to
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
corresponding to intermediate state. Also, use this to avoid
flickers that may arise from displaying intermediate state. Be
sure to call InputConnection.endBatchEdit()
for each call to this, or
you may block updates in the editor.
Editor authors: while a batch edit is in progress, take care not to send updates to the input method and not to update the display. IMEs use this intensively to this effect. Also please note that batch edits need to nest correctly.
beginBatchEdit
in interface InputConnection
public boolean endBatchEdit()
InputConnection
InputConnection.beginBatchEdit()
. This ends the latest
batch only.
IME authors: make sure you call this
exactly once for each call to InputConnection.beginBatchEdit()
.
Editor authors: please be careful about batch edit nesting. Updates still to be held back until the end of the last batch edit.
endBatchEdit
in interface InputConnection
public boolean sendKeyEvent(KeyEvent event)
InputConnection
This method can be used to send key events to the application. For example, an on-screen keyboard may use this method to simulate a hardware keyboard. There are three types of standard keyboards, numeric (12-key), predictive (20-key) and ALPHA (QWERTY). You can specify the keyboard type by specify the device id of the key event.
You will usually want to set the flag
KeyEvent.FLAG_SOFT_KEYBOARD
on all key event objects you give to this API; the flag will
not be set for you.
Note that it's discouraged to send such key events in normal
operation; this is mainly for use with
InputType.TYPE_NULL
type text fields. Use
the InputConnection.commitText(java.lang.CharSequence, int)
family of methods to send text to the
application instead.
sendKeyEvent
in interface InputConnection
event
- The key event.KeyEvent
,
KeyCharacterMap.NUMERIC
,
KeyCharacterMap.PREDICTIVE
,
KeyCharacterMap.ALPHA
public boolean clearMetaKeyStates(int states)
InputConnection
This can be used by the IME to clear the meta key states set by a hardware keyboard with latched meta keys, if the editor keeps track of these.
clearMetaKeyStates
in interface InputConnection
states
- The states to be cleared, may be one or more bits as
per KeyEvent.getMetaState()
.public boolean deleteSurroundingText(int beforeLength, int afterLength)
InputConnection
The lengths are supplied in Java chars, not in code points or in glyphs.
Since this method only operates on text before and after the selection, it can't affect the contents of the selection. This may affect the composing span if the span includes characters that are to be deleted, but otherwise will not change it. If some characters in the composing span are deleted, the composing span will persist but get shortened by however many chars inside it have been removed.
IME authors: please be careful not to
delete only half of a surrogate pair. Also take care not to
delete more characters than are in the editor, as that may have
ill effects on the application. Calling this method will cause
the editor to call
InputMethodService.onUpdateSelection(int, int, int, int, int, int)
on your service after the batch input is over.
Editor authors: please be careful of race
conditions in implementing this call. An IME can make a change
to the text or change the selection position and use this
method right away; you need to make sure the effects are
consistent with the results of the latest edits. Also, although
the IME should not send lengths bigger than the contents of the
string, you should check the values for overflows and trim the
indices to the size of the contents to avoid crashes. Since
this changes the contents of the editor, you need to make the
changes known to the input method by calling
InputMethodManager.updateSelection(View, int, int, int, int)
,
but be careful to wait until the batch edit is over if one is
in progress.
deleteSurroundingText
in interface InputConnection
beforeLength
- The number of characters before the cursor to be deleted, in code unit.
If this is greater than the number of existing characters between the beginning of the
text and the cursor, then this method does not fail but deletes all the characters in
that range.afterLength
- The number of characters after the cursor to be deleted, in code unit.
If this is greater than the number of existing characters between the cursor and
the end of the text, then this method does not fail but deletes all the characters in
that range.public boolean deleteSurroundingTextInCodePoints(int beforeLength, int afterLength)
InputConnection
InputConnection.deleteSurroundingText(int, int)
. Major differences are:
Editor authors: In addition to the requirement in
InputConnection.deleteSurroundingText(int, int)
, make sure to do nothing when one ore more invalid
surrogate pairs are found in the requested range.
deleteSurroundingTextInCodePoints
in interface InputConnection
beforeLength
- The number of characters before the cursor to be deleted, in code points.
If this is greater than the number of existing characters between the beginning of the
text and the cursor, then this method does not fail but deletes all the characters in
that range.afterLength
- The number of characters after the cursor to be deleted, in code points.
If this is greater than the number of existing characters between the cursor and
the end of the text, then this method does not fail but deletes all the characters in
that range.false
when the target application does not implement this method.InputConnection.deleteSurroundingText(int, int)
public boolean reportFullscreenMode(boolean enabled)
InputConnection
InputMethodService
.reportFullscreenMode
in interface InputConnection
public boolean performPrivateCommand(String action, Bundle data)
InputConnection
EditorInfo
to determine if a client
supports a particular command.performPrivateCommand
in interface InputConnection
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 boolean requestCursorUpdates(int cursorUpdateMode)
InputConnection
InputMethodManager.updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)
to
notify cursor/anchor locations.requestCursorUpdates
in interface InputConnection
cursorUpdateMode
- InputConnection.CURSOR_UPDATE_IMMEDIATE
and/or
InputConnection.CURSOR_UPDATE_MONITOR
. Pass 0
to disable the effect of
InputConnection.CURSOR_UPDATE_MONITOR
.true
if the request is scheduled. false
to indicate that when the
application will not call
InputMethodManager.updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)
.
In Build.VERSION_CODES.N
and later, returns false
also when the
target application does not implement this method.public Handler getHandler()
InputConnection
InputMethodManager
to enable application developers to specify a
dedicated Handler
on which incoming IPC method calls from input methods will be
dispatched.
Note: This does nothing when called from input methods.
getHandler
in interface InputConnection
null
to use the default Handler
.public void closeConnection()
InputConnection
Editor authors: You can clear all the nested batch edit right now and
you no longer need to handle subsequent callbacks on this connection, including
InputConnection.beginBatchEdit()
}. Note that although the system tries to call this method whenever
possible, there may be a chance that this method is not called in some exceptional
situations.
Note: This does nothing when called from input methods.
closeConnection
in interface InputConnection
public boolean commitContent(InputContentInfo inputContentInfo, int flags, Bundle opts)
InputConnection
In order to avoid a variety of compatibility issues, this focuses on a simple use case, where editors and IMEs are expected to work cooperatively as follows:
EditorInfo.contentMimeTypes
equal to null
if it does
not support this method at all.inputContentInfo
does not match any of EditorInfo.contentMimeTypes
.
true
asynchronously, even before it starts loading the
content.EditorInfo.packageName
about how to obtain the package name of the editor.commitContent
in interface InputConnection
inputContentInfo
- Content to be inserted.flags
- InputConnection.INPUT_CONTENT_GRANT_READ_URI_PERMISSION
if the content provider
allows grantUriPermissions
or 0
if the application does not need to call
InputContentInfo.requestPermission()
.opts
- optional bundle data. This can be null
.true
if this request is accepted by the application, whether the request
is already handled or still being handled in background, false
otherwise.public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())