https://source.android.com/ 
/*
 * Copyright (C) 2007 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.view.inputmethod;

import android.annotation.NonNull;
import android.annotation.Nullable;
import android.inputmethodservice.InputMethodService;
import android.os.Bundle;
import android.os.Handler;
import android.view.KeyCharacterMap;
import android.view.KeyEvent;


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



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


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


/**
 * The InputConnection interface is the communication channel from an
 * {@link 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.
 *
 * <p>Starting from API Level {@link 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.</p>
 * <ul>
 *     <li>{@link #getSelectedText(int)}, which was introduced in
 *     {@link android.os.Build.VERSION_CODES#GINGERBREAD}.</li>
 *     <li>{@link #setComposingRegion(int, int)}, which was introduced
 *     in {@link android.os.Build.VERSION_CODES#GINGERBREAD}.</li>
 *     <li>{@link #commitCorrection(CorrectionInfo)}, which was introduced
 *     in {@link android.os.Build.VERSION_CODES#HONEYCOMB}.</li>
 *     <li>{@link #requestCursorUpdates(int)}, which was introduced in
 *     {@link android.os.Build.VERSION_CODES#LOLLIPOP}.</li>
 *     <li>{@link #deleteSurroundingTextInCodePoints(int, int)}, which
 *     was introduced in {@link android.os.Build.VERSION_CODES#N}.</li>
 *     <li>{@link #getHandler()}, which was introduced in
 *     {@link android.os.Build.VERSION_CODES#N}.</li>
 *     <li>{@link #closeConnection()}, which was introduced in
 *     {@link android.os.Build.VERSION_CODES#N}.</li>
 *     <li>{@link #commitContent(InputContentInfo, int, Bundle)}, which was
 *     introduced in {@link android.os.Build.VERSION_CODES#N_MR1}.</li>
 * </ul>
 *
 * <h3>Implementing an IME or an editor</h3>
 * <p>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
 * {@link android.inputmethodservice.InputMethodService}.
 * For more information about how to create an IME, see the
 * <a href="{@docRoot}guide/topics/text/creating-input-method.html">
 * Creating an input method</a> guide.
 *
 * The editor is the component that receives text and displays it.
 * Typically, this is an {@link 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
 * {@link android.view.inputmethod.InputMethodManager}. An editor
 * should start by implementing
 * {@link android.view.View#onCreateInputConnection(EditorInfo)}
 * to return its own input connection.</p>
 *
 * <p>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.</p>
 *
 * <p>If you are implementing your own editor, you will probably need
 * to provide your own subclass of {@link 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.</p>
 *
 * <h3>Cursors, selections and compositions</h3>
 * <p>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.</p>
 *
 * <p>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
 * {@link 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
 * {@link InputConnection#setComposingText(CharSequence, int)},
 * {@link InputConnection#setComposingRegion(int, int)} and
 * {@link InputConnection#finishComposingText()}.
 * The composing region and the selection are completely independent
 * of each other, and the IME may use them however they see fit.</p>
 */
