DelegatableNode

open fun onDensityChange(): Unit

Invoked when the density changes for this node. This affects Dp to pixel conversions, and can cause coordinates / other values to change.

Changes to density will automatically invalidate layout / draw modifiers, as layout, measurement, and draw depend on density. This callback can be used to update any other node state that depends on density, outside of these phases. Density can be retrieved inside a node by using androidx.compose.ui.node.requireDensity.

open fun onLayoutDirectionChange(): Unit

Invoked when the layout direction changes for this node. This can affect the layout and drawing of nodes.

Changes to layout direction will automatically invalidate layout / draw modifiers, as layout, measurement, and draw depend on layout direction. This callback can be used to update any other node state that depends on layout direction, outside of these phases. Layout direction can be retrieved inside a node by using androidx.compose.ui.node.requireLayoutDirection.

val node: Modifier.Node

A reference of the Modifier.Node that holds this node's position in the node hierarchy. If the node is a delegate of another node, this will point to the root delegating node that is actually part of the node tree. Otherwise, this will point to itself.

fun DelegatableNode.invalidateSubtree(): Unit

Invalidates the subtree of this layout, including layout, drawing, parent data, etc.

Calling this method can be a relatively expensive operation as it will cause the entire subtree to relayout and redraw instead of just parts that are otherwise invalidated. Its use should be limited to structural changes.

fun DelegatableNode.requireDensity(): Density

Returns the current Density of the LayoutNode that this DelegatableNode is attached to. If the node is not attached, this function will throw an IllegalStateException.

fun DelegatableNode.requireGraphicsContext(): GraphicsContext

Returns the current GraphicsContext of the Owner

fun DelegatableNode.requireLayoutCoordinates(): LayoutCoordinates

Returns the LayoutCoordinates of this node.

To get a signal when the LayoutCoordinates become available, or when its parent places it, implement LayoutAwareModifierNode.

fun DelegatableNode.requireLayoutDirection(): LayoutDirection

Returns the current LayoutDirection of the LayoutNode that this DelegatableNode is attached to. If the node is not attached, this function will throw an IllegalStateException.

fun DelegatableNode.requireView(): View

The Android View hosting the composition.

fun DelegatableNode.registerOnRectChanged(
    throttleMs: Int,
    debounceMs: Int,
    callback: (RectInfo) -> Unit
): DisposableHandle

Registers a callback to be executed with the position of this modifier node relative to the coordinate system of the root of the composition, as well as in screen coordinates and window coordinates. This will be called after layout pass. This API allows for throttling and debouncing parameters in order to moderate the frequency with which the callback gets invoked during high rates of change (e.g. scrolling).

Specifying throttleMs will prevent callback from being executed more than once over that time period. Specifying debounceMs will delay the execution of callback until that amount of time has elapsed without a new position.

Specifying 0 for both throttleMs and debounceMs will result in the callback being executed every time the position has changed. Specifying non-zero amounts for both will result in both conditions being met.

suspend fun DelegatableNode.scrollIntoView(rect: Rect? = null): Unit

Bring this node into bounds by making all the scrollable parents scroll appropriately.

This method will not return until this request is satisfied or a newer request interrupts it. If this call is interrupted by a newer call, this method will throw a CancellationException.

import androidx.compose.foundation.horizontalScroll
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.relocation.BringIntoViewRequester
import androidx.compose.foundation.relocation.bringIntoViewRequester
import androidx.compose.foundation.rememberScrollState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.focusTarget
import androidx.compose.ui.focus.onFocusChanged

Row(Modifier.horizontalScroll(rememberScrollState())) {
    repeat(100) {
        val bringIntoViewRequester = remember { BringIntoViewRequester() }
        val coroutineScope = rememberCoroutineScope()
        Box(
            Modifier
                // This associates the RelocationRequester with a Composable that wants to be
                // brought into view.
                .bringIntoViewRequester(bringIntoViewRequester)
                .onFocusChanged {
                    if (it.isFocused) {
                        coroutineScope.launch {
                            // This sends a request to all parents that asks them to scroll so
                            // that this item is brought into view.
                            bringIntoViewRequester.bringIntoView()
                        }
                    }
                }
                .focusTarget()
        )
    }
}

