EditorInfoCompat

Added in 1.1.0

public final class EditorInfoCompat

Helper for accessing features in EditorInfo in a backwards compatible fashion.

Summary

Constants
static final int
IME_FLAG_FORCE_ASCII = -2147483648

Flag of imeOptions: used to request an IME that is capable of inputting ASCII characters.
static final int

Flag of imeOptions: used to request that the IME does not update any personalized data such as typing history and personalized language model based on what the user typed on this text editing object.

Public constructors

This method is deprecated.

This type should not be instantiated as it contains only static methods.

Public methods
static @NonNull String[]

Gets MIME types that can be accepted by the target editor if the IME calls commitContent
static @Nullable CharSequence
getInitialSelectedText(@NonNull EditorInfo editorInfo, int flags)

Gets the selected text, if any.
static @Nullable CharSequence
getInitialTextAfterCursor(
    @NonNull EditorInfo editorInfo,
    int length,
    int flags
)

Get n characters of text after the current cursor position.
static @Nullable CharSequence
getInitialTextBeforeCursor(
    @NonNull EditorInfo editorInfo,
    int length,
    int flags
)

Get n characters of text before the current cursor position.
static boolean

Returns true when an editor has stylus handwriting enabled.
static void
setContentMimeTypes(
    @NonNull EditorInfo editorInfo,
    @Nullable String[] contentMimeTypes
)

Sets MIME types that can be accepted by the target editor if the IME calls commitContent.
static void
setInitialSurroundingSubText(
    @NonNull EditorInfo editorInfo,
    @NonNull CharSequence subText,
    int subTextStart
)

Editors may use this method to provide initial input text to IMEs.
static void
setInitialSurroundingText(
    @NonNull EditorInfo editorInfo,
    @NonNull CharSequence sourceText
)

Editors may use this method to provide initial input text to IMEs.
static void
setStylusHandwritingEnabled(
    @NonNull EditorInfo editorInfo,
    boolean enabled
)

Set true if the editor has stylus handwriting enabled.

Constants

IME_FLAG_FORCE_ASCII

Added in 1.1.0
public static final int IME_FLAG_FORCE_ASCII = -2147483648

Flag of imeOptions: used to request an IME that is capable of inputting ASCII characters.

The intention of this flag is to ensure that the user can type Roman alphabet characters in a android.widget.TextView. It is typically used for an account ID or password input.

In many cases, IMEs are already able to input ASCII even without being told so (such IMEs already respect this flag in a sense), but there are cases when this is not the default. For instance, users of languages using a different script like Arabic, Greek, Hebrew or Russian typically have a keyboard that can't input ASCII characters by default.

Applications need to be aware that the flag is not a guarantee, and some IMEs may not respect it. However, it is strongly recommended for IME authors to respect this flag especially when their IME could end up with a state where only languages using non-ASCII are enabled.

IME_FLAG_NO_PERSONALIZED_LEARNING

Added in 1.1.0
public static final int IME_FLAG_NO_PERSONALIZED_LEARNING = 16777216

Flag of imeOptions: used to request that the IME does not update any personalized data such as typing history and personalized language model based on what the user typed on this text editing object. Typical use cases are:

  • When the application is in a special mode, where user's activities are expected to be not recorded in the application's history. Some web browsers and chat applications may have this kind of modes.
  • When storing typing history does not make much sense. Specifying this flag in typing games may help to avoid typing history from being filled up with words that the user is less likely to type in their daily life. Another example is that when the application already knows that the expected input is not a valid word (e.g. a promotion code that is not a valid word in any natural language).

Applications need to be aware that the flag is not a guarantee, and some IMEs may not respect it.

Public constructors

EditorInfoCompat

Added in 1.1.0
Deprecated in 1.1.0
public EditorInfoCompat()

Public methods

getContentMimeTypes

Added in 1.1.0
public static @NonNull String[] getContentMimeTypes(@NonNull EditorInfo editorInfo)

Gets MIME types that can be accepted by the target editor if the IME calls commitContent

Parameters
@NonNull EditorInfo editorInfo

the editor from which we get the MIME types
Returns
@NonNull String[]

an array of MIME types. An empty array means that commitContent is not supported on this editor

getInitialSelectedText

Added in 1.5.0
public static @Nullable CharSequence getInitialSelectedText(@NonNull EditorInfo editorInfo, int flags)

Gets the selected text, if any. May be null when no text is selected or the selected text is way too long.

Parameters
@NonNull EditorInfo editorInfo

the editor with which to get the text.
int flags

Supplies additional options controlling how the text is returned. May be either 0 or GET_TEXT_WITH_STYLES.
Returns
@Nullable CharSequence