public interface InputConnection {
    
Flag for use with getTextAfterCursor and getTextBeforeCursor to have style information returned along with the text. If not set, getTextAfterCursor 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.

/**
     * Flag for use with {@link #getTextAfterCursor} and
     * {@link #getTextBeforeCursor} to have style information returned
     * along with the text. If not set, {@link #getTextAfterCursor}
     * sends only the raw text, without style or other spans. If set,
     * it may return a complex CharSequence of both text and style
     * spans. <strong>Editor authors</strong>: you should strive to
     * send text with styles if possible, but it is not required.
     */
    int GET_TEXT_WITH_STYLES = 0x0001;

    
Flag for use with getExtractedText to indicate you would like to receive updates when the extracted text changes. 
/**
     * Flag for use with {@link #getExtractedText} to indicate you
     * would like to receive updates when the extracted text changes.
     */
    int GET_EXTRACTED_TEXT_MONITOR = 0x0001;

    
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.


Params:
  • 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.
/**
     * Get <var>n</var> characters of text before the current cursor
     * position.
     *
     * <p>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.</p>
     *
     * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the
     * editor should return a {@link android.text.SpannableString}
     * with all the spans set on the text.</p>
     *
     * <p><strong>IME authors:</strong> 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.</p>
     *
     * <p><strong>Editor authors:</strong> 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.</p>
     *
     * @param n The expected length of the text.
     * @param flags Supplies additional options controlling how the text is
     * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
     * @return the text before the cursor position; the length of the
     * returned text might be less than <var>n</var>.
     */
    CharSequence getTextBeforeCursor(int n, int flags);

    
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.


Params:
  • 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.
/**
     * Get <var>n</var> characters of text after the current cursor
     * position.
     *
     * <p>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.
     *
     * <p>This method does not affect the text in the editor in any
     * way, nor does it affect the selection or composing spans.</p>
     *
     * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the
     * editor should return a {@link android.text.SpannableString}
     * with all the spans set on the text.</p>
     *
     * <p><strong>IME authors:</strong> please consider this will
     * trigger an IPC round-trip that will take some time. Assume this
     * method consumes a lot of time.</p>
     *
     * <p><strong>Editor authors:</strong> 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.</p>
     *
     * @param n The expected length of the text.
     * @param flags Supplies additional options controlling how the text is
     * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
     *
     * @return the text after the cursor position; the length of the
     * returned text might be less than <var>n</var>.
     */
    CharSequence getTextAfterCursor(int n, int flags);

    
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.


Params:
  • 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. In VERSION_CODES.N and later, returns false when the target application does not implement this method.
/**
     * Gets the selected text, if any.
     *
     * <p>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.</p>
     *
     * <p>This method must not cause any changes in the editor's
     * state.</p>
     *
     * <p>If {@link #GET_TEXT_WITH_STYLES} is supplied as flags, the
     * editor should return a {@link android.text.SpannableString}
     * with all the spans set on the text.</p>
     *
     * <p><strong>IME authors:</strong> please consider this will
     * trigger an IPC round-trip that will take some time. Assume this
     * method consumes a lot of time.</p>
     *
     * <p><strong>Editor authors:</strong> 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.</p>
     *
     * @param flags Supplies additional options controlling how the text is
     * returned. May be either 0 or {@link #GET_TEXT_WITH_STYLES}.
     * @return the text that is currently selected, if any, or null if
     * no text is selected. In {@link android.os.Build.VERSION_CODES#N} and
     * later, returns false when the target application does not implement
     * this method.
     */
    CharSequence getSelectedText(int flags);

    
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.


Params:
Returns:the caps mode flags that are in effect at the current cursor position. See TYPE_TEXT_FLAG_CAPS_* in InputType.
/**
     * Retrieve the current capitalization mode in effect at the
     * current cursor position in the text. See
     * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}
     * for more information.
     *
     * <p>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.</p>
     *
     * <p>This method does not affect the text in the editor in any
     * way, nor does it affect the selection or composing spans.</p>
     *
     * <p><strong>Editor authors:</strong> 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.</p>
     *
     * @param reqModes The desired modes to retrieve, as defined by
     * {@link android.text.TextUtils#getCapsMode TextUtils.getCapsMode}. These
     * constants are defined so that you can simply pass the current
     * {@link EditorInfo#inputType TextBoxAttribute.contentType} value
     * directly in to here.
     * @return the caps mode flags that are in effect at the current
     * cursor position. See TYPE_TEXT_FLAG_CAPS_* in {@link android.text.InputType}.
     */
    int getCursorCapsMode(int reqModes);

    
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 InputMethodManager.updateExtractedText(View, int, ExtractedText) whenever you call InputMethodManager.updateSelection(View, int, int, int, int).


Params:
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.
/**
     * 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.
     *
     * <p>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.</p>
     *
     * <p>Editor authors: as a general rule, try to comply with the
     * fields in <code>request</code> 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
     * {@link #GET_EXTRACTED_TEXT_MONITOR} flag is set, you should be
     * calling
     * {@link InputMethodManager#updateExtractedText(View, int, ExtractedText)}
     * whenever you call
     * {@link InputMethodManager#updateSelection(View, int, int, int, int)}.</p>
     *
     * @param request Description of how the text should be returned.
     * {@link android.view.inputmethod.ExtractedTextRequest}
     * @param flags Additional options to control the client, either 0 or
     * {@link #GET_EXTRACTED_TEXT_MONITOR}.

     * @return an {@link android.view.inputmethod.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.
     */
    ExtractedText getExtractedText(ExtractedTextRequest request, int flags);

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


Params:
  • beforeLength – 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 – 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:true on success, false if the input connection is no longer valid.
/**
     * 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. 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.
     *
     * <p>The lengths are supplied in Java chars, not in code points
     * or in glyphs.</p>
     *
     * <p>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.</p>
     *
     * <p><strong>IME authors:</strong> 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
     * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int,
     * int, int)} on your service after the batch input is over.</p>
     *
     * <p><strong>Editor authors:</strong> 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
     * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
     * but be careful to wait until the batch edit is over if one is
     * in progress.</p>
     *
     * @param beforeLength 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.
     * @param afterLength 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.
     * @return true on success, false if the input connection is no longer valid.
     */
    boolean deleteSurroundingText(int beforeLength, int afterLength);

    
A variant of deleteSurroundingText(int, int). Major differences are: 
    
    
  • The lengths are supplied in code points, not in Java chars or in glyphs.
    
