SemanticsNode


A list of key/value pairs associated with a layout node or its subtree.

Each SemanticsNode takes its id and initial key/value list from the outermost modifier on one layout node. It also contains the "collapsed" configuration of any other semantics modifiers on the same layout node, and if "mergeDescendants" is specified and enabled, also the "merged" configuration of its subtree.

Summary

Public functions

Boolean

Returns true if at least one property that contributes to mergedConfig matches predicate.

Cmn
Unit

Calculates the bounding box of this node relative to its parent semantics node, with clipping applied, writing the result into rect.

Cmn
Boolean

Calculates the bounding box in root coordinates of the semantics modifier node that provides SemanticsProperties.Shape for this node, writing the result into rect.

Cmn
Unit

Collects child semantics nodes for the accessibility hierarchy in inverse hit test order (paint order), appending them to outChildren.

Cmn
Float

Returns the effective composite alpha (opacity) of this node, computed by resolving the product of this node's layer alpha and all ancestor layer alphas.

Cmn
Unit

Visits the same children as collectAccessibilityChildren, in the same order, without building a list.

Cmn
Unit

Visits every property that contributes to mergedConfig without building the merged configuration.

Cmn
LayoutInfo?

Visits the semantics ancestors of this node, nearest first, without creating a SemanticsNode per ancestor.

Cmn
Int

Returns the position of an alignment line, or AlignmentLine.Unspecified if the line is not provided.

Cmn
T?

Returns the value of key in mergedConfig without building the merged configuration, or null if neither this node nor any merged descendant sets it.

Cmn
Boolean

Returns true if forEachAccessibilityChild visits at least one child.

Cmn

Public properties

Rect

The bounding box for this node relative to the root of this Compose hierarchy, with clipping applied.

Cmn
Rect

The bounding box for this node relative to the window, with clipping applied.

Cmn
List<SemanticsNode>

Contains the children in inverse hit test order (i.e. paint order).

Cmn
SemanticsConfiguration

The list of semantics properties of this node.

Cmn
Int

For newer AccessibilityNodeInfo-based integration test frameworks, it can be matched in the extras with key "androidx.compose.ui.semantics.id"

Cmn
Boolean

Whether this node merges semantics from descendant nodes in this tree.

Cmn
Boolean

Whether this SemanticNode is the root of a tree or not

Cmn
LayoutInfo

The LayoutInfo that this is associated with.

Cmn
SemanticsPropertyProvider

The merged SemanticsPropertyProvider of this node and its descendants, even if this node was constructed with mergingEnabled set to false.

Cmn
Boolean
Cmn
SemanticsNode?

The parent of this node in the tree.

Cmn
Offset

The position of this node relative to the root of this Compose hierarchy, with no clipping applied

Cmn
Offset

The position of this node relative to the window, with no clipping applied

Cmn
Offset

The position of this node relative to the screen, with no clipping applied

Cmn
RootForTest?

The root this node is attached to.

Cmn
IntSize

The size of the bounding box for this node, with no clipping applied

Cmn
Rect

The rectangle of the touchable area.

Cmn
SemanticsPropertyProvider

The unmerged semantics configuration directly declared on this node.

Cmn

Extension properties

Boolean

Returns whether this node is hidden from accessibility services.

Cmn
Boolean

Whether this node is meaningful to accessibility services: it isn't hidden or an inline text link test marker, and it merges descendants, sets a property that accessibility reads, or has an interaction barrier.

Cmn

Public functions

anyMergedProperty

@ExperimentalComposeUiHostApi
fun anyMergedProperty(predicate: (key: SemanticsPropertyKey<*>, Any?) -> Boolean): Boolean

Returns true if at least one property that contributes to mergedConfig matches predicate. Visits properties in the same order as forEachMergedProperty and stops at the first match, without building the merged configuration.

Parameters
predicate: (key: SemanticsPropertyKey<*>, Any?) -> Boolean

Called with each key and value.

calculateBoundsInParent

@ExperimentalComposeUiHostApi
fun calculateBoundsInParent(rect: MutableRect): Unit

Calculates the bounding box of this node relative to its parent semantics node, with clipping applied, writing the result into rect.

