Android APIs
Added in API level 3
public interface

InputConnection

android.view.inputmethod.InputConnection
Known Indirect Subclasses

Class Overview

The InputConnection interface is the communication channel from an InputMethod back to the application that is receiving its input. It is used to perform such things as reading text around the cursor, committing text to the text box, and sending raw key events to the application.

Applications should never directly implement this interface, but instead subclass from BaseInputConnection. This will ensure that the application does not break when new methods are added to the interface.

Implementing an IME or an editor

Text input is the result of the synergy of two essential components: an Input Method Engine (IME) and an editor. The IME can be a software keyboard, a handwriting interface, an emoji palette, a speech-to-text engine, and so on. There are typically several IMEs installed on any given Android device. In Android, IMEs extend InputMethodService. For more information about how to create an IME, see the Creating an input method guide. The editor is the component that receives text and displays it. Typically, this is an EditText instance, but some applications may choose to implement their own editor for various reasons. This is a large and complicated task, and an application that does this needs to make sure the behavior is consistent with standard EditText behavior in Android. An editor needs to interact with the IME, receiving commands through this InputConnection interface, and sending commands through InputMethodManager. An editor should start by implementing onCreateInputConnection(EditorInfo) to return its own input connection.

If you are implementing your own IME, you will need to call the methods in this interface to interact with the application. Be sure to test your IME with a wide range of applications, including browsers and rich text editors, as some may have peculiarities you need to deal with. Remember your IME may not be the only source of changes on the text, and try to be as conservative as possible in the data you send and as liberal as possible in the data you receive.

If you are implementing your own editor, you will probably need to provide your own subclass of BaseInputConnection to answer to the commands from IMEs. Please be sure to test your editor with as many IMEs as you can as their behavior can vary a lot. Also be sure to test with various languages, including CJK languages and right-to-left languages like Arabic, as these may have different input requirements. When in doubt about the behavior you should adopt for a particular call, please mimic the default TextView implementation in the latest Android version, and if you decide to drift from it, please consider carefully that inconsistencies in text edition behavior is almost universally felt as a bad thing by users.

Cursors, selections and compositions

In Android, the cursor and the selection are one and the same thing. A "cursor" is just the special case of a zero-sized selection. As such, this documentation uses them interchangeably. Any method acting "before the cursor" would act before the start of the selection if there is one, and any method acting "after the cursor" would act after the end of the selection.

An editor needs to be able to keep track of a currently "composing" region, like the standard edition widgets do. The composition is marked in a specific style: see SPAN_COMPOSING. IMEs use this to help the user keep track of what part of the text they are currently focusing on, and interact with the editor using setComposingText(CharSequence, int), setComposingRegion(int, int) and finishComposingText(). The composing region and the selection are completely independent of each other, and the IME may use them however they see fit.

Summary

Constants
int GET_EXTRACTED_TEXT_MONITOR Flag for use with getExtractedText(ExtractedTextRequest, int) to indicate you would like to receive updates when the extracted text changes.
int GET_TEXT_WITH_STYLES Flag for use with getTextAfterCursor(int, int) and getTextBeforeCursor(int, int) to have style information returned along with the text.
Public Methods
abstract boolean beginBatchEdit()
Tell the editor that you are starting a batch of editor operations.
abstract boolean clearMetaKeyStates(int states)
Clear the given meta key pressed states in the given input connection.
abstract 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[]).
abstract boolean commitCorrection(CorrectionInfo correctionInfo)
Commit a correction automatically performed on the raw user's input.
abstract boolean commitText(CharSequence text, int newCursorPosition)
Commit text to the text box and set the new cursor position.
abstract 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.
abstract boolean endBatchEdit()
Tell the editor that you are done with a batch edit previously initiated with beginBatchEdit().
abstract boolean finishComposingText()
Have the text editor finish whatever composing text is currently active.
abstract int getCursorCapsMode(int reqModes)
Retrieve the current capitalization mode in effect at the current cursor position in the text.
abstract ExtractedText getExtractedText(ExtractedTextRequest request, int flags)
Retrieve the current text in the input connection's editor, and monitor for any changes to it.
abstract CharSequence getSelectedText(int flags)
Gets the selected text, if any.
abstract CharSequence getTextAfterCursor(int n, int flags)
Get n characters of text after the current cursor position.
abstract CharSequence getTextBeforeCursor(int n, int flags)
Get n characters of text before the current cursor position.
abstract boolean performContextMenuAction(int id)
Perform a context menu action on the field.
abstract boolean performEditorAction(int editorAction)
Have the editor perform an action it has said it can do.
abstract boolean performPrivateCommand(String action, Bundle data)
API to send private commands from an input method to its connected editor.
abstract boolean reportFullscreenMode(boolean enabled)
Called by the IME to tell the client when it switches between fullscreen and normal modes.
abstract boolean sendKeyEvent(KeyEvent event)
Send a key event to the process that is currently attached through this input connection.
abstract boolean setComposingRegion(int start, int end)
Mark a certain region of text as composing text.
abstract boolean setComposingText(CharSequence text, int newCursorPosition)
Replace the currently composing text with the given text, and set the new cursor position.
abstract boolean setSelection(int start, int end)
Set the selection of the text editor.

