Added in API level 33

InputMethod.AccessibilityInputConnection


public final class InputMethod.AccessibilityInputConnection
extends Object

java.lang.Object
   ↳ android.accessibilityservice.InputMethod.AccessibilityInputConnection


This class provides the allowed list of InputConnection APIs for accessibility services.

Summary

Public methods

void clearMetaKeyStates(int states)

Clear the given meta key pressed states in the given input connection.

void commitText(CharSequence text, int newCursorPosition, TextAttribute textAttribute)

Commit text to the text box and set the new cursor position.

void 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.

int getCursorCapsMode(int reqModes)

Retrieve the current capitalization mode in effect at the current cursor position in the text.

SurroundingText getSurroundingText(int beforeLength, int afterLength, int flags)

Gets the surrounding text around the current cursor, with beforeLength characters of text before the cursor (start of the selection), afterLength characters of text after the cursor (end of the selection), and all of the selected text.

void performContextMenuAction(int id)

Perform a context menu action on the field.

void performEditorAction(int editorAction)

Have the editor perform an action it has said it can do.

void sendKeyEvent(KeyEvent event)

Send a key event to the process that is currently attached through this input connection.

void setSelection(int start, int end)

Set the selection of the text editor.

Inherited methods

Public methods

clearMetaKeyStates

Added in API level 33
public void clearMetaKeyStates (int states)

Clear the given meta key pressed states in the given input connection.

This can be used by the accessibility service to clear the meta key states set by a hardware keyboard with latched meta keys, if the editor keeps track of these.

Parameters
states int: The states to be cleared, may be one or more bits as per KeyEvent.getMetaState().

commitText

Added in API level 33
public void commitText (CharSequence text, 
                int newCursorPosition, 
                TextAttribute textAttribute)

Commit text to the text box and set the new cursor position. This method is used to allow the IME to provide extra information while setting up text.

This method commits the contents of the currently composing text, 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.

Calling this method will cause the editor to call InputMethod.onUpdateSelection(int, int, int, int, int, int) on the current accessibility service after the batch input is over. Editor authors, for this to happen you need to make the changes known to the accessibility service by calling InputMethodManager#updateSelection(android.view.View, int, int, int, int), but be careful to wait until the batch edit is over if one is in progress.

Parameters
text CharSequence: The text to commit. This may include styles. This value cannot be null.

newCursorPosition int: 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.

textAttribute TextAttribute: The extra information about the text. This value may be null.

deleteSurroundingText

Added in API level 33
public void 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. Before and after refer to the order of the characters in the string, not to their visual representation: this means you don't have to figure out the direction of the text and can just use the indices as-is.

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.

Accessibility service 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 InputMethod#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(android.view.View, int, int, int, int), but be careful to wait until the batch edit is over if one is in progress.

Parameters
beforeLength int: 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 int: 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.

getCursorCapsMode

Added in API level 33
public int getCursorCapsMode (int reqModes)

Retrieve the current capitalization mode in effect at the current cursor position in the text. See 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.

Parameters
reqModes int: 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.

Returns
int the caps mode flags that are in effect at the current cursor position. See TYPE_TEXT_FLAG_CAPS_* in InputType.

getSurroundingText

Added in API level 33
public SurroundingText getSurroundingText (int beforeLength, 
                int afterLength, 
                int flags)

Gets the surrounding text around the current cursor, with beforeLength characters of text before the cursor (start of the selection), afterLength characters of text after the cursor (end of the selection), and all of the selected text. The range are for java characters, not glyphs that can be multiple characters.

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), or the protocol is not supported. In any of these cases, 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 Spanned with all the spans set on the text.

Accessibility service authors: please consider this will trigger an IPC round-trip that will take some time. Assume this method consumes a lot of time.

Parameters
beforeLength int: The expected length of the text before the cursor. Value is 0 or greater

afterLength int: The expected length of the text after the cursor. Value is 0 or greater

flags int: Supplies additional options controlling how the text is returned. May be either 0 or InputConnection#GET_TEXT_WITH_STYLES. Value is either 0 or InputConnection.GET_TEXT_WITH_STYLES

Returns
SurroundingText an SurroundingText object describing the surrounding text and state of selection, or null if the input connection is no longer valid, or the editor can't comply with the request for some reason, or the application does not implement this method. The length of the returned text might be less than the sum of beforeLength and afterLength .

Throws
IllegalArgumentException if beforeLength or afterLength is negative.

performContextMenuAction

Added in API level 33
public void performContextMenuAction (int id)

Perform a context menu action on the field. The given id may be one of: R.id.selectAll, R.id.startSelectingText, R.id.stopSelectingText, R.id.cut, R.id.copy, R.id.paste, R.id.copyUrl, or R.id.switchInputMethod

Parameters
id int

performEditorAction

Added in API level 33
public void performEditorAction (int editorAction)

Have the editor perform an action it has said it can do.

Parameters
editorAction int: This must be one of the action constants for EditorInfo.imeOptions, such as EditorInfo.EDITOR_ACTION_GO, or the value of EditorInfo.actionId if a custom action is available.

sendKeyEvent

Added in API level 33
public void sendKeyEvent (KeyEvent event)

Send a key event to the process that is currently attached through this input connection. The event will be dispatched like a normal key event, to the currently focused view; this generally is the view that is providing this InputConnection, but due to the asynchronous nature of this protocol that can not be guaranteed and the focus may have changed by the time the event is received.

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 commitText(CharSequence, int, TextAttribute) family of methods to send text to the application instead.

Parameters
event KeyEvent: The key event. This value cannot be null.

setSelection

Added in API level 33
public void setSelection (int start, 
                int end)

Set the selection of the text editor. To set the cursor position, start and end should have the same value.

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(android.view.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.

Parameters
start int: the character index where the selection should start.

end int: the character index where the selection should end.