If this node is not attached, or has no parent semantics node with bounds, rect is set to empty bounds at (0, 0, 0, 0).

Parameters
rect: MutableRect

The MutableRect into which the calculated bounds are written.

calculateShapeBoundsInRoot

@ExperimentalComposeUiHostApi
fun calculateShapeBoundsInRoot(rect: MutableRect): Boolean

Calculates the bounding box in root coordinates of the semantics modifier node that provides SemanticsProperties.Shape for this node, writing the result into rect. Bounds are not clipped.

If this node does not define a shape, rect is set to (0, 0, 0, 0) and this method returns false. If the shape is defined but its modifier can't be matched or isn't attached, rect receives the outer bounds of the layout (LayoutInfo.calculateOuterBoundsInRoot) and this method returns true.

Parameters
rect: MutableRect

The MutableRect into which the calculated bounds are written.

Returns
Boolean

true if this node defines a SemanticsProperties.Shape, false otherwise.

collectAccessibilityChildren

@ExperimentalComposeUiHostApi
fun collectAccessibilityChildren(outChildren: MutableList<SemanticsNode>): Unit

Collects child semantics nodes for the accessibility hierarchy in inverse hit test order (paint order), appending them to outChildren.

Unlike children, if this node is marked with clearAndSetSemantics, its children are cleared and nothing is appended to outChildren. Synthetic accessibility nodes are included, while inline text link test marker nodes (SemanticsProperties.LinkTestMarker) are excluded because they are exposed via text spans.

Parameters
outChildren: MutableList<SemanticsNode>

The mutable list to which the child semantics nodes are appended.

computeEffectiveAlpha

fun computeEffectiveAlpha(): Float

Returns the effective composite alpha (opacity) of this node, computed by resolving the product of this node's layer alpha and all ancestor layer alphas.

forEachAccessibilityChild

@ExperimentalComposeUiHostApi
fun forEachAccessibilityChild(block: (child: SemanticsNode) -> Unit): Unit

Visits the same children as collectAccessibilityChildren, in the same order, without building a list.

Parameters
block: (child: SemanticsNode) -> Unit

Called with each child.

forEachMergedProperty

@ExperimentalComposeUiHostApi
fun forEachMergedProperty(action: (key: SemanticsPropertyKey<*>, Any?) -> Unit): Unit

Visits every property that contributes to mergedConfig without building the merged configuration.

Visits this node's own properties first, then, if unmergedConfig merges descendants and doesn't clear them, the unmerged properties of each descendant that mergedConfig merges, in merge order. A key can be visited more than once and values are not combined with SemanticsPropertyKey.merge; use getMergedOrNull for the merged value of one key.

Parameters
action: (key: SemanticsPropertyKey<*>, Any?) -> Unit

Called with each key and value.

forEachSemanticsAncestor

@ExperimentalComposeUiHostApi
fun forEachSemanticsAncestor(
    block: (layoutInfo: LayoutInfo, config: SemanticsPropertyProvider) -> Boolean
): LayoutInfo?

Visits the semantics ancestors of this node, nearest first, without creating a SemanticsNode per ancestor.

An ancestor is any enclosing layout that has semantics, whether or not it merges. For a synthetic accessibility node (see collectAccessibilityChildren) the node that owns it is visited first, followed by that node's ancestors.

Parameters
block: (layoutInfo: LayoutInfo, config: SemanticsPropertyProvider) -> Boolean

Called with each ancestor's LayoutInfo and unmerged configuration. Return true to stop at that ancestor.

Returns
LayoutInfo?

the ancestor for which block returned true, or null if it never did.

getAlignmentLinePosition

fun getAlignmentLinePosition(alignmentLine: AlignmentLine): Int

Returns the position of an alignment line, or AlignmentLine.Unspecified if the line is not provided.

getMergedOrNull

@ExperimentalComposeUiHostApi
fun <T : Any?> getMergedOrNull(key: SemanticsPropertyKey<T>): T?

Returns the value of key in mergedConfig without building the merged configuration, or null if neither this node nor any merged descendant sets it.