Constants

public static final int GET_EXTRACTED_TEXT_MONITOR

Added in API level 3

Flag for use with getExtractedText(ExtractedTextRequest, int) to indicate you would like to receive updates when the extracted text changes.

Constant Value: 1 (0x00000001)

public static final int GET_TEXT_WITH_STYLES

Added in API level 3

Flag for use with getTextAfterCursor(int, int) and getTextBeforeCursor(int, int) to have style information returned along with the text. If not set, getTextAfterCursor(int, int) sends only the raw text, without style or other spans. If set, it may return a complex CharSequence of both text and style spans. Editor authors: you should strive to send text with styles if possible, but it is not required.

Constant Value: 1 (0x00000001)

Public Methods

public abstract boolean beginBatchEdit ()

Added in API level 3

Tell the editor that you are starting a batch of editor operations. The editor will try to avoid sending you updates about its state until endBatchEdit() is called. Batch edits nest.

IME authors: use this to avoid getting calls to 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 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.

Returns
  • 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.

public abstract boolean clearMetaKeyStates (int states)

Added in API level 3

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

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.

Parameters
states The states to be cleared, may be one or more bits as per KeyEvent.getMetaState().
Returns
  • true on success, false if the input connection is no longer valid.

public abstract boolean commitCompletion (CompletionInfo text)

Added in API level 3

Commit a completion the user has selected from the possible ones previously reported to 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 commitText(CharSequence, int).

IME authors: please take care to send the same object that you received through onDisplayCompletions(CompletionInfo[]).

Editor authors: if you never call displayCompletions(CompletionInfo[]) or 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 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 updateSelection(View, int, int, int, int), but be careful to wait until the batch edit is over if one is in progress.

Parameters
text The committed completion.
Returns
  • true on success, false if the input connection is no longer valid.

public abstract boolean commitCorrection (CorrectionInfo correctionInfo)

Added in API level 11

Commit a correction automatically performed on the raw user's input. A typical example would be to correct typos using a dictionary.

Calling this method will cause the editor to call 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 updateSelection(View, int, int, int, int), but be careful to wait until the batch edit is over if one is in progress.

Parameters
correctionInfo Detailed information about the correction.
Returns
  • true on success, false if the input connection is no longer valid.

public abstract boolean commitText (CharSequence text, int newCursorPosition)

Added in API level 3

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

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 finishComposingText().

Calling this method will cause the editor to call 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 updateSelection(View, int, int, int, int), but be careful to wait until the batch edit is over if one is in progress.

Parameters
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.
Returns
  • true on success, false if the input connection is no longer valid.

public abstract boolean deleteSurroundingText (int beforeLength, int afterLength)

Added in API level 3

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.

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

Parameters
beforeLength The number of characters to be deleted before the current cursor position.
afterLength The number of characters to be deleted after the current cursor position.
Returns
  • true on success, false if the input connection is no longer valid.

public abstract boolean endBatchEdit ()

Added in API level 3

Tell the editor that you are done with a batch edit previously initiated with beginBatchEdit(). This ends the latest batch only.

IME authors: make sure you call this exactly once for each call to beginBatchEdit().

Editor authors: please be careful about batch edit nesting. Updates still to be held back until the end of the last batch edit.

