BaseInputConnection

public class BaseInputConnection
extends Object implements InputConnection

java.lang.Object
   ↳ android.view.inputmethod.BaseInputConnection


Base class for implementors of the InputConnection interface, taking care of most of the common behavior for providing a connection to an Editable. Implementors of this class will want to be sure to implement getEditable() to provide access to their own editable object, and to refer to the documentation in InputConnection.

Summary

Inherited constants

Public constructors

BaseInputConnection(View targetView, boolean fullEditor)

Public methods

boolean beginBatchEdit()

Default implementation does nothing.

boolean clearMetaKeyStates(int states)

Default implementation uses MetaKeyKeyListener.clearMetaKeyState(long, int) to clear the state.

void closeConnection()

Default implementation calls finishComposingText() and setImeConsumesInput(false).

boolean commitCompletion(CompletionInfo text)

Default implementation does nothing and returns false.

boolean commitContent(InputContentInfo inputContentInfo, int flags, Bundle opts)

Default implementation which invokes View#performReceiveContent on the target view if the view allows content insertion; otherwise returns false without any side effects.

boolean commitCorrection(CorrectionInfo correctionInfo)

Default implementation does nothing and returns false.

boolean commitText(CharSequence text, int newCursorPosition)

Default implementation replaces any existing composing text with the given text.

boolean deleteSurroundingText(int beforeLength, int afterLength)

The default implementation performs the deletion around the current selection position of the editable text.

boolean deleteSurroundingTextInCodePoints(int beforeLength, int afterLength)

The default implementation performs the deletion around the current selection position of the editable text.

boolean endBatchEdit()

Default implementation does nothing.

boolean finishComposingText()

The default implementation removes the composing state from the current editable text.

static int getComposingSpanEnd(Spannable text)

Return the end of the range of composing text, or -1 if there's no composing text.

static int getComposingSpanStart(Spannable text)

Return the beginning of the range of composing text, or -1 if there's no composing text.

int getCursorCapsMode(int reqModes)

The default implementation uses TextUtils.getCapsMode to get the cursor caps mode for the current selection position in the editable text, unless in fallback mode in which case 0 is always returned.

Editable getEditable()

Return the target of edit operations.

ExtractedText getExtractedText(ExtractedTextRequest request, int flags)

The default implementation always returns null.

Handler getHandler()

Called by the system to enable application developers to specify a dedicated thread on which InputConnection methods are called back.

CharSequence getSelectedText(int flags)

The default implementation returns the text currently selected, or null if none is selected.

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

The default implementation returns the given amount of text around the current cursor position in the buffer.

CharSequence getTextAfterCursor(int length, int flags)

The default implementation returns the given amount of text from the current cursor position in the buffer.

CharSequence getTextBeforeCursor(int length, int flags)

The default implementation returns the given amount of text from the current cursor position in the buffer.

boolean performContextMenuAction(int id)

The default implementation does nothing.

boolean performEditorAction(int actionCode)

The default implementation turns this into the enter key.

boolean performPrivateCommand(String action, Bundle data)

The default implementation does nothing.

static final void removeComposingSpans(Spannable text)

Removes the composing spans from the given text if any.

boolean replaceText(int start, int end, CharSequence text, int newCursorPosition, TextAttribute textAttribute)

Replace the specific range in the editor with suggested text.

boolean reportFullscreenMode(boolean enabled)

Updates InputMethodManager with the current fullscreen mode.

boolean requestCursorUpdates(int cursorUpdateMode)

The default implementation does nothing.

boolean sendKeyEvent(KeyEvent event)

Provides standard implementation for sending a key event to the window attached to the input connection's view.

boolean setComposingRegion(int start, int end)

Mark a certain region of text as composing text.

static void setComposingSpans(Spannable text)

Removes the composing spans from the given text if any.

boolean setComposingText(CharSequence text, int newCursorPosition)

The default implementation places the given text into the editable, replacing any existing composing text.