Applies SemanticsPropertyKey.merge to the values in the same order as mergedConfig.

Parameters
key: SemanticsPropertyKey<T>

Property key to retrieve.

hasAccessibilityChild

@ExperimentalComposeUiHostApi
fun hasAccessibilityChild(): Boolean

Returns true if forEachAccessibilityChild visits at least one child. Stops at the first child, without building a list or creating SemanticsNodes.

Public properties

boundsInRoot

val boundsInRoot: Rect

The bounding box for this node relative to the root of this Compose hierarchy, with clipping applied. To get the bounds with no clipping applied, use Rect(positionInRoot, size.toSize())

boundsInWindow

val boundsInWindow: Rect

The bounding box for this node relative to the window, with clipping applied. To get the bounds with no clipping applied, use PxBounds(positionInWindow, size.toSize())

children

val children: List<SemanticsNode>

Contains the children in inverse hit test order (i.e. paint order).

Note that if mergingEnabled and mergeDescendants are both true, then there are no children (except those that are themselves mergeDescendants).

config

val config: SemanticsConfiguration

The list of semantics properties of this node.

This includes all properties attached as modifiers to the current layout node. In addition, if mergeDescendants and mergingEnabled are both true, then it also includes the semantics properties of descendant nodes.

id

val id: Int

For newer AccessibilityNodeInfo-based integration test frameworks, it can be matched in the extras with key "androidx.compose.ui.semantics.id"

isMergingSemanticsOfDescendants

@ExperimentalComposeUiHostApi
val isMergingSemanticsOfDescendants: Boolean

Whether this node merges semantics from descendant nodes in this tree.

true only when mergingEnabled is true and unmergedConfig declares SemanticsPropertyProvider.isMergingSemanticsOfDescendants. In the unmerged tree (mergingEnabled false) this is always false, while unmergedConfig.isMergingSemanticsOfDescendants still reports the declared value.

isRoot

val isRoot: Boolean

Whether this SemanticNode is the root of a tree or not

layoutInfo

val layoutInfo: LayoutInfo

The LayoutInfo that this is associated with.

mergedConfig

@ExperimentalComposeUiHostApi
val mergedConfig: SemanticsPropertyProvider

The merged SemanticsPropertyProvider of this node and its descendants, even if this node was constructed with mergingEnabled set to false.

If this node does not merge descendant semantics, returns unmergedConfig. Otherwise each call walks the merging subtree and allocates a new merged configuration, so the result reflects the current tree. To read a single key use getMergedOrNull; to scan the merged properties without building a merged configuration use forEachMergedProperty or anyMergedProperty.

mergingEnabled

val mergingEnabled: Boolean

parent

val parent: SemanticsNode?

The parent of this node in the tree.

positionInRoot

val positionInRoot: Offset

The position of this node relative to the root of this Compose hierarchy, with no clipping applied

positionInWindow

val positionInWindow: Offset

The position of this node relative to the window, with no clipping applied

positionOnScreen

val positionOnScreen: Offset

The position of this node relative to the screen, with no clipping applied

root

val root: RootForTest?

The root this node is attached to.

size

val size: IntSize

The size of the bounding box for this node, with no clipping applied

touchBoundsInRoot

val touchBoundsInRoot: Rect

The rectangle of the touchable area.

If this is a clickable region, this is the rectangle that accepts touch input. This can be larger than size when the layout is less than ViewConfiguration.minimumTouchTargetSize

unmergedConfig

@ExperimentalComposeUiHostApi
val unmergedConfig: SemanticsPropertyProvider

The unmerged semantics configuration directly declared on this node.

Contains properties defined on this node without merging semantics from descendants.

Extension properties

SemanticsNode.isHidden

@ExperimentalComposeUiHostApi
val SemanticsNode.isHidden: Boolean

Returns whether this node is hidden from accessibility services.

SemanticsNode.isImportantForAccessibility

@ExperimentalComposeUiHostApi
val SemanticsNode.isImportantForAccessibility: Boolean

Whether this node is meaningful to accessibility services: it isn't hidden or an inline text link test marker, and it merges descendants, sets a property that accessibility reads, or has an interaction barrier.