IInputConnection Interface
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
The InputConnection interface is the communication channel from an
InputMethod back to the application that is receiving its
input.
[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
- Attributes
- Implements
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
| Handle |
Gets the JNI value of the underlying Android object. (Inherited from IJavaObject) |
| Handler | |
| JniIdentityHashCode |
Returns the value of |
| JniManagedPeerState |
State of the managed peer. (Inherited from IJavaPeerable) |
| JniPeerMembers |
Member access and invocation support. (Inherited from IJavaPeerable) |
| PeerReference |
Returns a JniObjectReference of the wrapped Java object instance. (Inherited from IJavaPeerable) |
Methods
| BeginBatchEdit() |
Tell the editor that you are starting a batch of editor operations. |
| ClearMetaKeyStates(MetaKeyStates) |
Clear the given meta key pressed states in the given input connection. |
| CloseConnection() |
Called by the system up to only once to notify that the system is about to invalidate connection between the input method and the application. |
| CommitCompletion(CompletionInfo) |
Commit a completion the user has selected from the possible ones
previously reported to |
| CommitContent(InputContentInfo, InputContentFlags, Bundle) |
Called by the input method to commit content such as a PNG image to the editor. |
| CommitCorrection(CorrectionInfo) |
Commit a correction automatically performed on the raw user's input. |
| CommitText(ICharSequence, Int32, TextAttribute) |
The variant of |
| CommitText(ICharSequence, Int32) |
Commit text to the text box and set the new cursor position. |
| CommitText(String, Int32, TextAttribute) |
The variant of |
| DeleteSurroundingText(Int32, Int32) |
Delete <var>beforeLength</var> characters of text before the current cursor position, and delete <var>afterLength</var> characters of text after the current cursor position, excluding the selection. |
| DeleteSurroundingTextInCodePoints(Int32, Int32) |
A variant of |
| Disposed() |
Called when the instance has been disposed. (Inherited from IJavaPeerable) |
| DisposeUnlessReferenced() |
If there are no outstanding references to this instance, then
calls |
| EndBatchEdit() |
Tell the editor that you are done with a batch edit previously initiated with
|
| Finalized() |
Called when the instance has been finalized. (Inherited from IJavaPeerable) |
| FinishComposingText() |
Have the text editor finish whatever composing text is currently active. |
| GetCursorCapsMode(CapitalizationMode) |
Retrieve the current capitalization mode in effect at the current cursor position in the text. |
| GetExtractedText(ExtractedTextRequest, GetTextFlags) |
Retrieve the current text in the input connection's editor, and monitor for any changes to it. |
| GetSelectedTextFormatted(GetTextFlags) |
Gets the selected text, if any. |
| GetSurroundingText(Int32, Int32, Int32) |
Gets the surrounding text around the current cursor, with <var>beforeLength</var> characters of text before the cursor (start of the selection), <var>afterLength</var> characters of text after the cursor (end of the selection), and all of the selected text. |
| GetTextAfterCursorFormatted(Int32, GetTextFlags) |
Get <var>n</var> characters of text after the current cursor position. |
| GetTextBeforeCursorFormatted(Int32, GetTextFlags) |
Get <var>n</var> characters of text before the current cursor position. |
| PerformContextMenuAction(Int32) |
Perform a context menu action on the field. |
| PerformEditorAction(ImeAction) |
Have the editor perform an action it has said it can do. |
| PerformHandwritingGesture(HandwritingGesture, IExecutor, IIntConsumer) |
Perform a handwriting gesture on text. |
| PerformPrivateCommand(String, Bundle) |
API to send private commands from an input method to its connected editor. |
| PerformSpellCheck() |
Have the editor perform spell checking for the full content. |
| PreviewHandwritingGesture(PreviewableHandwritingGesture, CancellationSignal) |
Preview a handwriting gesture on text. |
| ReplaceText(Int32, Int32, ICharSequence, Int32, TextAttribute) |
Replace the specific range in the editor with suggested text. |
| ReplaceText(Int32, Int32, String, Int32, TextAttribute) |
Replace the specific range in the editor with suggested text. |
| ReportFullscreenMode(Boolean) |
Called back when the connected IME switches between fullscreen and normal modes. |
| RequestCursorUpdates(Int32, Int32) |
Called by the input method to ask the editor for calling back
|
| RequestCursorUpdates(Int32) |
Called by the input method to ask the editor for calling back
|
| RequestTextBoundsInfo(RectF, IExecutor, IConsumer) |
Called by input method to request the |
| SendKeyEvent(KeyEvent) |
Send a key event to the process that is currently attached through this input connection. |
| SetComposingRegion(Int32, Int32, TextAttribute) |
The variant of |
| SetComposingRegion(Int32, Int32) |
Mark a certain region of text as composing text. |
| SetComposingText(ICharSequence, Int32, TextAttribute) |
The variant of |
| SetComposingText(ICharSequence, Int32) |
Replace the currently composing text with the given text, and set the new cursor position. |
| SetComposingText(String, Int32, TextAttribute) |
The variant of |
| SetImeConsumesInput(Boolean) |
Called by the input method to indicate that it consumes all input for itself, or no longer does so. |
| SetJniIdentityHashCode(Int32) |
Set the value returned by |
| SetJniManagedPeerState(JniManagedPeerStates) | (Inherited from IJavaPeerable) |
| SetPeerReference(JniObjectReference) |
Set the value returned by |
| SetSelection(Int32, Int32) |
Set the selection of the text editor. |
| TakeSnapshot() |
Called by the system when it needs to take a snapshot of multiple text-related data in an atomic manner. |
| UnregisterFromRuntime() |
Unregister this instance so that the runtime will not return it from future Java.Interop.JniRuntime+JniValueManager.PeekValue invocations. (Inherited from IJavaPeerable) |