boolean setSelection(int start, int end)

The default implementation changes the selection position in the current editable text.

TextSnapshot takeSnapshot()

Default implementation that constructs TextSnapshot with information extracted from BaseInputConnection.

Inherited methods

Public constructors

BaseInputConnection

Added in API level 3
public BaseInputConnection (View targetView, 
                boolean fullEditor)

Parameters
targetView View: This value cannot be null.

fullEditor boolean

Public methods

beginBatchEdit

Added in API level 3
public boolean beginBatchEdit ()

Default implementation does nothing.

Returns
boolean true if a batch edit is now in progress, false otherwise. Since this method starts a batch edit, that means it will always return true unless the input connection is no longer valid.

clearMetaKeyStates

Added in API level 3
public boolean clearMetaKeyStates (int states)

Default implementation uses MetaKeyKeyListener.clearMetaKeyState(long, int) to clear the state.

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

Returns
boolean true on success, false if the input connection is no longer valid.

closeConnection

Added in API level 24
public void closeConnection ()

Default implementation calls finishComposingText() and setImeConsumesInput(false).
If you override this method you must call through to the superclass implementation.

commitCompletion

Added in API level 3
public boolean commitCompletion (CompletionInfo text)

Default implementation does nothing and returns false.

Parameters
text CompletionInfo: The committed completion.

Returns
boolean true on success, false if the input connection is no longer valid.

commitContent

Added in API level 25
public boolean commitContent (InputContentInfo inputContentInfo, 
                int flags, 
                Bundle opts)

Default implementation which invokes View#performReceiveContent on the target view if the view allows content insertion; otherwise returns false without any side effects.

Parameters
inputContentInfo InputContentInfo: Content to be inserted. This value cannot be null.

flags int: 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 Bundle: optional bundle data. This can be null.

Returns
boolean true if this request is accepted by the application, whether the request is already handled or still being handled in background, false otherwise.

commitCorrection

Added in API level 11
public boolean commitCorrection (CorrectionInfo correctionInfo)

Default implementation does nothing and returns false.

Parameters
correctionInfo CorrectionInfo: Detailed information about the correction.

Returns
boolean true on success, false if the input connection is no longer valid. Since Android Build.VERSION_CODES.N until Build.VERSION_CODES.TIRAMISU, this API returned false when the target application does not implement this method.

commitText

Added in API level 3
public boolean commitText (CharSequence text, 
                int newCursorPosition)

Default implementation replaces any existing composing text with the given text. In addition, only if fallback mode, a key event is sent for the new text and the current editable buffer cleared.

Parameters
text CharSequence: The text to commit. This may include styles.

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.

Returns
boolean true on success, false if the input connection is no longer valid.

deleteSurroundingText

Added in API level 3
public boolean deleteSurroundingText (int beforeLength, 
                int afterLength)

The default implementation performs the deletion around the current selection position of the editable text.

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.

Returns
boolean true when selected text is deleted, false when either the selection is invalid or not yet attached (i.e. selection start or end is -1), or the editable text is null.

deleteSurroundingTextInCodePoints

Added in API level 24
public boolean deleteSurroundingTextInCodePoints (int beforeLength, 
                int afterLength)

The default implementation performs the deletion around the current selection position of the editable text.

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

Returns
boolean true on success, false if the input connection is no longer valid. Before Android Build.VERSION_CODES.TIRAMISU, this API returned false when the target application does not implement this method.

endBatchEdit

Added in API level 3
public boolean endBatchEdit ()

Default implementation does nothing.

Returns
boolean For editor authors, you must return true if a batch edit is still in progress after closing the latest one (in other words, if the nesting count is still a positive number). Return false otherwise. For IME authors, you will always receive true as long as the request was sent to the editor, and receive false only if the input connection is no longer valid.

finishComposingText

Added in API level 3
public boolean finishComposingText ()