Returns
  • true if there is still a batch edit in progress after closing the latest one (in other words, if the nesting count is > 0), false otherwise or if the input connection is no longer valid.

public abstract boolean finishComposingText ()

Added in API level 3

Have the text editor finish whatever composing text is currently active. This simply leaves the text as-is, removing any special composing styling or other state that was around it. The cursor position remains unchanged.

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.

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

public abstract int getCursorCapsMode (int reqModes)

Added in API level 3

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 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
  • the caps mode flags that are in effect at the current cursor position. See TYPE_TEXT_FLAG_CAPS_* in InputType.

public abstract ExtractedText getExtractedText (ExtractedTextRequest request, int flags)

Added in API level 3

Retrieve the current text in the input connection's editor, and monitor for any changes to it. This function returns with the current text, and optionally the input connection can send updates to the input method when its text changes.

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 GET_EXTRACTED_TEXT_MONITOR flag is set, you should be calling updateExtractedText(View, int, ExtractedText) whenever you call updateSelection(View, int, int, int, int).

Parameters
request Description of how the text should be returned. ExtractedTextRequest
flags Additional options to control the client, either 0 or GET_EXTRACTED_TEXT_MONITOR.
Returns
  • 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.

public abstract CharSequence getSelectedText (int flags)

Added in API level 9

Gets the selected text, if any.

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

Parameters
flags Supplies additional options controlling how the text is returned. May be either 0 or GET_TEXT_WITH_STYLES.
Returns
  • the text that is currently selected, if any, or null if no text is selected.

public abstract CharSequence getTextAfterCursor (int n, int flags)

Added in API level 3

Get n characters of text after the current cursor position.

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

Parameters
n The expected length of the text.
flags Supplies additional options controlling how the text is returned. May be either 0 or GET_TEXT_WITH_STYLES.
Returns
  • the text after the cursor position; the length of the returned text might be less than n.

public abstract CharSequence getTextBeforeCursor (int n, int flags)

Added in API level 3

Get n characters of text before the current cursor position.

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

Parameters
n The expected length of the text.
flags Supplies additional options controlling how the text is returned. May be either 0 or GET_TEXT_WITH_STYLES.
Returns
  • the text before the cursor position; the length of the returned text might be less than n.

public abstract boolean performContextMenuAction (int id)

Added in API level 3

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

public abstract boolean performEditorAction (int editorAction)

Added in API level 3

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

This is typically used by IMEs when the user presses the key associated with the action.

Parameters
editorAction This must be one of the action constants for EditorInfo.editorType, such as EditorInfo.EDITOR_ACTION_GO.
Returns
  • true on success, false if the input connection is no longer valid.

public abstract boolean performPrivateCommand (String action, Bundle data)

Added in API level 3

API to send private commands from an input method to its connected editor. This can be used to provide domain-specific features that are only known between certain input methods and their clients. Note that because the InputConnection protocol is asynchronous, you have no way to get a result back or know if the client understood the command; you can use the information in EditorInfo to determine if a client supports a particular command.

Parameters
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.
Returns
  • true if the command was sent (whether or not the associated editor understood it), false if the input connection is no longer valid.

public abstract boolean reportFullscreenMode (boolean enabled)

Added in API level 3

Called by the IME to tell the client when it switches between fullscreen and normal modes. This will normally be called for you by the standard implementation of InputMethodService.

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

public abstract boolean sendKeyEvent (KeyEvent event)

Added in API level 3

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

Parameters
event The key event.
Returns
  • true on success, false if the input connection is no longer valid.

public abstract boolean setComposingRegion (int start, int end)

Added in API level 9

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 updateSelection(View, int, int, int, int) and IMEs should not receive 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 the position in the text at which the composing region begins
end the position in the text at which the composing region ends
Returns
  • true on success, false if the input connection is no longer valid.

public abstract boolean setComposingText (CharSequence text, int newCursorPosition)

Added in API level 3

Replace the currently composing text with the given text, and set the new cursor position. Any composing text set previously will be removed automatically.

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

Parameters
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.
Returns
  • true on success, false if the input connection is no longer valid.

public abstract boolean setSelection (int start, int end)

Added in API level 3

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

Parameters
start the character index where the selection should start.
end the character index where the selection should end.
Returns
  • true on success, false if the input connection is no longer valid.