{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

TextFieldValue

public final class TextFieldValue


A class holding information about the editing state.

The input service updates text selection, cursor, text and text composition. This class represents those values and it is possible to observe changes to those values in the text editing composables.

This class stores a snapshot of the input state of the edit buffer and provide utility functions for answering IME requests such as getTextBeforeCursor, getSelectedText.

Input service composition is an instance of text produced by IME. An example visual for the composition is that the currently composed word is visually separated from others with underline, or text background. For description of composition please check W3C IME Composition.

IME composition is defined by composition parameter and function. When a TextFieldValue with null composition is passed to a TextField, if there was an active composition on the text, the changes will be applied. Applying a composition will accept the changes that were still being composed by IME. Please use copy functions if you do not want to intentionally apply the ongoing IME composition.

Summary

Nested types

public static class TextFieldValue.Companion

Public constructors

TextFieldValue(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextRange selection,
    TextRange composition
)
TextFieldValue(
    @NonNull String text,
    @NonNull TextRange selection,
    TextRange composition
)

Public methods

final @NonNull TextFieldValue
copy(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextRange selection,
    TextRange composition
)

Returns a copy of the TextFieldValue.

final @NonNull TextFieldValue
copy(
    @NonNull String text,
    @NonNull TextRange selection,
    TextRange composition
)

Returns a copy of the TextFieldValue.

boolean
equals(Object other)
final @NonNull AnnotatedString

the text to be rendered.

final TextRange

Composition range created by IME.

final @NonNull TextRange

The selection range.

final @NonNull String
int
@NonNull String

Extension functions

final @NonNull AnnotatedString

Returns the currently selected text.

final @NonNull AnnotatedString
TextFieldValueKt.getTextAfterSelection(
    @NonNull TextFieldValue receiver,
    int maxChars
)

Returns the text after the selection.

final @NonNull AnnotatedString
TextFieldValueKt.getTextBeforeSelection(
    @NonNull TextFieldValue receiver,
    int maxChars
)

Returns the text before the selection.

Public constructors

TextFieldValue

public TextFieldValue(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextRange selection,
    TextRange composition
)
Parameters
@NonNull AnnotatedString annotatedString

the text to be rendered.

@NonNull TextRange selection

the selection range. If the selection is collapsed, it represents cursor location. When selection range is out of bounds, it is constrained with the text length.

TextRange composition

the composition range, null means empty composition or apply if a composition exists on the text. Owned by IME, and if you have an instance of TextFieldValue please use copy functions if you do not want to intentionally change the value of this field.

TextFieldValue

public TextFieldValue(
    @NonNull String text,
    @NonNull TextRange selection,
    TextRange composition
)
Parameters
@NonNull String text

the text to be rendered.

@NonNull TextRange selection

the selection range. If the selection is collapsed, it represents cursor location. When selection range is out of bounds, it is constrained with the text length.

TextRange composition

the composition range, null means empty composition or apply if a composition exists on the text. Owned by IME, and if you have an instance of TextFieldValue please use copy functions if you do not want to intentionally change the value of this field.

Public methods

copy

public final @NonNull TextFieldValue copy(
    @NonNull AnnotatedString annotatedString,
    @NonNull TextRange selection,
    TextRange composition
)

Returns a copy of the TextFieldValue.

copy

public final @NonNull TextFieldValue copy(
    @NonNull String text,
    @NonNull TextRange selection,
    TextRange composition
)

Returns a copy of the TextFieldValue.

equals

public boolean equals(Object other)

getAnnotatedString

public final @NonNull AnnotatedString getAnnotatedString()

the text to be rendered.

getComposition

public final TextRange getComposition()

Composition range created by IME. If null, there is no composition range.

Input service composition is an instance of text produced by IME. An example visual for the composition is that the currently composed word is visually separated from others with underline, or text background. For description of composition please check W3C IME Composition

Composition can be set on the by the system, however it is possible to apply an existing composition by setting the value to null. Applying a composition will accept the changes that were still being composed by IME.

getSelection

public final @NonNull TextRange getSelection()

The selection range. If the selection is collapsed, it represents cursor location. When selection range is out of bounds, it is constrained with the text length.

getText

public final @NonNull String getText()

hashCode

public int hashCode()

toString

public @NonNull String toString()

Extension functions

TextFieldValueKt.getSelectedText

public final @NonNull AnnotatedString TextFieldValueKt.getSelectedText(@NonNull TextFieldValue receiver)

Returns the currently selected text.

TextFieldValueKt.getTextAfterSelection

public final @NonNull AnnotatedString TextFieldValueKt.getTextAfterSelection(
    @NonNull TextFieldValue receiver,
    int maxChars
)

Returns the text after the selection.

Parameters
int maxChars

maximum number of characters (exclusive) after the maximum value in TextFieldValue.selection.

See also
max

TextFieldValueKt.getTextBeforeSelection

public final @NonNull AnnotatedString TextFieldValueKt.getTextBeforeSelection(
    @NonNull TextFieldValue receiver,
    int maxChars
)

Returns the text before the selection.

Parameters
int maxChars

maximum number of characters (inclusive) before the minimum value in TextFieldValue.selection.

See also
min