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

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().
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 composing text.
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)
Set composing text around the current cursor position 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, you will receive only the raw text. If set, you may receive a complex CharSequence of both text and style spans.

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.

public abstract boolean clearMetaKeyStates (int states)

Added in API level 3

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

Parameters
states The states to be cleared, may be one or more bits as per KeyEvent.getMetaState().
Returns
  • 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(). This will result in the same behavior as if the user had selected the completion from the actual UI.

Parameters
text The committed completion.
Returns
  • 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.

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. Any composing text set previously will be removed automatically.

Parameters
text The committed text.
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
  • 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 composing text. Before and after refer to the order of the characters in the string, not to their visual representation.

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

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.

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, a 0 is returned.

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
  • Returns the caps mode flags that are in effect.

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, a null is returned.

Parameters
request Description of how the text should be returned.
flags Additional options to control the client, either 0 or GET_EXTRACTED_TEXT_MONITOR.
Returns
  • Returns an ExtractedText object describing the state of the text view and containing the extracted text itself.

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, a null is returned.

Parameters
flags Supplies additional options controlling how the text is returned. May be either 0 or GET_TEXT_WITH_STYLES.
Returns
  • 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, a null is returned.

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
  • 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 client is taking too long to respond with the text (it is given a couple seconds to return). In either case, a null is returned.

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

Parameters
editorAction This must be one of the action constants for EditorInfo.editorType, such as EditorInfo.EDITOR_ACTION_GO.
Returns
  • 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
  • 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.

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; 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
  • 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. Any composing text set previously will be removed automatically. The default style for composing text is used.

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

Set composing text around the current cursor position with the given text, and set the new cursor position. Any composing text set previously will be removed automatically.

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 {#link android.text.Spanned} for how to attach style object to the text. {#link android.text.SpannableString} and {#link android.text.SpannableStringBuilder} are two implementations of the interface {#link android.text.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
  • 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.

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