the text that is currently selected, if any. It could be an empty string when there is no text selected. When null is returned, the selected text might be too long or this protocol is not supported.

getInitialTextAfterCursor

Added in 1.5.0
public static @Nullable CharSequence getInitialTextAfterCursor(
    @NonNull EditorInfo editorInfo,
    int length,
    int flags
)

Get n characters of text after the current cursor position. May be null when the protocol is not supported.

Parameters
@NonNull EditorInfo editorInfo

the editor with which to get the text.
int length

The expected length of the text.
int flags

Supplies additional options controlling how the text is returned. May be either 0 or GET_TEXT_WITH_STYLES.
Returns
@Nullable CharSequence

the text after the cursor position; the length of the returned text might be less than n. When there is no text after the cursor, an empty string will be returned. It could also be null when the editor or system could not support this protocol.

getInitialTextBeforeCursor

Added in 1.5.0
public static @Nullable CharSequence getInitialTextBeforeCursor(
    @NonNull EditorInfo editorInfo,
    int length,
    int flags
)

Get n characters of text before the current cursor position. May be null when the protocol is not supported.

Parameters
@NonNull EditorInfo editorInfo

the editor with which to get the text.
int length

The expected length of the text.
int flags

Supplies additional options controlling how the text is returned. May be either 0 or GET_TEXT_WITH_STYLES.
Returns
@Nullable CharSequence

the text before the cursor position; the length of the returned text might be less than n. When there is no text before the cursor, an empty string will be returned. It could also be null when the editor or system could not support this protocol.

isStylusHandwritingEnabled

Added in 1.13.0
public static boolean isStylusHandwritingEnabled(@NonNull EditorInfo editorInfo)

Returns true when an editor has stylus handwriting enabled. false by default.

Parameters
@NonNull EditorInfo editorInfo

the editor from which we get stylus handwriting enabled.
See also
setStylusHandwritingEnabled
isStylusHandwritingAvailable

setContentMimeTypes

Added in 1.1.0
public static void setContentMimeTypes(
    @NonNull EditorInfo editorInfo,
    @Nullable String[] contentMimeTypes
)

Sets MIME types that can be accepted by the target editor if the IME calls commitContent.

Parameters
@NonNull EditorInfo editorInfo

the editor with which we associate supported MIME types
@Nullable String[] contentMimeTypes

an array of MIME types. null and an empty array means that commitContent is not supported on this Editor

setInitialSurroundingSubText

Added in 1.5.0
public static void setInitialSurroundingSubText(
    @NonNull EditorInfo editorInfo,
    @NonNull CharSequence subText,
    int subTextStart
)

Editors may use this method to provide initial input text to IMEs. As the surrounding text could be used to provide various input assistance, we recommend editors to provide the complete initial input text in its onCreateInputConnection callback. When trimming the input text is needed, call this method instead of setInitialSurroundingText(CharSequence) and provide the trimmed position info. Always try to include the selected text within subText to give the system best flexibility to choose where and how to trim subText when necessary.

Parameters
@NonNull EditorInfo editorInfo

the editor with which to set the text.
@NonNull CharSequence subText

The input text. When it was trimmed, subTextStart must be provided correctly.
int subTextStart

The position that the input text got trimmed. For example, when the editor wants to trim out the first 10 chars, subTextStart should be 10.

setInitialSurroundingText

Added in 1.5.0
public static void setInitialSurroundingText(
    @NonNull EditorInfo editorInfo,
    @NonNull CharSequence sourceText
)

Editors may use this method to provide initial input text to IMEs. As the surrounding text could be used to provide various input assistance, we recommend editors to provide the complete initial input text in its onCreateInputConnection callback. The supplied text will then be processed to serve #getInitialTextBeforeCursor, #getInitialSelectedText, and #getInitialTextBeforeCursor. System is allowed to trim sourceText for various reasons while keeping the most valuable data to IMEs.

Editor authors: Providing the initial input text helps reducing IPC calls for IMEs to provide many modern features right after the connection setup. We recommend calling this method in your implementation.

Parameters
@NonNull EditorInfo editorInfo

the editor with which to set the text.
@NonNull CharSequence sourceText

The complete input text.

setStylusHandwritingEnabled

Added in 1.13.0
public static void setStylusHandwritingEnabled(
    @NonNull EditorInfo editorInfo,
    boolean enabled
)

Set true if the editor has stylus handwriting enabled. false by default, editor must set it true to indicate that it supports stylus handwriting.

Parameters
@NonNull EditorInfo editorInfo

the editor with which we set handwriting enabled.
boolean enabled

true if stylus handwriting is enabled.
See also
setAutoHandwritingEnabled