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

SemanticsPropertiesKt

public final class SemanticsPropertiesKt


Summary

Public methods

static final void
collapse(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to collapse an expandable node.

static final void
copyText(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to copy the text to the clipboard.

static final void
cutText(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to cut the text and copy it to the clipboard.

static final void

Whether this element is a Dialog.

static final void

Whether this semantics node is disabled.

static final void
dismiss(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to dismiss a dismissible node.

static final void
error(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String description
)

Mark semantics node that contains invalid input or error.

static final void
expand(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to expand an expandable node.

static final @NonNull CollectionInfo

This semantics marks node as a collection and provides the required information.

static final @NonNull CollectionItemInfo

This semantics marks node as an items of a collection and provides the required information.

static final @NonNull String

Developer-set content description of the semantics node.

static final @NonNull List<@NonNull CustomAccessibilityAction>

Custom actions which are defined by app developers.

static final @NonNull AnnotatedString

Input text of the text field with visual transformation applied to it.

static final boolean

Whether this semantics node is focused.

static final @NonNull ScrollAxisRange

The horizontal scroll state of this node if this node is scrollable.

static final @NonNull ImeAction

Contains the IME action provided by the node.

static final @NonNull LiveRegionMode

This node is marked as live region for accessibility.

static final @NonNull String

Accessibility-friendly title for a screen's pane.

static final @NonNull ProgressBarRangeInfo

The semantics is represents a range of possible values with a current value.

static final @NonNull Role

The type of user interface element.

static final boolean

Whether this element is selected (out of a list of possible selections).

static final @NonNull String

Developer-set state description of the semantics node.

static final @NonNull String

Test tag attached to this semantics node.

static final boolean

Configuration toggle to map testTags to resource-id.

static final @NonNull AnnotatedString

Text of the semantics node.

static final void
getTextLayoutResult(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function1<@NonNull List<@NonNull TextLayoutResult>, @NonNull Boolean> action
)

Action to get a Text/TextField node's TextLayoutResult.

static final @NonNull TextRange

Text selection range for the text field.

static final @NonNull ToggleableState

The state of a toggleable component.

static final float

A value to manually control screenreader traversal order.

static final @NonNull ScrollAxisRange

The vertical scroll state of this node if this node is scrollable.

static final void

The node is marked as heading for accessibility.

static final void
indexForKey(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull Function1<@NonNull Object, @NonNull Integer> mapping
)

The index of an item identified by a given key.

static final void
insertTextAtCursor(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function1<@NonNull AnnotatedString, @NonNull Boolean> action
)

Action to insert text into this node at the current cursor position, or replacing the selection if text is selected.

static final void

Whether this node is specially known to be invisible to the user.

static final boolean

Whether this semantics node is a container.

static final boolean

Whether this semantics node is a traversal group.

static final void
onClick(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to be performed when the node is clicked (single-tapped).

static final void
onLongClick(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to be performed when the node is long clicked (long-pressed).

static final void
pageDown(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to page down.

static final void
pageLeft(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to page left.

static final void
pageRight(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to page right.

static final void
pageUp(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to page up.

static final void

The node is marked as a password.

static final void
pasteText(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

This function adds the SemanticsActions.PasteText to the SemanticsPropertyReceiver.

static final void
performImeAction(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to invoke the IME action handler configured on the node.

static final void

Whether this semantics node represents a Popup.

static final void
requestFocus(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action that gives input focus to this node.

static final void
scrollBy(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function2<@NonNull Float, @NonNull Float, @NonNull Boolean> action
)

Action to scroll by a specified amount.

static final void
scrollToIndex(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    @NonNull Function1<@NonNull Integer, @NonNull Boolean> action
)

Action to scroll a container to the index of one of its items.

static final void

The node is marked as a collection of horizontally or vertically stacked selectable elements.

static final void
setCollectionInfo(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull CollectionInfo collectionInfo
)

This semantics marks node as a collection and provides the required information.

static final void
setCollectionItemInfo(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull CollectionItemInfo collectionItemInfo
)

This semantics marks node as an items of a collection and provides the required information.

static final void
setContainer(
    @NonNull SemanticsPropertyReceiver receiver,
    boolean isContainer
)

Whether this semantics node is a container.

static final void
setContentDescription(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String contentDescription
)

Developer-set content description of the semantics node.

static final void

Custom actions which are defined by app developers.

static final void
setEditableText(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull AnnotatedString editableText
)

Input text of the text field with visual transformation applied to it.

static final void
setFocused(@NonNull SemanticsPropertyReceiver receiver, boolean focused)

Whether this semantics node is focused.

static final void
setHorizontalScrollAxisRange(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ScrollAxisRange horizontalScrollAxisRange
)

The horizontal scroll state of this node if this node is scrollable.

static final void
setImeAction(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ImeAction imeAction
)

Contains the IME action provided by the node.

static final void
setLiveRegion(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull LiveRegionMode liveRegion
)

This node is marked as live region for accessibility.

static final void
setPaneTitle(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String paneTitle
)

Accessibility-friendly title for a screen's pane.

static final void
setProgress(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function1<@NonNull Float, @NonNull Boolean> action
)

Action to set the current value of the progress bar.

static final void
setProgressBarRangeInfo(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ProgressBarRangeInfo progressBarRangeInfo
)

The semantics is represents a range of possible values with a current value.

static final void

The type of user interface element.

static final void
setSelected(
    @NonNull SemanticsPropertyReceiver receiver,
    boolean selected
)

Whether this element is selected (out of a list of possible selections).

static final void
setSelection(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function3<@NonNull Integer, @NonNull Integer, @NonNull Boolean, @NonNull Boolean> action
)

Action to set text selection by character index range.

static final void
setStateDescription(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String stateDescription
)

Developer-set state description of the semantics node.

static final void
setTestTag(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String testTag
)

Test tag attached to this semantics node.

static final void

Configuration toggle to map testTags to resource-id.

static final void

Text of the semantics node.

static final void
setText(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function1<@NonNull AnnotatedString, @NonNull Boolean> action
)

Action to set the text contents of this node.

static final void
setTextSelectionRange(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull TextRange textSelectionRange
)

Text selection range for the text field.

static final void
setToggleableState(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ToggleableState toggleableState
)

The state of a toggleable component.

static final void
setTraversalGroup(
    @NonNull SemanticsPropertyReceiver receiver,
    boolean isTraversalGroup
)

Whether this semantics node is a traversal group.

static final void
setTraversalIndex(
    @NonNull SemanticsPropertyReceiver receiver,
    float traversalIndex
)

A value to manually control screenreader traversal order.

static final void
setVerticalScrollAxisRange(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ScrollAxisRange verticalScrollAxisRange
)

The vertical scroll state of this node if this node is scrollable.

Public methods

collapse

public static final void collapse(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to collapse an expandable node.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.Collapse is called.

copyText

public static final void copyText(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to copy the text to the clipboard.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.CopyText is called.

cutText

public static final void cutText(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to cut the text and copy it to the clipboard.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.CutText is called.

dialog

public static final void dialog(@NonNull SemanticsPropertyReceiver receiver)

Whether this element is a Dialog. Not to be confused with if this element is part of a Dialog.

disabled

public static final void disabled(@NonNull SemanticsPropertyReceiver receiver)

Whether this semantics node is disabled. Note that proper SemanticsActions should still be added when this property is set.

See also
Disabled

dismiss

public static final void dismiss(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to dismiss a dismissible node.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.Dismiss is called.

error

public static final void error(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String description
)

Mark semantics node that contains invalid input or error.

Parameters
@NonNull String description

a localized description explaining an error to the accessibility user

expand

public static final void expand(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to expand an expandable node.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.Expand is called.

getCollectionInfo

public static final @NonNull CollectionInfo getCollectionInfo(@NonNull SemanticsPropertyReceiver receiver)

This semantics marks node as a collection and provides the required information.

getCollectionItemInfo

public static final @NonNull CollectionItemInfo getCollectionItemInfo(@NonNull SemanticsPropertyReceiver receiver)

This semantics marks node as an items of a collection and provides the required information.

If you mark items of a collection, you should also be marking the collection with collectionInfo.

getContentDescription

public static final @NonNull String getContentDescription(@NonNull SemanticsPropertyReceiver receiver)

Developer-set content description of the semantics node.

If this is not set, accessibility services will present the text of this node as the content.

This typically should not be set directly by applications, because some screen readers will cease presenting other relevant information when this property is present. This is intended to be used via Foundation components which are inherently intractable to automatically describe, such as Image, Icon, and Canvas.

getCustomActions

public static final @NonNull List<@NonNull CustomAccessibilityActiongetCustomActions(@NonNull SemanticsPropertyReceiver receiver)

Custom actions which are defined by app developers.

getEditableText

public static final @NonNull AnnotatedString getEditableText(@NonNull SemanticsPropertyReceiver receiver)

Input text of the text field with visual transformation applied to it. It must be a real text entered by the user with visual transformation applied on top of the input text instead of a developer-set content description.

getFocused

public static final boolean getFocused(@NonNull SemanticsPropertyReceiver receiver)

Whether this semantics node is focused. The presence of this property indicates this node is focusable

See also
Focused

getHorizontalScrollAxisRange

public static final @NonNull ScrollAxisRange getHorizontalScrollAxisRange(
    @NonNull SemanticsPropertyReceiver receiver
)

The horizontal scroll state of this node if this node is scrollable.

getImeAction

public static final @NonNull ImeAction getImeAction(@NonNull SemanticsPropertyReceiver receiver)

Contains the IME action provided by the node.

For example, "go to next form field" or "submit".

A node that specifies an action should also specify a callback to perform the action via performImeAction.

getLiveRegion

public static final @NonNull LiveRegionMode getLiveRegion(@NonNull SemanticsPropertyReceiver receiver)

This node is marked as live region for accessibility. This indicates to accessibility services they should automatically notify the user about changes to the node's content description or text, or to the content descriptions or text of the node's children (where applicable). It should be used with caution, especially with assertive mode which immediately stops the current audio and the user does not hear the rest of the content. An example of proper use is a Snackbar which is marked as LiveRegionMode.Polite.

getPaneTitle

public static final @NonNull String getPaneTitle(@NonNull SemanticsPropertyReceiver receiver)

Accessibility-friendly title for a screen's pane. For accessibility purposes, a pane is a visually distinct portion of a window, such as the contents of a open drawer. In order for accessibility services to understand a pane's window-like behavior, you should give descriptive titles to your app's panes. Accessibility services can then provide more granular information to users when a pane's appearance or content changes.

See also
PaneTitle

getProgressBarRangeInfo

public static final @NonNull ProgressBarRangeInfo getProgressBarRangeInfo(@NonNull SemanticsPropertyReceiver receiver)

The semantics is represents a range of possible values with a current value. For example, when used on a slider control, this will allow screen readers to communicate the slider's state.

getRole

public static final @NonNull Role getRole(@NonNull SemanticsPropertyReceiver receiver)

The type of user interface element. Accessibility services might use this to describe the element or do customizations. Most roles can be automatically resolved by the semantics properties of this element. But some elements with subtle differences need an exact role. If an exact role is not listed in Role, this property should not be set and the framework will automatically resolve it.

getSelected

public static final boolean getSelected(@NonNull SemanticsPropertyReceiver receiver)

Whether this element is selected (out of a list of possible selections).

The presence of this property indicates that the element is selectable.

getStateDescription

public static final @NonNull String getStateDescription(@NonNull SemanticsPropertyReceiver receiver)

Developer-set state description of the semantics node.

For example: on/off. If this not set, accessibility services will derive the state from other semantics properties, like ProgressBarRangeInfo, but it is not guaranteed and the format will be decided by accessibility services.

getTestTag

public static final @NonNull String getTestTag(@NonNull SemanticsPropertyReceiver receiver)

Test tag attached to this semantics node.

This can be used to find nodes in testing frameworks:

getTestTagsAsResourceId

@ExperimentalComposeUiApi
public static final boolean getTestTagsAsResourceId(@NonNull SemanticsPropertyReceiver receiver)

Configuration toggle to map testTags to resource-id.

This provides a way of filling in AccessibilityNodeInfo.viewIdResourceName, which in the View System is populated based on the resource string in the XML.

testTags are also provided in AccessibilityNodeInfo.extras under key "androidx.compose.ui.semantics.testTag". However, when using UIAutomator or on Android 7 and below, extras are not available, so a more backwards-compatible way of making testTags available to accessibility-tree-based integration tests is sometimes needed. resource-id was the most natural property to repurpose for this.

This property applies to a semantics subtree. For example, if it's set to true on the root semantics node of the app (and no child nodes set it back to false), then every testTag will be mapped.

getText

public static final @NonNull AnnotatedString getText(@NonNull SemanticsPropertyReceiver receiver)

Text of the semantics node. It must be real text instead of developer-set content description.

See also
editableText

getTextLayoutResult

public static final void getTextLayoutResult(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function1<@NonNull List<@NonNull TextLayoutResult>, @NonNull Boolean> action
)

Action to get a Text/TextField node's TextLayoutResult. The result is the first element of layout (the argument of the AccessibilityAction).

Parameters
String label

Optional label for this action.

Function1<@NonNull List<@NonNull TextLayoutResult>, @NonNull Boolean> action

Action to be performed when the SemanticsActions.GetTextLayoutResult is called.

getTextSelectionRange

public static final @NonNull TextRange getTextSelectionRange(@NonNull SemanticsPropertyReceiver receiver)

Text selection range for the text field.

getToggleableState

public static final @NonNull ToggleableState getToggleableState(@NonNull SemanticsPropertyReceiver receiver)

The state of a toggleable component.

The presence of this property indicates that the element is toggleable.

getTraversalIndex

public static final float getTraversalIndex(@NonNull SemanticsPropertyReceiver receiver)

A value to manually control screenreader traversal order.

This API can be used to customize TalkBack traversal order. When the traversalIndex property is set on a traversalGroup or on a screenreader-focusable node, then the sorting algorithm will prioritize nodes with smaller traversalIndexs earlier. The default traversalIndex value is zero, and traversalIndices are compared at a peer level.

For example,traversalIndex = -1f can be used to force a top bar to be ordered earlier, and traversalIndex = 1f to make a bottom bar ordered last, in the edge cases where this does not happen by default. As another example, if you need to reorder two Buttons within a Row, then you can set isTraversalGroup = true on the Row, and set traversalIndex on one of the Buttons.

Note that if traversalIndex seems to have no effect, be sure to set isTraversalGroup = true as well.

getVerticalScrollAxisRange

public static final @NonNull ScrollAxisRange getVerticalScrollAxisRange(@NonNull SemanticsPropertyReceiver receiver)

The vertical scroll state of this node if this node is scrollable.

heading

public static final void heading(@NonNull SemanticsPropertyReceiver receiver)

The node is marked as heading for accessibility.

See also
Heading

indexForKey

public static final void indexForKey(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull Function1<@NonNull Object, @NonNull Integer> mapping
)

The index of an item identified by a given key. The key is usually defined during the creation of the container. If the key did not match any of the items' keys, the mapping must return -1.

insertTextAtCursor

public static final void insertTextAtCursor(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function1<@NonNull AnnotatedString, @NonNull Boolean> action
)

Action to insert text into this node at the current cursor position, or replacing the selection if text is selected.

Expected to be used on editable text fields.

Parameters
String label

Optional label for this action.

Function1<@NonNull AnnotatedString, @NonNull Boolean> action

Action to be performed when SemanticsActions.InsertTextAtCursor is called.

invisibleToUser

@ExperimentalComposeUiApi
public static final void invisibleToUser(@NonNull SemanticsPropertyReceiver receiver)

Whether this node is specially known to be invisible to the user.

For example, if the node is currently occluded by a dark semitransparent pane above it, then for all practical purposes the node is invisible to the user, but the system cannot automatically determine that. To make the screen reader linear navigation skip over this type of invisible node, this property can be set.

If looking for a way to hide semantics of small items from screen readers because they're redundant with semantics of their parent, consider SemanticsModifier.clearAndSetSemantics instead.

isContainer

public static final boolean isContainer(@NonNull SemanticsPropertyReceiver receiver)

Whether this semantics node is a container. This is defined as a node whose function is to serve as a boundary or border in organizing its children.

See also
IsContainer

isTraversalGroup

public static final boolean isTraversalGroup(@NonNull SemanticsPropertyReceiver receiver)

Whether this semantics node is a traversal group. This is defined as a node whose function is to serve as a boundary or border in organizing its children.

See also
IsTraversalGroup

onClick

public static final void onClick(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to be performed when the node is clicked (single-tapped).

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.OnClick is called.

onLongClick

public static final void onLongClick(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to be performed when the node is long clicked (long-pressed).

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.OnLongClick is called.

pageDown

public static final void pageDown(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to page down.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.PageDown is called.

pageLeft

public static final void pageLeft(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to page left.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.PageLeft is called.

pageRight

public static final void pageRight(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to page right.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.PageRight is called.

pageUp

public static final void pageUp(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to page up.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.PageUp is called.

password

public static final void password(@NonNull SemanticsPropertyReceiver receiver)

The node is marked as a password.

pasteText

public static final void pasteText(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

This function adds the SemanticsActions.PasteText to the SemanticsPropertyReceiver. Use it to indicate that element is open for accepting paste data from the clipboard. There is no need to check if the clipboard data available as this is done by the framework. For this action to be triggered, the element must also have the SemanticsProperties.Focused property set.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.PasteText is called.

See also
focused

performImeAction

public static final void performImeAction(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action to invoke the IME action handler configured on the node.

Expected to be used on editable text fields.

A node that specifies an action callback should also report what IME action it will perform via the imeAction property.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when SemanticsActions.PerformImeAction is called.

popup

public static final void popup(@NonNull SemanticsPropertyReceiver receiver)

Whether this semantics node represents a Popup. Not to be confused with if this node is part of a Popup.

requestFocus

public static final void requestFocus(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function0<@NonNull Boolean> action
)

Action that gives input focus to this node.

Parameters
String label

Optional label for this action.

Function0<@NonNull Boolean> action

Action to be performed when the SemanticsActions.RequestFocus is called.

scrollBy

public static final void scrollBy(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function2<@NonNull Float, @NonNull Float, @NonNull Boolean> action
)

Action to scroll by a specified amount.

Expected to be used in conjunction with verticalScrollAxisRange/horizontalScrollAxisRange.

Parameters
String label

Optional label for this action.

Function2<@NonNull Float, @NonNull Float, @NonNull Boolean> action

Action to be performed when the SemanticsActions.ScrollBy is called.

scrollToIndex

public static final void scrollToIndex(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    @NonNull Function1<@NonNull Integer, @NonNull Boolean> action
)

Action to scroll a container to the index of one of its items.

The action should throw an IllegalArgumentException if the index is out of bounds.

selectableGroup

public static final void selectableGroup(@NonNull SemanticsPropertyReceiver receiver)

The node is marked as a collection of horizontally or vertically stacked selectable elements.

Unlike collectionInfo which marks a collection of any elements and asks developer to provide all the required information like number of elements etc., this semantics will populate the number of selectable elements automatically. Note that if you use this semantics with lazy collections, it won't get the number of elements in the collection.

See also
selected

setCollectionInfo

public static final void setCollectionInfo(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull CollectionInfo collectionInfo
)

This semantics marks node as a collection and provides the required information.

setCollectionItemInfo

public static final void setCollectionItemInfo(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull CollectionItemInfo collectionItemInfo
)

This semantics marks node as an items of a collection and provides the required information.

If you mark items of a collection, you should also be marking the collection with collectionInfo.

setContainer

public static final void setContainer(
    @NonNull SemanticsPropertyReceiver receiver,
    boolean isContainer
)

Whether this semantics node is a container. This is defined as a node whose function is to serve as a boundary or border in organizing its children.

See also
IsContainer

setContentDescription

public static final void setContentDescription(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String contentDescription
)

Developer-set content description of the semantics node.

If this is not set, accessibility services will present the text of this node as the content.

This typically should not be set directly by applications, because some screen readers will cease presenting other relevant information when this property is present. This is intended to be used via Foundation components which are inherently intractable to automatically describe, such as Image, Icon, and Canvas.

setCustomActions

public static final void setCustomActions(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull List<@NonNull CustomAccessibilityAction> customActions
)

Custom actions which are defined by app developers.

setEditableText

public static final void setEditableText(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull AnnotatedString editableText
)

Input text of the text field with visual transformation applied to it. It must be a real text entered by the user with visual transformation applied on top of the input text instead of a developer-set content description.

setFocused

public static final void setFocused(@NonNull SemanticsPropertyReceiver receiver, boolean focused)

Whether this semantics node is focused. The presence of this property indicates this node is focusable

See also
Focused

setHorizontalScrollAxisRange

public static final void setHorizontalScrollAxisRange(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ScrollAxisRange horizontalScrollAxisRange
)

The horizontal scroll state of this node if this node is scrollable.

setImeAction

public static final void setImeAction(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ImeAction imeAction
)

Contains the IME action provided by the node.

For example, "go to next form field" or "submit".

A node that specifies an action should also specify a callback to perform the action via performImeAction.

setLiveRegion

public static final void setLiveRegion(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull LiveRegionMode liveRegion
)

This node is marked as live region for accessibility. This indicates to accessibility services they should automatically notify the user about changes to the node's content description or text, or to the content descriptions or text of the node's children (where applicable). It should be used with caution, especially with assertive mode which immediately stops the current audio and the user does not hear the rest of the content. An example of proper use is a Snackbar which is marked as LiveRegionMode.Polite.

setPaneTitle

public static final void setPaneTitle(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String paneTitle
)

Accessibility-friendly title for a screen's pane. For accessibility purposes, a pane is a visually distinct portion of a window, such as the contents of a open drawer. In order for accessibility services to understand a pane's window-like behavior, you should give descriptive titles to your app's panes. Accessibility services can then provide more granular information to users when a pane's appearance or content changes.

See also
PaneTitle

setProgress

public static final void setProgress(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function1<@NonNull Float, @NonNull Boolean> action
)

Action to set the current value of the progress bar.

Expected to be used in conjunction with progressBarRangeInfo.

Parameters
String label

Optional label for this action.

Function1<@NonNull Float, @NonNull Boolean> action

Action to be performed when the SemanticsActions.SetProgress is called.

setProgressBarRangeInfo

public static final void setProgressBarRangeInfo(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ProgressBarRangeInfo progressBarRangeInfo
)

The semantics is represents a range of possible values with a current value. For example, when used on a slider control, this will allow screen readers to communicate the slider's state.

setRole

public static final void setRole(@NonNull SemanticsPropertyReceiver receiver, @NonNull Role role)

The type of user interface element. Accessibility services might use this to describe the element or do customizations. Most roles can be automatically resolved by the semantics properties of this element. But some elements with subtle differences need an exact role. If an exact role is not listed in Role, this property should not be set and the framework will automatically resolve it.

setSelected

public static final void setSelected(
    @NonNull SemanticsPropertyReceiver receiver,
    boolean selected
)

Whether this element is selected (out of a list of possible selections).

The presence of this property indicates that the element is selectable.

setSelection

public static final void setSelection(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function3<@NonNull Integer, @NonNull Integer, @NonNull Boolean, @NonNull Boolean> action
)

Action to set text selection by character index range.

If this action is provided, the selection data must be provided using textSelectionRange.

Parameters
String label

Optional label for this action.

Function3<@NonNull Integer, @NonNull Integer, @NonNull Boolean, @NonNull Boolean> action

Action to be performed when the SemanticsActions.SetSelection is called. The parameters to the action are: startIndex, endIndex, and whether the indices are relative to the original text or the transformed text (when a VisualTransformation is applied).

setStateDescription

public static final void setStateDescription(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String stateDescription
)

Developer-set state description of the semantics node.

For example: on/off. If this not set, accessibility services will derive the state from other semantics properties, like ProgressBarRangeInfo, but it is not guaranteed and the format will be decided by accessibility services.

setTestTag

public static final void setTestTag(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull String testTag
)

Test tag attached to this semantics node.

This can be used to find nodes in testing frameworks:

setTestTagsAsResourceId

@ExperimentalComposeUiApi
public static final void setTestTagsAsResourceId(
    @NonNull SemanticsPropertyReceiver receiver,
    @ExperimentalComposeUiApi boolean testTagsAsResourceId
)

Configuration toggle to map testTags to resource-id.

This provides a way of filling in AccessibilityNodeInfo.viewIdResourceName, which in the View System is populated based on the resource string in the XML.

testTags are also provided in AccessibilityNodeInfo.extras under key "androidx.compose.ui.semantics.testTag". However, when using UIAutomator or on Android 7 and below, extras are not available, so a more backwards-compatible way of making testTags available to accessibility-tree-based integration tests is sometimes needed. resource-id was the most natural property to repurpose for this.

This property applies to a semantics subtree. For example, if it's set to true on the root semantics node of the app (and no child nodes set it back to false), then every testTag will be mapped.

setText

public static final void setText(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull AnnotatedString text
)

Text of the semantics node. It must be real text instead of developer-set content description.

See also
editableText

setText

public static final void setText(
    @NonNull SemanticsPropertyReceiver receiver,
    String label,
    Function1<@NonNull AnnotatedString, @NonNull Boolean> action
)

Action to set the text contents of this node.

Expected to be used on editable text fields.

Parameters
String label

Optional label for this action.

Function1<@NonNull AnnotatedString, @NonNull Boolean> action

Action to be performed when SemanticsActions.SetText is called.

setTextSelectionRange

public static final void setTextSelectionRange(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull TextRange textSelectionRange
)

Text selection range for the text field.

setToggleableState

public static final void setToggleableState(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ToggleableState toggleableState
)

The state of a toggleable component.

The presence of this property indicates that the element is toggleable.

setTraversalGroup

public static final void setTraversalGroup(
    @NonNull SemanticsPropertyReceiver receiver,
    boolean isTraversalGroup
)

Whether this semantics node is a traversal group. This is defined as a node whose function is to serve as a boundary or border in organizing its children.

See also
IsTraversalGroup

setTraversalIndex

public static final void setTraversalIndex(
    @NonNull SemanticsPropertyReceiver receiver,
    float traversalIndex
)

A value to manually control screenreader traversal order.

This API can be used to customize TalkBack traversal order. When the traversalIndex property is set on a traversalGroup or on a screenreader-focusable node, then the sorting algorithm will prioritize nodes with smaller traversalIndexs earlier. The default traversalIndex value is zero, and traversalIndices are compared at a peer level.

For example,traversalIndex = -1f can be used to force a top bar to be ordered earlier, and traversalIndex = 1f to make a bottom bar ordered last, in the edge cases where this does not happen by default. As another example, if you need to reorder two Buttons within a Row, then you can set isTraversalGroup = true on the Row, and set traversalIndex on one of the Buttons.

Note that if traversalIndex seems to have no effect, be sure to set isTraversalGroup = true as well.

setVerticalScrollAxisRange

public static final void setVerticalScrollAxisRange(
    @NonNull SemanticsPropertyReceiver receiver,
    @NonNull ScrollAxisRange verticalScrollAxisRange
)

The vertical scroll state of this node if this node is scrollable.