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

SemanticsModifierNode

public interface SemanticsModifierNode extends DelegatableNode


A Modifier.Node that adds semantics key/value for use in testing, accessibility, and similar use cases.

This is the androidx.compose.ui.Modifier.Node equivalent of androidx.compose.ui.semantics.SemanticsModifier

Summary

Public methods

abstract void

Add semantics key/value pairs to the layout node, for use in testing, accessibility, etc.

default boolean

Clears the semantics of all the descendant nodes and sets new semantics.

default boolean

Whether the semantic information provided by this node and its descendants should be treated as one logical entity.

Extension functions

default final void

Inherited methods

From androidx.compose.ui.node.DelegatableNode
abstract @NonNull Modifier.Node

A reference of the Modifier.Node that holds this node's position in the node hierarchy.

Public methods

applySemantics

abstract void applySemantics(@NonNull SemanticsPropertyReceiver receiver)

Add semantics key/value pairs to the layout node, for use in testing, accessibility, etc.

The SemanticsPropertyReceiver provides "key = value"-style setters for any SemanticsPropertyKey. Additionally, chaining multiple semantics modifiers is also a supported style.

The resulting semantics produce two SemanticsNode trees:

The "unmerged tree" rooted at SemanticsOwner.unmergedRootSemanticsNode has one SemanticsNode per layout node which has any SemanticsModifierNode on it. This SemanticsNode contains all the properties set in all the SemanticsModifierNodes on that node.

The "merged tree" rooted at SemanticsOwner.rootSemanticsNode has equal-or-fewer nodes: it simplifies the structure based on shouldMergeDescendantSemantics and shouldClearDescendantSemantics. For most purposes (especially accessibility, or the testing of accessibility), the merged semantics tree should be used.

getShouldClearDescendantSemantics

default boolean getShouldClearDescendantSemantics()

Clears the semantics of all the descendant nodes and sets new semantics.

In the merged semantics tree, this clears the semantic information provided by the node's descendants (but not those of the layout node itself, if any) In the unmerged tree, the semantics node is marked with "SemanticsConfiguration.isClearingSemantics", but nothing is actually cleared.

Compose's default semantics provide baseline usability for screen-readers, but this can be used to provide a more polished screen-reader experience: for example, clearing the semantics of a group of tiny buttons, and setting equivalent actions on the card containing them.

getShouldMergeDescendantSemantics

default boolean getShouldMergeDescendantSemantics()

Whether the semantic information provided by this node and its descendants should be treated as one logical entity. Most commonly set on screen-reader-focusable items such as buttons or form fields. In the merged semantics tree, all descendant nodes (except those themselves marked shouldMergeDescendantSemantics) will disappear from the tree, and their properties will get merged into the parent's configuration (using a merging algorithm that varies based on the type of property -- for example, text properties will get concatenated, separated by commas). In the unmerged semantics tree, the node is simply marked with SemanticsConfiguration.isMergingSemanticsOfDescendants.

Extension functions

SemanticsModifierNodeKt.invalidateSemantics

default final void SemanticsModifierNodeKt.invalidateSemantics(
    @NonNull SemanticsModifierNode receiver
)