  • This method does nothing if there are one or more invalid surrogate pairs in the
    requested range.
    • 



Editor authors: In addition to the requirement in deleteSurroundingText(int, int), make sure to do nothing when one ore more invalid surrogate pairs are found in the requested range.


Params:
  • beforeLength – 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 – 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.
See Also:
Returns:true on success, false if the input connection is no longer valid. Returns false when the target application does not implement this method.
/**
     * A variant of {@link #deleteSurroundingText(int, int)}. Major differences are:
     *
     * <ul>
     *     <li>The lengths are supplied in code points, not in Java chars or in glyphs.</>
     *     <li>This method does nothing if there are one or more invalid surrogate pairs in the
     *     requested range.</li>
     * </ul>
     *
     * <p><strong>Editor authors:</strong> In addition to the requirement in
     * {@link #deleteSurroundingText(int, int)}, make sure to do nothing when one ore more invalid
     * surrogate pairs are found in the requested range.</p>
     *
     * @see #deleteSurroundingText(int, int)
     *
     * @param beforeLength 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.
     * @param afterLength 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.
     * @return true on success, false if the input connection is no longer valid.  Returns
     * {@code false} when the target application does not implement this method.
     */
    boolean deleteSurroundingTextInCodePoints(int beforeLength, int afterLength);

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


Params:
  • 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.
/**
     * Replace the currently composing text with the given text, and
     * set the new cursor position. Any composing text set previously
     * will be removed automatically.
     *
     * <p>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
     * <code>newCursorPosition</code>.</p>
     *
     * <p>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
     * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int,
     * int, int)} on the current IME after the batch input is over.</p>
     *
     * <p><strong>Editor authors:</strong> 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
     * {@link InputMethodManager#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.</p>
     *
     * @param 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}.
     * @param 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.
     * @return true on success, false if the input connection is no longer
     * valid.
     */
    boolean setComposingText(CharSequence text, int newCursorPosition);

    
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.


Params:
  • 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. In VERSION_CODES.N and later, false is returned when the target application does not implement this method.
/**
     * 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 {@link #finishComposingText()}
     * has been called. The default style for composing text is used.
     *
     * <p>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 {@link #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.</p>
     *
     * <p>Since this does not change the contents of the text, editors should not call
     * {@link InputMethodManager#updateSelection(View, int, int, int, int)} and
     * IMEs should not receive
     * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int,
     * int, int)}.</p>
     *
     * <p>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.</p>
     *
     * @param start the position in the text at which the composing region begins
     * @param end the position in the text at which the composing region ends
     * @return true on success, false if the input connection is no longer
     * valid. In {@link android.os.Build.VERSION_CODES#N} and later, false is returned when the
     * target application does not implement this method.
     */
    boolean setComposingRegion(int start, int end);

    
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.
/**
     * 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.
     *
     * <p><strong>IME authors:</strong> be aware that this call may be
     * expensive with some editors.</p>
     *
     * <p><strong>Editor authors:</strong> 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.</p>
     *
     * @return true on success, false if the input connection
     * is no longer valid.
     */
    boolean finishComposingText();

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


Params:
  • 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.
/**
     * Commit text to the text box and set the new cursor position.
     *
     * <p>This method removes the contents of the currently composing
     * text and replaces it with the passed CharSequence, and then
     * moves the cursor according to {@code 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
     * {@link #setComposingText(CharSequence, int) setComposingText(text, newCursorPosition)}
     * then {@link #finishComposingText()}.</p>
     *
     * <p>Calling this method will cause the editor to call
     * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int,
     * int, int)} on the current IME after the batch input is over.
     * <strong>Editor authors</strong>, for this to happen you need to
     * make the changes known to the input method by calling
     * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
     * but be careful to wait until the batch edit is over if one is
     * in progress.</p>
     *
     * @param text The text to commit. This may include styles.
     * @param 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.
     * @return true on success, false if the input connection is no longer
     * valid.
     */
    boolean commitText(CharSequence text, int newCursorPosition);

    
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 InputMethodService.onDisplayCompletions(CompletionInfo[]). 


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


Params:
  • text – The committed completion.
Returns:true on success, false if the input connection is no longer
valid.
/**
     * Commit a completion the user has selected from the possible ones
     * previously reported to {@link InputMethodSession#displayCompletions
     * InputMethodSession#displayCompletions(CompletionInfo[])} or
     * {@link InputMethodManager#displayCompletions
     * 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 {@link #commitText(CharSequence, int)}.
     *
     * <p><strong>IME authors:</strong> please take care to send the
     * same object that you received through
     * {@link android.inputmethodservice.InputMethodService#onDisplayCompletions(CompletionInfo[])}.
     * </p>
     *
     * <p><strong>Editor authors:</strong> if you never call
     * {@link InputMethodSession#displayCompletions(CompletionInfo[])} or
     * {@link InputMethodManager#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.</p>
     *
     * <p>Calling this method (with a valid {@link CompletionInfo} object)
     * will cause the editor to call
     * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int,
     * int, int)} on the current IME after the batch input is over.
     * <strong>Editor authors</strong>, for this to happen you need to
     * make the changes known to the input method by calling
     * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
     * but be careful to wait until the batch edit is over if one is
     * in progress.</p>
     *
     * @param text The committed completion.
     * @return true on success, false if the input connection is no longer
     * valid.
     */
    boolean commitCompletion(CompletionInfo text);

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


Params:
  • correctionInfo – Detailed information about the correction.
Returns:true on success, false if the input connection is no longer valid. In VERSION_CODES.N and later, returns false when the target application does not implement this method.
/**
     * Commit a correction automatically performed on the raw user's input. A
     * typical example would be to correct typos using a dictionary.
     *
     * <p>Calling this method will cause the editor to call
     * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int,
     * int, int)} on the current IME after the batch input is over.
     * <strong>Editor authors</strong>, for this to happen you need to
     * make the changes known to the input method by calling
     * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
     * but be careful to wait until the batch edit is over if one is
     * in progress.</p>
     *
     * @param correctionInfo Detailed information about the correction.
     * @return true on success, false if the input connection is no longer valid.
     * In {@link android.os.Build.VERSION_CODES#N} and later, returns false
     * when the target application does not implement this method.
     */
    boolean commitCorrection(CorrectionInfo correctionInfo);

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


Params:
  • 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.
/**
     * Set the selection of the text editor. To set the cursor
     * position, start and end should have the same value.
     *
     * <p>Since this moves the cursor, calling this method will cause
     * the editor to call
     * {@link android.inputmethodservice.InputMethodService#onUpdateSelection(int, int, int, int,
     * int, int)} on the current IME after the batch input is over.
     * <strong>Editor authors</strong>, for this to happen you need to
     * make the changes known to the input method by calling
     * {@link InputMethodManager#updateSelection(View, int, int, int, int)},
     * but be careful to wait until the batch edit is over if one is
     * in progress.</p>
     *
     * <p>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.</p>
     *
     * @param start the character index where the selection should start.
     * @param end the character index where the selection should end.
     * @return true on success, false if the input connection is no longer
     * valid.
     */
    boolean setSelection(int start, int end);

    
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.


Params:
Returns:true on success, false if the input connection is no longer
valid.
/**
     * Have the editor perform an action it has said it can do.
     *
     * <p>This is typically used by IMEs when the user presses the key
     * associated with the action.</p>
     *
     * @param editorAction This must be one of the action constants for
     * {@link EditorInfo#imeOptions EditorInfo.editorType}, such as
     * {@link EditorInfo#IME_ACTION_GO EditorInfo.EDITOR_ACTION_GO}.
     * @return true on success, false if the input connection is no longer
     * valid.
     */
    boolean performEditorAction(int editorAction);

    
Perform a context menu action on the field. The given id may be one of: selectAll.selectAll, startSelectingText.startSelectingText, stopSelectingText.stopSelectingText, cut.cut, copy.copy, paste.paste, copyUrl.copyUrl, or switchInputMethod.switchInputMethod 
/**
     * Perform a context menu action on the field. The given id may be one of:
     * {@link android.R.id#selectAll},
     * {@link android.R.id#startSelectingText}, {@link android.R.id#stopSelectingText},
     * {@link android.R.id#cut}, {@link android.R.id#copy},
     * {@link android.R.id#paste}, {@link android.R.id#copyUrl},
     * or {@link android.R.id#switchInputMethod}
     */
    boolean performContextMenuAction(int id);

    
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 InputMethodService.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.
/**
     * 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 {@link #endBatchEdit} is called. Batch
     * edits nest.
     *
     * <p><strong>IME authors:</strong> use this to avoid getting
     * calls to
     * {@link android.inputmethodservice.InputMethodService#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 {@link #endBatchEdit} for each call to this, or
     * you may block updates in the editor.</p>
     *
     * <p><strong>Editor authors:</strong> 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.</p>
     *
     * @return 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.
     */
    boolean beginBatchEdit();

    
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.
/**
     * Tell the editor that you are done with a batch edit previously
     * initiated with {@link #beginBatchEdit}. This ends the latest
     * batch only.
     *
     * <p><strong>IME authors:</strong> make sure you call this
     * exactly once for each call to {@link #beginBatchEdit}.</p>
     *
     * <p><strong>Editor authors:</strong> please be careful about
     * batch edit nesting. Updates still to be held back until the end
     * of the last batch edit.</p>
     *
     * @return 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.
     */
    boolean endBatchEdit();

    
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 InputType.TYPE_NULL type text fields. Use the commitText family of methods to send text to the application instead.


Params:
  • event – The key event.
See Also:
Returns:true on success, false if the input connection is no longer
valid.
/**
     * 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.
     *
     * <p>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.</p>
     *
     * <p>You will usually want to set the flag
     * {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD}
     * on all key event objects you give to this API; the flag will
     * not be set for you.</p>
     *
     * <p>Note that it's discouraged to send such key events in normal
     * operation; this is mainly for use with
     * {@link android.text.InputType#TYPE_NULL} type text fields. Use
     * the {@link #commitText} family of methods to send text to the
     * application instead.</p>
     *
     * @param event The key event.
     * @return true on success, false if the input connection is no longer
     * valid.
     *
     * @see KeyEvent
     * @see KeyCharacterMap#NUMERIC
     * @see KeyCharacterMap#PREDICTIVE
     * @see KeyCharacterMap#ALPHA
     */
    boolean sendKeyEvent(KeyEvent event);

    
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.


Params:
Returns:true on success, false if the input connection is no longer
valid.
/**
     * Clear the given meta key pressed states in the given input
     * connection.
     *
     * <p>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.</p>
     *
     * @param states The states to be cleared, may be one or more bits as
     * per {@link KeyEvent#getMetaState() KeyEvent.getMetaState()}.
     * @return true on success, false if the input connection is no longer
     * valid.
     */
    boolean clearMetaKeyStates(int states);

    
Called back when the connected IME switches between fullscreen and normal modes.

Note: On VERSION_CODES.O and later devices, input methods are no longer allowed to directly call this method at any time. To signal this event in the target application, input methods should always call InputMethodService.updateFullscreenMode() instead. This approach should work on API VERSION_CODES.N_MR1 and prior devices.


See Also:
Returns:For editor authors, the return value will always be ignored. For IME authors, this always returns true on VERSION_CODES.N_MR1 and prior devices and false on VERSION_CODES.O and later devices.
/**
     * Called back when the connected IME switches between fullscreen and normal modes.
     *
     * <p>Note: On {@link android.os.Build.VERSION_CODES#O} and later devices, input methods are no
     * longer allowed to directly call this method at any time. To signal this event in the target
     * application, input methods should always call
     * {@link InputMethodService#updateFullscreenMode()} instead. This approach should work on API
     * {@link android.os.Build.VERSION_CODES#N_MR1} and prior devices.</p>
     *
     * @return For editor authors, the return value will always be ignored. For IME authors, this
     *         always returns {@code true} on {@link android.os.Build.VERSION_CODES#N_MR1} and prior
     *         devices and {@code false} on {@link android.os.Build.VERSION_CODES#O} and later
     *         devices.
     * @see InputMethodManager#isFullscreenMode()
     */
    boolean reportFullscreenMode(boolean enabled);

    
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. 
Params:
  • 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.
/**
     * 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 {@link EditorInfo} to determine if a client
     * supports a particular command.
     *
     * @param action Name of the command to be performed. This <em>must</em>
     * be a scoped name, i.e. prefixed with a package name you own, so that
     * different developers will not create conflicting commands.
     * @param data Any data to include with the command.
     * @return true if the command was sent (whether or not the
     * associated editor understood it), false if the input connection is no longer
     * valid.
     */
    boolean performPrivateCommand(String action, Bundle data);

    
The editor is requested to call InputMethodManager.updateCursorAnchorInfo(View, CursorAnchorInfo) at once, as soon as possible, regardless of cursor/anchor position changes. This flag can be used together with CURSOR_UPDATE_MONITOR. 
/**
     * The editor is requested to call
     * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)} at
     * once, as soon as possible, regardless of cursor/anchor position changes. This flag can be
     * used together with {@link #CURSOR_UPDATE_MONITOR}.
     */
    int CURSOR_UPDATE_IMMEDIATE = 1 << 0;

    
The editor is requested to call InputMethodManager.updateCursorAnchorInfo(View, CursorAnchorInfo) whenever cursor/anchor position is changed. To disable monitoring, call requestCursorUpdates(int) again with this flag off. 
 This flag can be used together with CURSOR_UPDATE_IMMEDIATE. 


/**
     * The editor is requested to call
     * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)}
     * whenever cursor/anchor position is changed. To disable monitoring, call
     * {@link InputConnection#requestCursorUpdates(int)} again with this flag off.
     * <p>
     * This flag can be used together with {@link #CURSOR_UPDATE_IMMEDIATE}.
     * </p>
     */
    int CURSOR_UPDATE_MONITOR = 1 << 1;

    
Called by the input method to ask the editor for calling back InputMethodManager.updateCursorAnchorInfo(View, CursorAnchorInfo) to notify cursor/anchor locations. 
Params:
Returns:true if the request is scheduled. false to indicate that when the application will not call InputMethodManager.updateCursorAnchorInfo(View, CursorAnchorInfo). In VERSION_CODES.N and later, returns false also when the target application does not implement this method.
/**
     * Called by the input method to ask the editor for calling back
     * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)} to
     * notify cursor/anchor locations.
     *
     * @param cursorUpdateMode {@link #CURSOR_UPDATE_IMMEDIATE} and/or
     * {@link #CURSOR_UPDATE_MONITOR}. Pass {@code 0} to disable the effect of
     * {@link #CURSOR_UPDATE_MONITOR}.
     * @return {@code true} if the request is scheduled. {@code false} to indicate that when the
     * application will not call
     * {@link InputMethodManager#updateCursorAnchorInfo(android.view.View, CursorAnchorInfo)}.
     * In {@link android.os.Build.VERSION_CODES#N} and later, returns {@code false} also when the
     * target application does not implement this method.
     */
    boolean requestCursorUpdates(int cursorUpdateMode);

    
Called by the InputMethodManager to enable application developers to specify a dedicated Handler on which incoming IPC method calls from input methods will be dispatched. 
Note: This does nothing when called from input methods.


Returns:null to use the default Handler.
/**
     * Called by the {@link InputMethodManager} to enable application developers to specify a
     * dedicated {@link Handler} on which incoming IPC method calls from input methods will be
     * dispatched.
     *
     * <p>Note: This does nothing when called from input methods.</p>
     *
     * @return {@code null} to use the default {@link Handler}.
     */
    Handler getHandler();

    
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.

Editor authors: You can clear all the nested batch edit right now and you no longer need to handle subsequent callbacks on this connection, including beginBatchEdit()}. Note that although the system tries to call this method whenever possible, there may be a chance that this method is not called in some exceptional situations.


