SelectionState

class SelectionState

Selection state object for a particular SelectionContainer. It is invalid for the same SelectionState to be passed to multiple SelectionContainers. Holds the currently selected text and functions to perform Selection actions programmatically.

When instantiating this class from a composable, use rememberSelectionState to automatically save and restore the selection state. For more advanced use cases, pass SelectionState.Saver to rememberSaveable.

Properties

selectedTexts

val selectedTexts: List<AnnotatedString>

The currently selected texts in the SelectionContainer corresponding to this SelectionState, in visual/layout order. Each text composable within the Selection is returned as an AnnotatedString in the list. This field is backed by androidx.compose.runtime.mutableStateOf so it can be observed by Composables.

Functions

selectAll

fun selectAll()

Sets the current selection to include every selectable Text Composable within the SelectionContainer.

Note: When using SelectionContainer with androidx.compose.foundation.lazy.LazyList, selectAll will only select all selectable Text Composables that are composed.

clear

fun clear()

Clears the current selection for the SelectionContainer and removes selection handles.

extendSelectionByWord

fun extendSelectionByWord()

Extends the current selection to the next word boundary, if there is another word boundary available within the SelectionContainer. The next word is added at the active edge of the selection, following the current text direction. So if the selection is dragged in reverse, this adds a word earlier in the text.

If the next word in the selection is in a different Text composable, this extends to the next Text. If there is no selection, this selects the first word in the SelectionContainer.

Word boundaries separate words and non-words such as spaces, symbols, and punctuation. Word boundaries are defined more precisely in Unicode Standard Annex #29 <https://www.unicode.org/reports/tr29/#Word_Boundaries>.

getSelectableTexts

fun getSelectableTexts(): List<AnnotatedString>

Returns a list of all selectable texts within the SelectionContainer in visual/layout order. This returns the entire text content, including all selected or unselected portions. Text nodes excluded from selection using DisableSelection will not be included in the list. Calling this function can be inefficient for containers holding a large volume of text composables.

Note: This should not be called during composition as it requires the layout to be ready.

select

fun select(range: TextRange)

Sets the selection to the specified TextRange within the global space of all Texts inside the SelectionContainer. This function loops through all selectables in the SelectionContainer, so it is not advised to call within a loop or as an effect that triggers frequently.

Note: This should not be called during composition as it requires the layout to be ready.

Companion Object

Properties

val Saver: Saver<SelectionState, Any>