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

Public companion properties
Saver<TextFieldValue, Any>

The default Saver implementation for TextFieldValue.
Cmn

Public constructors
TextFieldValue(
    annotatedString: AnnotatedString,
    selection: TextRange,
    composition: TextRange?
)
Cmn
TextFieldValue(text: String, selection: TextRange, composition: TextRange?)
Cmn

Public functions
TextFieldValue
copy(
    annotatedString: AnnotatedString,
    selection: TextRange,
    composition: TextRange?
)

Returns a copy of the TextFieldValue.
Cmn
TextFieldValue
copy(text: String, selection: TextRange, composition: TextRange?)

Returns a copy of the TextFieldValue.
Cmn
open operator Boolean
equals(other: Any?)
Cmn
open Int
Cmn
open String
Cmn

Public properties
AnnotatedString

the text to be rendered.
Cmn
TextRange?

Composition range created by IME.
Cmn
TextRange

The selection range.
Cmn
String
Cmn

Extension functions
AnnotatedString

Returns the currently selected text.
Cmn
AnnotatedString

Returns the text after the selection.
Cmn
AnnotatedString

Returns the text before the selection.
Cmn

Public companion properties

Saver

Cmn
Added in 1.0.0
val Saver: Saver<TextFieldValue, Any>

The default Saver implementation for TextFieldValue.

Public constructors

TextFieldValue

Cmn 
TextFieldValue(
    annotatedString: AnnotatedString,
    selection: TextRange = TextRange.Zero,
    composition: TextRange? = null
)
Parameters
annotatedString: AnnotatedString

the text to be rendered.
selection: TextRange = TextRange.Zero

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.
composition: TextRange? = null

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

Cmn 
TextFieldValue(
    text: String = "",
    selection: TextRange = TextRange.Zero,
    composition: TextRange? = null
)
Parameters
text: String = ""

the text to be rendered.
selection: TextRange = TextRange.Zero

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.
composition: TextRange? = null

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 functions

copy

Cmn 
fun copy(
    annotatedString: AnnotatedString = this.annotatedString,
    selection: TextRange = this.selection,
    composition: TextRange? = this.composition
): TextFieldValue

Returns a copy of the TextFieldValue.

copy

Cmn 
fun copy(
    text: String,
    selection: TextRange = this.selection,
    composition: TextRange? = this.composition
): TextFieldValue

Returns a copy of the TextFieldValue.

equals

Cmn 
open operator fun equals(other: Any?): Boolean

hashCode

Cmn 
open fun hashCode(): Int

toString

Cmn 
open fun toString(): String

Public properties

annotatedString

Cmn
Added in 1.0.0
val annotatedString: AnnotatedString

the text to be rendered.

composition

Cmn
Added in 1.0.0
val composition: TextRange?

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.

selection

Cmn
Added in 1.0.0
val selection: TextRange

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.

text

Cmn
Added in 1.0.0
val text: String

Extension functions

getSelectedText

Cmn 
fun TextFieldValue.getSelectedText(): AnnotatedString

Returns the currently selected text.

getTextAfterSelection

Cmn 
fun TextFieldValue.getTextAfterSelection(maxChars: Int): AnnotatedString

Returns the text after the selection.

Parameters
maxChars: Int

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

getTextBeforeSelection

Cmn 
fun TextFieldValue.getTextBeforeSelection(maxChars: Int): AnnotatedString

Returns the text before the selection.

Parameters
maxChars: Int

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