Note: This does nothing when called from input methods.


/**
     * 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.
     *
     * <p><strong>Editor authors</strong>: You can clear all the nested batch edit right now and
     * you no longer need to handle subsequent callbacks on this connection, including
     * {@link #beginBatchEdit()}}.  Note that although the system tries to call this method whenever
     * possible, there may be a chance that this method is not called in some exceptional
     * situations.</p>
     *
     * <p>Note: This does nothing when called from input methods.</p>
     */
    void closeConnection();

    
When this flag is used, the editor will be able to request read access to the content URI contained in the InputContentInfo object. 
Make sure that the content provider owning the Uri sets the 
grantUriPermissions attribute in its manifest or included the 
<grant-uri-permissions> tag. Otherwise InputContentInfo.requestPermission() can fail.


Although calling this API is allowed only for the IME that is currently selected, the client is able to request a temporary read-only access even after the current IME is switched to any other IME as long as the client keeps InputContentInfo object.


/**
     * When this flag is used, the editor will be able to request read access to the content URI
     * contained in the {@link InputContentInfo} object.
     *
     * <p>Make sure that the content provider owning the Uri sets the
     * {@link android.R.styleable#AndroidManifestProvider_grantUriPermissions
     * grantUriPermissions} attribute in its manifest or included the
     * {@link android.R.styleable#AndroidManifestGrantUriPermission
     * &lt;grant-uri-permissions&gt;} tag. Otherwise {@link InputContentInfo#requestPermission()}
     * can fail.</p>
     *
     * <p>Although calling this API is allowed only for the IME that is currently selected, the
     * client is able to request a temporary read-only access even after the current IME is switched
     * to any other IME as long as the client keeps {@link InputContentInfo} object.</p>
     **/
    int INPUT_CONTENT_GRANT_READ_URI_PERMISSION =
            android.content.Intent.FLAG_GRANT_READ_URI_PERMISSION;  // 0x00000001

    
