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

androidx.compose.ui.node

Interfaces

CompositionLocalConsumerModifierNode

Implementing this interface allows your Modifier.Node subclass to read CompositionLocals via the currentValueOf function.

Cmn
DelegatableNode

Represents a Modifier.Node which can be a delegate of another Modifier.Node.

Cmn
DrawModifierNode

A Modifier.Node that draws into the space of the layout.

Cmn
GlobalPositionAwareModifierNode

A androidx.compose.ui.Modifier.Node whose onGloballyPositioned is called with the final LayoutCoordinates of the Layout when the global position of the content may have changed.

Cmn
InteroperableComposeUiNode

This interface allows the layout inspector to access inspect instances of Views that are associated with a Compose UI node.

Cmn
LayoutAwareModifierNode

A androidx.compose.ui.Modifier.Node which receives various callbacks in response to local changes in layout.

Cmn
LayoutModifierNode

A Modifier.Node that changes how its wrapped content is measured and laid out.

Cmn
ObserverModifierNode

Modifier.Nodes that implement ObserverNode can provide their own implementation of onObservedReadsChanged that will be called whenever the value of read object has changed.

Cmn
ParentDataModifierNode

A Modifier.Node that provides data to the parent Layout.

Cmn
PointerInputModifierNode

A androidx.compose.ui.Modifier.Node that receives PointerInputChanges, interprets them, and consumes the aspects of the changes that it is react to such that other PointerInputModifierNodes don't also react to them.

Cmn
RootForTest

The marker interface to be implemented by the root backing the composition.

Cmn
SemanticsModifierNode

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

Cmn

Classes

DelegatingNode

A Modifier.Node which is able to delegate work to other Modifier.Node instances.

Cmn
ModifierNodeElement

A Modifier.Element which manages an instance of a particular Modifier.Node implementation.

Cmn
Ref

Value holder general purpose class.

Cmn

Annotations

InternalCoreApi
Cmn

Extension functions summary

T

Returns the current value of local at the position in the composition hierarchy of this modifier's attached layout node.

Cmn
Unit

Invalidates this modifier's draw layer, ensuring that a draw pass will be run on the next frame.

Cmn
Unit

This will invalidate the current node's layer, and ensure that the layer is redrawn for the next frame.

Cmn
Unit

This invalidates the current node's measure result, and ensures that a re-measurement (the measurement block rerun) of this node will happen for the next frame.

Cmn
Unit

This invalidates the current node's parent data, and ensures that layouts that utilize it will be scheduled to relayout for the next frame.

Cmn
Unit

This will invalidate the current node's placement result, and ensure that relayout (the placement block rerun) of this node will happen for the next frame .

Cmn
Unit
Cmn
Unit

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

Cmn
Unit

Use this function to observe reads within the specified block.

Cmn
Unit

Performs the node remeasuring synchronously even if the node was not marked as needs remeasure before.

Cmn
Density

Returns the current Density of the LayoutNode that this DelegatableNode is attached to.

Cmn
LayoutDirection

Returns the current LayoutDirection of the LayoutNode that this DelegatableNode is attached to.

Cmn

Extension functions

currentValueOf

fun <T : Any?> CompositionLocalConsumerModifierNode.currentValueOf(
    local: CompositionLocal<T>
): T

Returns the current value of local at the position in the composition hierarchy of this modifier's attached layout node.

Unlike CompositionLocal.current, reads via this function are not automatically tracked by Compose. Modifiers are not able to recompose in the same way that a Composable can, and therefore can't receive updates arbitrarily for a CompositionLocal.

Because CompositionLocals may change arbitrarily, it is strongly recommended to ensure that the composition local is observed instead of being read once. If you call currentValueOf inside of a modifier callback like LayoutModifierNode.measure or DrawModifierNode.draw, then Compose will track the CompositionLocal read. This happens automatically, because these Compose UI phases take place in a snapshot observer that tracks which states are read. If the value of the CompositionLocal changes, and it was read inside of the measure or draw phase, then that phase will automatically be invalidated.

For all other reads of a CompositionLocal, this function will not notify you when the value of the local changes. Modifier.Node classes that also implement ObserverModifierNode may observe CompositionLocals arbitrarily by performing the lookup in an observeReads block. To continue observing values of the CompositionLocal, it must be read again in an observeReads block during or after the ObserverModifierNode.onObservedReadsChanged callback is invoked. See below for an example of how to implement this observation pattern.

import androidx.compose.runtime.compositionLocalOf
import androidx.compose.ui.Modifier
import androidx.compose.ui.node.CompositionLocalConsumerModifierNode
import androidx.compose.ui.node.ObserverModifierNode
import androidx.compose.ui.node.currentValueOf
import androidx.compose.ui.node.observeReads

val LocalValue = compositionLocalOf { "abc123" }
class ValueObserverModifierNode : Modifier.Node(),
    CompositionLocalConsumerModifierNode, ObserverModifierNode {
    private var observedValue: String? = null
    override fun onAttach() {
        onObservedReadsChanged()
    }
    override fun onDetach() {
        observedValue = null
    }
    override fun onObservedReadsChanged() {
        observeReads {
            observedValue = currentValueOf(LocalValue)
            // Do something with the new value
        }
    }
}

This function will fail with an IllegalStateException if you attempt to read a CompositionLocal before the node is attached or after the node is detached.

Parameters
local: CompositionLocal<T>

The CompositionLocal to get the current value of

Returns
T

The value provided by the nearest CompositionLocalProvider component that invokes, directly or indirectly, the composable function that this modifier is attached to. If local was never provided, its default value will be returned instead.

invalidateDraw

fun DrawModifierNode.invalidateDraw(): Unit

Invalidates this modifier's draw layer, ensuring that a draw pass will be run on the next frame.

invalidateLayer

fun LayoutModifierNode.invalidateLayer(): Unit

This will invalidate the current node's layer, and ensure that the layer is redrawn for the next frame.

invalidateMeasurement

fun LayoutModifierNode.invalidateMeasurement(): Unit

This invalidates the current node's measure result, and ensures that a re-measurement (the measurement block rerun) of this node will happen for the next frame.

invalidateParentData

fun ParentDataModifierNode.invalidateParentData(): Unit

This invalidates the current node's parent data, and ensures that layouts that utilize it will be scheduled to relayout for the next frame.

invalidatePlacement

fun LayoutModifierNode.invalidatePlacement(): Unit

This will invalidate the current node's placement result, and ensure that relayout (the placement block rerun) of this node will happen for the next frame .

invalidateSemantics

fun SemanticsModifierNode.invalidateSemantics(): Unit

invalidateSubtree

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.

observeReads

fun <T : Modifier.Node & ObserverModifierNode> T.observeReads(block: () -> Unit): Unit

Use this function to observe reads within the specified block.

remeasureSync

fun LayoutModifierNode.remeasureSync(): Unit

Performs the node remeasuring synchronously even if the node was not marked as needs remeasure before. Useful for cases like when during scrolling you need to re-execute the measure block to consume the scroll offset and remeasure your children in a blocking way.

requireDensity

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.

requireLayoutDirection

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.