import androidx.compose.foundation.Canvas
import androidx.compose.foundation.border
import androidx.compose.foundation.horizontalScroll
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.relocation.BringIntoViewRequester
import androidx.compose.foundation.relocation.bringIntoViewRequester
import androidx.compose.foundation.rememberScrollState
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Modifier
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.geometry.Rect
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp

with(LocalDensity.current) {
    val bringIntoViewRequester = remember { BringIntoViewRequester() }
    val coroutineScope = rememberCoroutineScope()
    Column {
        Box(
            Modifier.border(2.dp, Color.Black)
                .size(500f.toDp())
                .horizontalScroll(rememberScrollState())
        ) {
            Canvas(
                Modifier.size(1500f.toDp(), 500f.toDp())
                    // This associates the RelocationRequester with a Composable that wants
                    // to be brought into view.
                    .bringIntoViewRequester(bringIntoViewRequester)
            ) {
                drawCircle(color = Color.Red, radius = 250f, center = Offset(750f, 250f))
            }
        }
        Button(
            onClick = {
                val circleCoordinates = Rect(500f, 0f, 1000f, 500f)
                coroutineScope.launch {
                    // This sends a request to all parents that asks them to scroll so that
                    // the circle is brought into view.
                    bringIntoViewRequester.bringIntoView(circleCoordinates)
                }
            }
        ) {
            Text("Bring circle into View")
        }
    }
}

fun DelegatableNode.findNearestAncestor(key: Any?): TraversableNode?

Finds the nearest traversable ancestor with a matching key.

fun DelegatableNode.traverseAncestors(
    key: Any?,
    block: (TraversableNode) -> Boolean
): Unit

Executes block for all ancestors with a matching key.

Note: The parameter block's return boolean value will determine if the traversal will continue (true = continue, false = cancel).

import androidx.compose.ui.Modifier
import androidx.compose.ui.node.traverseAncestors

val customTraversableModifierNode = CustomTraversableModifierNode()

with(customTraversableModifierNode) {
    traverseAncestors(traverseKey) {
        if (it is CustomTraversableModifierNode) {
            it.doSomethingWithAncestor()
        }
        // Return true to continue searching the tree after a match. If you were looking to
        // match only some of the nodes, you could return false and stop executing the search.
        true
    }
}

fun DelegatableNode.traverseChildren(
    key: Any?,
    block: (TraversableNode) -> Boolean
): Unit

Executes block for all direct children of the node with a matching key.

Note 1: This stops at the children and does not include grandchildren and so on down the tree.

Note 2: The parameter block's return boolean value will determine if the traversal will continue (true = continue, false = cancel).

import androidx.compose.ui.Modifier
import androidx.compose.ui.node.traverseChildren

val customTraversableModifierNode = CustomTraversableModifierNode()

with(customTraversableModifierNode) {
    traverseChildren(traverseKey) {
        if (it is CustomTraversableModifierNode) {
            it.doSomethingWithChild()
        }
        // Return true to continue searching the tree after a match. If you were looking to
        // match only some of the nodes, you could return false and stop executing the search.
        true
    }
}

fun DelegatableNode.traverseDescendants(
    key: Any?,
    block: (TraversableNode) -> TraversableNode.Companion.TraverseDescendantsAction
): Unit

Conditionally executes block for each descendant with a matching key.

Note 1: For nodes that do not have the same key, it will continue to execute the block for descendants below that non-matching node (where there may be a node that matches).

Note 2: The parameter block's return value TraverseDescendantsAction will determine the next step in the traversal.

import androidx.compose.ui.Modifier
import androidx.compose.ui.node.TraversableNode.Companion.TraverseDescendantsAction
import androidx.compose.ui.node.traverseDescendants

val customTraversableModifierNode = CustomTraversableModifierNode()

with(customTraversableModifierNode) {
    traverseDescendants(traverseKey) {
        if (it is CustomTraversableModifierNode) {
            it.doSomethingWithDescendant()
        }

        // [traverseDescendants()] actually has three options:
        // - ContinueTraversal
        // - SkipSubtreeAndContinueTraversal - rarely used
        // - CancelTraversal
        // They are pretty self explanatory. Usually, you just want to continue or cancel the
        // search. In some rare cases, you might want to skip the subtree but continue searching
        // the tree.
        TraverseDescendantsAction.ContinueTraversal
    }
}