The default implementation removes the composing state from the current editable text. In addition, only if fallback mode, a key event is sent for the new text and the current editable buffer cleared.

Returns
boolean true on success, false if the input connection is no longer valid.

getComposingSpanEnd

Added in API level 3
public static int getComposingSpanEnd (Spannable text)

Return the end of the range of composing text, or -1 if there's no composing text.

Parameters
text Spannable: This value cannot be null.

Returns
int

getComposingSpanStart

Added in API level 3
public static int getComposingSpanStart (Spannable text)

Return the beginning of the range of composing text, or -1 if there's no composing text.

Parameters
text Spannable: This value cannot be null.

Returns
int

getCursorCapsMode

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

The default implementation uses TextUtils.getCapsMode to get the cursor caps mode for the current selection position in the editable text, unless in fallback mode in which case 0 is always returned.

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.

getEditable

Added in API level 3
public Editable getEditable ()

Return the target of edit operations. The default implementation returns its own fake editable that is just used for composing text; subclasses that are real text editors should override this and supply their own.

Subclasses could override this method to turn null.

Returns
Editable

getExtractedText

Added in API level 3
public ExtractedText getExtractedText (ExtractedTextRequest request, 
                int flags)

The default implementation always returns null.

Parameters
request ExtractedTextRequest: Description of how the text should be returned. ExtractedTextRequest

flags int: Additional options to control the client, either 0 or InputConnection.GET_EXTRACTED_TEXT_MONITOR.

Returns
ExtractedText an 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.

getHandler

Added in API level 24
public Handler getHandler ()

Called by the system to enable application developers to specify a dedicated thread on which InputConnection methods are called back.

Editor authors: although you can return your custom subclasses of Handler, the system only uses Looper returned from Handler#getLooper(). You cannot intercept or cancel InputConnection callbacks by implementing this method.

IME authors: This method is not intended to be called from the IME. You will always receive null.

Returns
Handler This value may be null.

getSelectedText

Added in API level 9
public CharSequence getSelectedText (int flags)

The default implementation returns the text currently selected, or null if none is selected.

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

Returns
CharSequence the text that is currently selected, if any, or null if no text is selected.

getSurroundingText

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

The default implementation returns the given amount of text around the current cursor position in the buffer.

Parameters
beforeLength int: Value is 0 or greater

afterLength int: 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 This value may be null.

getTextAfterCursor

Added in API level 3
public CharSequence getTextAfterCursor (int length, 
                int flags)

The default implementation returns the given amount of text from the current cursor position in the buffer.

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

Returns
CharSequence This value may be null.

getTextBeforeCursor

Added in API level 3
public CharSequence getTextBeforeCursor (int length, 
                int flags)

The default implementation returns the given amount of text from the current cursor position in the buffer.

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

Returns
CharSequence This value may be null.

performContextMenuAction

Added in API level 3
public boolean performContextMenuAction (int id)

The default implementation does nothing.

Parameters
id int

Returns
boolean

performEditorAction

Added in API level 3
public boolean performEditorAction (int actionCode)

The default implementation turns this into the enter key.

Parameters
actionCode 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.

Returns
boolean true on success, false if the input connection is no longer valid.

performPrivateCommand

Added in API level 3
public boolean performPrivateCommand (String action, 
                Bundle data)

The default implementation does nothing.

Parameters
action String: 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 Bundle: Any data to include with the command.

Returns
boolean true if the command was sent (whether or not the associated editor understood it), false if the input connection is no longer valid.

removeComposingSpans

Added in API level 3
public static final void removeComposingSpans (Spannable text)

Removes the composing spans from the given text if any.

Parameters
text Spannable: the spannable text to remove composing spans This value cannot be null.

replaceText

Added in API level 34
public boolean replaceText (int start, 
                int end, 
                CharSequence text, 
                int newCursorPosition, 
                TextAttribute textAttribute)

Replace the specific range in the editor with suggested text.

