IInputConnection Interface

Definition

[Android.Runtime.Register("android/view/inputmethod/InputConnection", "", "Android.Views.InputMethods.IInputConnectionInvoker")]
public interface IInputConnection : Android.Runtime.IJavaObject, IDisposable, Java.Interop.IJavaPeerable

[<Android.Runtime.Register("android/view/inputmethod/InputConnection", "", "Android.Views.InputMethods.IInputConnectionInvoker")>]
type IInputConnection = interface
    interface IJavaObject
    interface IDisposable
    interface IJavaPeerable

Derived

Android.Views.InputMethods.BaseInputConnection

Android.Views.InputMethods.InputConnectionWrapper

Attributes

RegisterAttribute

Implements

IJavaObject IJavaPeerable IDisposable

Remarks

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.

Starting from API Level android.os.Build.VERSION_CODES#N, the system can deal with the situation where the application directly implements this class but one or more of the following methods are not implemented.

<ul> <li>#getSelectedText(int), which was introduced in android.os.Build.VERSION_CODES#GINGERBREAD.</li> <li>#setComposingRegion(int, int), which was introduced in android.os.Build.VERSION_CODES#GINGERBREAD.</li> <li>#commitCorrection(CorrectionInfo), which was introduced in android.os.Build.VERSION_CODES#HONEYCOMB.</li> <li>#requestCursorUpdates(int), which was introduced in android.os.Build.VERSION_CODES#LOLLIPOP.</li> <li>#deleteSurroundingTextInCodePoints(int, int), which was introduced in android.os.Build.VERSION_CODES#N.</li> <li>#getHandler(), which was introduced in android.os.Build.VERSION_CODES#N.</li> <li>#closeConnection(), which was introduced in android.os.Build.VERSION_CODES#N.</li> <li>#commitContent(InputContentInfo, int, Bundle), which was introduced in android.os.Build.VERSION_CODES#N_MR1.</li> </ul>

<h3>Implementing an IME or an editor</h3>

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 android.inputmethodservice.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 android.widget.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 android.view.inputmethod.InputMethodManager. An editor should start by implementing android.view.View#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 editor behavior is almost universally felt as a bad thing by users.

<h3>Cursors, selections and compositions</h3>

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 android.text.Spanned#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 InputConnection#setComposingText(CharSequence, int), InputConnection#setComposingRegion(int, int) and InputConnection#finishComposingText(). The composing region and the selection are completely independent of each other, and the IME may use them however they see fit.

Java documentation for android.view.inputmethod.InputConnection.

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Properties

Methods

Extension Methods

Applies to