SemanticsOwner


Owns SemanticsNode objects and notifies listeners of changes to the semantics tree

Summary

Public functions

operator SemanticsNode?

Returns the unmerged SemanticsNode with semanticsId, or null if no attached layout with that id has semantics.

Cmn
LayoutInfo?

Returns the attached LayoutInfo with semanticsId, or null if there is none.

Cmn
LayoutInfo?
@ExperimentalComposeUiHostApi
hitTest(position: Offset, onHit: (layoutInfo: LayoutInfo) -> Boolean)

Performs semantics hit testing at position and calls onHit for each hit layout that has semantics, top-most first, until onHit returns true.

Cmn

Public properties

SemanticsNode

The root node of the semantics tree.

Cmn
SemanticsNode

Root node of the unmerged semantics tree.

Cmn

Extension functions

Unit

Visits the semantics nodes in the unmerged tree that aren't completely covered by siblings drawn on top of them.

Cmn
List<SemanticsNode>
SemanticsOwner.getAllSemanticsNodes(
    mergingEnabled: Boolean,
    skipDeactivatedNodes: Boolean
)

Finds all SemanticsNodes in the tree owned by this SemanticsOwner.

Cmn

Public functions

get

@ExperimentalComposeUiHostApi
operator fun get(semanticsId: Int): SemanticsNode?

Returns the unmerged SemanticsNode with semanticsId, or null if no attached layout with that id has semantics.

Allocates a SemanticsNode. Use getLayoutInfo with LayoutInfo.semanticsConfiguration when only the layout or its unmerged configuration is needed.

Parameters
semanticsId: Int

The LayoutInfo.semanticsId of the node.

getLayoutInfo

@ExperimentalComposeUiHostApi
fun getLayoutInfo(semanticsId: Int): LayoutInfo?

Returns the attached LayoutInfo with semanticsId, or null if there is none. Doesn't allocate.

Parameters
semanticsId: Int

The LayoutInfo.semanticsId of the layout.

hitTest

@ExperimentalComposeUiHostApi
fun hitTest(position: Offset, onHit: (layoutInfo: LayoutInfo) -> Boolean): LayoutInfo?

Performs semantics hit testing at position and calls onHit for each hit layout that has semantics, top-most first, until onHit returns true. Each layout is reported once.

Results include hidden nodes; filter them with SemanticsNode.isHidden or LayoutInfo.semanticsConfiguration as needed. Inline text link test markers (SemanticsProperties.LinkTestMarker) are skipped. Hit testing uses the most recent layout, so measure and lay out pending changes first.

import androidx.compose.ui.layout.LayoutInfo
import androidx.compose.ui.semantics.SemanticsProperties
import androidx.compose.ui.semantics.semanticsConfiguration

// A host implementing accessibility hover finds the top-most node under the pointer that isn't
// hidden from accessibility, without allocating a SemanticsNode for every hit.
val hovered: LayoutInfo? =
    semanticsOwner.hitTest(positionInRoot) { layoutInfo ->
        val config = layoutInfo.semanticsConfiguration
        // Stop at the top-most node that isn't hidden; keep looking below otherwise.
        config != null && SemanticsProperties.HideFromAccessibility !in config
    }
// Report hovered?.semanticsId to the accessibility framework, or the host if null.
println("Hovered semantics id: ${hovered?.semanticsId}")
Parameters
position: Offset

Pointer position in root coordinates.

onHit: (layoutInfo: LayoutInfo) -> Boolean

Called with each hit layout. Return true to stop at that layout.

Returns
LayoutInfo?

the layout for which onHit returned true, or null if it never did.

Public properties

rootSemanticsNode

val rootSemanticsNode: SemanticsNode

The root node of the semantics tree. Does not contain any unmerged data. May contain merged data.

unmergedRootSemanticsNode

val unmergedRootSemanticsNode: SemanticsNode

Root node of the unmerged semantics tree.

Extension functions

SemanticsOwner.forEachUncoveredSemanticsNode

@ExperimentalComposeUiHostApi
fun SemanticsOwner.forEachUncoveredSemanticsNode(
    visitor: UncoveredSemanticsNodeVisitor
): Unit

Visits the semantics nodes in the unmerged tree that aren't completely covered by siblings drawn on top of them.

Starts at SemanticsOwner.unmergedRootSemanticsNode, which is always visited (hosts usually map its id to their own root). Children come from SemanticsNode.collectAccessibilityChildren, so descendants of clearAndSetSemantics nodes and inline text link test markers (SemanticsProperties.LinkTestMarker) are not visited. The bounds passed to visitor are the bounding box of the uncovered part of each node's touch bounds; synthetic nodes use the bounds of the node that owns them. Nothing is visited if the root isn't attached and placed.

Parameters
visitor: UncoveredSemanticsNodeVisitor

Called for each uncovered node.

SemanticsOwner.getAllSemanticsNodes

fun SemanticsOwner.getAllSemanticsNodes(
    mergingEnabled: Boolean,
    skipDeactivatedNodes: Boolean = true
): List<SemanticsNode>

Finds all SemanticsNodes in the tree owned by this SemanticsOwner. Return the results in a list.

Parameters
mergingEnabled: Boolean

set to true if you want the data to be merged.

skipDeactivatedNodes: Boolean = true

set to false if you want to collect the nodes which are deactivated. For example, the children of androidx.compose.ui.layout.SubcomposeLayout which are retained to be reused in future are considered deactivated.