This method finishes whatever composing text is currently active and leaves the text as-it, replaces the specific range of text with the passed CharSequence, and then moves the cursor according to newCursorPosition. This behaves like calling finishComposingText(), setSelection(start, end), and then commitText(text, newCursorPosition, textAttribute).

Similar to setSelection(int, int), 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: Value is 0 or greater

end int: Value is 0 or greater

text CharSequence: This value cannot be null.

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

textAttribute TextAttribute: This value may be null.

Returns
boolean true if the replace command was sent to the associated editor (regardless of whether the replacement is success or not), false otherwise.

reportFullscreenMode

Added in API level 3
public boolean reportFullscreenMode (boolean enabled)

Updates InputMethodManager with the current fullscreen mode.

Parameters
enabled boolean

Returns
boolean For editor authors, the return value will always be ignored. For IME authors, this always returns true on Build.VERSION_CODES.N_MR1 and prior devices and false on Build.VERSION_CODES.O and later devices.

requestCursorUpdates

Added in API level 21
public boolean requestCursorUpdates (int cursorUpdateMode)

The default implementation does nothing.

Parameters
cursorUpdateMode int: any combination of update modes and filters: InputConnection.CURSOR_UPDATE_IMMEDIATE, InputConnection.CURSOR_UPDATE_MONITOR, and data filters: InputConnection.CURSOR_UPDATE_FILTER_CHARACTER_BOUNDS, InputConnection.CURSOR_UPDATE_FILTER_EDITOR_BOUNDS, InputConnection.CURSOR_UPDATE_FILTER_INSERTION_MARKER, InputConnection.CURSOR_UPDATE_FILTER_VISIBLE_LINE_BOUNDS, InputConnection.CURSOR_UPDATE_FILTER_TEXT_APPEARANCE. Pass 0 to disable them. However, if an unknown flag is provided, request will be rejected and method will return false.

Returns
boolean true if the request is scheduled. false to indicate that when the application will not call InputMethodManager#updateCursorAnchorInfo( android.view.View, CursorAnchorInfo). Since Android Build.VERSION_CODES.N until Build.VERSION_CODES.TIRAMISU, this API returned false when the target application does not implement this method.

sendKeyEvent

Added in API level 3
public boolean sendKeyEvent (KeyEvent event)

Provides standard implementation for sending a key event to the window attached to the input connection's view.

Parameters
event KeyEvent: The key event.

Returns
boolean true on success, false if the input connection is no longer valid.

setComposingRegion

Added in API level 9
public boolean setComposingRegion (int start, 
                int end)

Mark a certain region of text as composing text. If there was a composing region, the characters are left as they were and the composing span removed, as if 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 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.

Parameters
start int: the position in the text at which the composing region begins

end int: the position in the text at which the composing region ends

Returns
boolean true on success, false if the input connection is no longer valid. Since Android Build.VERSION_CODES.N until Build.VERSION_CODES.TIRAMISU, this API returned false when the target application does not implement this method.

setComposingSpans

Added in API level 3
public static void setComposingSpans (Spannable text)

Removes the composing spans from the given text if any.

Parameters
text Spannable: the spannable text to remove composing spans This value cannot be null.

setComposingText

Added in API level 3
public boolean setComposingText (CharSequence text, 
                int newCursorPosition)

The default implementation places the given text into the editable, replacing any existing composing text. The new text is marked as in a composing state with the composing style.

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

Returns
boolean true on success, false if the input connection is no longer valid.

setSelection

Added in API level 3
public boolean setSelection (int start, 
                int end)

The default implementation changes the selection position in the current editable text.

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

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

Returns
boolean true on success, false if the input connection is no longer valid.

takeSnapshot

Added in API level 33
public TextSnapshot takeSnapshot ()

Default implementation that constructs TextSnapshot with information extracted from BaseInputConnection.

Returns
TextSnapshot null when TextSnapshot cannot be fully taken.