Called by the input method to commit content such as a PNG image to the editor.

In order to avoid a variety of compatibility issues, this focuses on a simple use case,
where editors and IMEs are expected to work cooperatively as follows:


    
    
  • Editor must keep EditorInfo.contentMimeTypes equal to null if it does not support this method at all.
    • 
    
  • Editor can ignore this request when the MIME type specified in inputContentInfo does not match any of EditorInfo.contentMimeTypes. 
    • 
    
  • Editor can ignore the cursor position when inserting the provided content.
    • 
    
  • Editor can return true asynchronously, even before it starts loading the content.
    • 
    
  • Editor should provide a way to delete the content inserted by this method or to
    revert the effect caused by this method.
    • 
    
  • IME should not call this method when there is any composing text, in case calling
    this method causes a focus change.
    • 
    
  • IME should grant a permission for the editor to read the content. See EditorInfo.packageName about how to obtain the package name of the editor.
    • 



Params:
Returns:true if this request is accepted by the application, whether the request is already handled or still being handled in background, false otherwise.
/**
     * Called by the input method to commit content such as a PNG image to the editor.
     *
     * <p>In order to avoid a variety of compatibility issues, this focuses on a simple use case,
     * where editors and IMEs are expected to work cooperatively as follows:</p>
     * <ul>
     *     <li>Editor must keep {@link EditorInfo#contentMimeTypes} equal to {@code null} if it does
     *     not support this method at all.</li>
     *     <li>Editor can ignore this request when the MIME type specified in
     *     {@code inputContentInfo} does not match any of {@link EditorInfo#contentMimeTypes}.
     *     </li>
     *     <li>Editor can ignore the cursor position when inserting the provided content.</li>
     *     <li>Editor can return {@code true} asynchronously, even before it starts loading the
     *     content.</li>
     *     <li>Editor should provide a way to delete the content inserted by this method or to
     *     revert the effect caused by this method.</li>
     *     <li>IME should not call this method when there is any composing text, in case calling
     *     this method causes a focus change.</li>
     *     <li>IME should grant a permission for the editor to read the content. See
     *     {@link EditorInfo#packageName} about how to obtain the package name of the editor.</li>
     * </ul>
     *
     * @param inputContentInfo Content to be inserted.
     * @param flags {@link #INPUT_CONTENT_GRANT_READ_URI_PERMISSION} if the content provider
     * allows {@link android.R.styleable#AndroidManifestProvider_grantUriPermissions
     * grantUriPermissions} or {@code 0} if the application does not need to call
     * {@link InputContentInfo#requestPermission()}.
     * @param opts optional bundle data. This can be {@code null}.
     * @return {@code true} if this request is accepted by the application, whether the request
     * is already handled or still being handled in background, {@code false} otherwise.
     */
    boolean commitContent(@NonNull InputContentInfo inputContentInfo, int flags,
            @Nullable Bundle opts);
}