androidx.compose.ui.modifier

Interfaces

ModifierLocalConsumer

A Modifier that can be used to consume ModifierLocals that were provided by other modifiers to the left of this modifier, or above this modifier in the layout tree.
Cmn
ModifierLocalModifierNode

A androidx.compose.ui.Modifier.Node that is capable of consuming and providing ModifierLocal values.
Cmn
ModifierLocalProvider

A Modifier that can be used to provide ModifierLocals that can be read by other modifiers to the right of this modifier, or modifiers that are children of the layout node that this modifier is attached to.
Cmn
ModifierLocalReadScope

This scope gives us access to modifier locals that are provided by other modifiers to the left of this modifier, or above this modifier in the layout tree.
Cmn

Classes

ModifierLocal

ModifierLocals provide a means of inter-modifier communication.
Cmn
ModifierLocalMap

An opaque key-value holder of ModifierLocals to be used with ModifierLocalModifierNode.
Cmn
ProvidableModifierLocal

ProvidableModifierLocals are ModifierLocals that can be used to provide values using a ModifierLocalProvider.
Cmn

Top-level functions summary

ModifierLocalMap

Creates an empty ModifierLocalMap
Cmn
ModifierLocalMap
<T : Any?> modifierLocalMapOf(entry: Pair<ModifierLocal<T>, T>)

Creates a ModifierLocalMap with a single key and value.
Cmn
ModifierLocalMap

Creates a ModifierLocalMap with a single key and value initialized to null.
Cmn
ModifierLocalMap
modifierLocalMapOf(
    entry1: Pair<ModifierLocal<*>, Any>,
    entry2: Pair<ModifierLocal<*>, Any>,
    vararg entries: Pair<ModifierLocal<*>, Any>
)

Creates a ModifierLocalMap with multiple keys and values.
Cmn
ModifierLocalMap
modifierLocalMapOf(
    key1: ModifierLocal<*>,
    key2: ModifierLocal<*>,
    vararg keys: ModifierLocal<*>
)

Creates a ModifierLocalMap with several keys, all initialized with values of null
Cmn
ProvidableModifierLocal<T>
<T : Any?> modifierLocalOf(defaultFactory: () -> T)

Creates a ProvidableModifierLocal and specifies a default factory.
Cmn

Extension functions summary

Modifier

A Modifier that can be used to consume ModifierLocals that were provided by other modifiers to the left of this modifier, or above this modifier in the layout tree.
Cmn
Modifier
<T : Any?> Modifier.modifierLocalProvider(
    key: ProvidableModifierLocal<T>,
    value: () -> T
)

A Modifier that can be used to provide ModifierLocals that can be read by other modifiers to the right of this modifier, or modifiers that are children of the layout node that this modifier is attached to.
Cmn

Top-level functions

modifierLocalMapOf

Cmn 
fun modifierLocalMapOf(): ModifierLocalMap

Creates an empty ModifierLocalMap

modifierLocalMapOf

Cmn 
fun <T : Any?> modifierLocalMapOf(entry: Pair<ModifierLocal<T>, T>): ModifierLocalMap

Creates a ModifierLocalMap with a single key and value. The provided entry should have Pair::first be the ModifierLocal key, and the Pair::second be the corresponding value.

modifierLocalMapOf

Cmn 
fun <T : Any?> modifierLocalMapOf(key: ModifierLocal<T>): ModifierLocalMap

Creates a ModifierLocalMap with a single key and value initialized to null.

modifierLocalMapOf

Cmn 
fun modifierLocalMapOf(
    entry1: Pair<ModifierLocal<*>, Any>,
    entry2: Pair<ModifierLocal<*>, Any>,
    vararg entries: Pair<ModifierLocal<*>, Any>
): ModifierLocalMap

Creates a ModifierLocalMap with multiple keys and values. The provided entries should have each item's Pair::first be the ModifierLocal key, and the Pair::second be the corresponding value.

modifierLocalMapOf

Cmn 
fun modifierLocalMapOf(
    key1: ModifierLocal<*>,
    key2: ModifierLocal<*>,
    vararg keys: ModifierLocal<*>
): ModifierLocalMap

Creates a ModifierLocalMap with several keys, all initialized with values of null

modifierLocalOf

Cmn 
fun <T : Any?> modifierLocalOf(defaultFactory: () -> T): ProvidableModifierLocal<T>

Creates a ProvidableModifierLocal and specifies a default factory.

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.composed
import androidx.compose.ui.modifier.modifierLocalConsumer
import androidx.compose.ui.modifier.modifierLocalOf
import androidx.compose.ui.modifier.modifierLocalProvider

// Define the type of data.
val ModifierLocalMessage = modifierLocalOf { "Unknown" }

Box(
    Modifier
        // Provide an instance associated with the data type.
        .modifierLocalProvider(ModifierLocalMessage) { "World" }
        .composed {
            var message by remember { mutableStateOf("") }
            Modifier
                // Use the data type to read the message.
                .modifierLocalConsumer { message = ModifierLocalMessage.current }
                .clickable { println("Hello $message") }
        }
)

Sample 2: Modifier sending a message to another to its left.

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.composed
import androidx.compose.ui.modifier.modifierLocalConsumer
import androidx.compose.ui.modifier.modifierLocalOf
import androidx.compose.ui.modifier.modifierLocalProvider

class Sender(val onMessageReceived: (String) -> Unit) {
    fun sendMessage(message: String) {
        onMessageReceived(message)
    }
}

// Define the type of data.
val ModifierLocalSender = modifierLocalOf<Sender> { error("No sender provided by parent.") }

Box(
    Modifier
        // Provide an instance associated with the sender type.
        .modifierLocalProvider(ModifierLocalSender) {
            Sender { println("Message Received: $it") }
        }
        .composed {
            var sender by remember { mutableStateOf<Sender?>(null) }
            Modifier
                // Use the sender type to fetch an instance.
                .modifierLocalConsumer { sender = ModifierLocalSender.current }
                // Use this instance to send a message to the parent.
                .clickable { sender?.sendMessage("Hello World") }
        }
)

Here are examples where a modifier can communicate with another across layout nodes:

Sample 1: Modifier sending a message to a modifier on a child layout node.

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.modifier.modifierLocalConsumer
import androidx.compose.ui.modifier.modifierLocalOf
import androidx.compose.ui.modifier.modifierLocalProvider

// Define the type of data.
val ModifierLocalMessage = modifierLocalOf { "Unknown" }

Box(
    // Provide an instance associated with the data type.
    Modifier.modifierLocalProvider(ModifierLocalMessage) { "World" }
) {
    var message by remember { mutableStateOf("") }
    Box(
        Modifier
            // Use the data type to read the message.
            .modifierLocalConsumer { message = ModifierLocalMessage.current }
            .clickable { println("Hello $message") }
    )
}

Sample 2: Modifier sending a message to a modifier on a parent layout node.

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.modifier.modifierLocalConsumer
import androidx.compose.ui.modifier.modifierLocalOf
import androidx.compose.ui.modifier.modifierLocalProvider

class Sender(val onMessageReceived: (String) -> Unit) {
    fun sendMessage(message: String) {
        onMessageReceived(message)
    }
}

// Define the type of data.
val ModifierLocalSender = modifierLocalOf<Sender> { error("No sender provided by parent.") }

Box(
    Modifier
        // Provide an instance associated with the sender type.
        .modifierLocalProvider(ModifierLocalSender) {
            Sender { println("Message Received: $it") }
        }
) {
    var sender by remember { mutableStateOf<Sender?>(null) }
    Box(
        Modifier
            // Use the sender type to fetch an instance.
            .modifierLocalConsumer { sender = ModifierLocalSender.current }
            // Use this instance to send a message to the parent.
            .clickable { sender?.sendMessage("Hello World") }
    )
}
Parameters
defaultFactory: () -> T

a factory to create a default value in cases where a ModifierLocal is consumed without a Provider. If this is a situation you would rather not handle, you can throw an error in this factory.

Here are examples where a modifier can communicate with another in the same modifier chain:

Sample 1: Modifier sending a message to another to its right.
See also
ProvidableModifierLocal
ModifierLocal
modifierLocalProvider
modifierLocalConsumer

Extension functions

modifierLocalConsumer

Cmn 
fun Modifier.modifierLocalConsumer(consumer: ModifierLocalReadScope.() -> Unit): Modifier

A Modifier that can be used to consume ModifierLocals that were provided by other modifiers to the left of this modifier, or above this modifier in the layout tree.

modifierLocalProvider

Cmn 
fun <T : Any?> Modifier.modifierLocalProvider(
    key: ProvidableModifierLocal<T>,
    value: () -> T
): Modifier

A Modifier that can be used to provide ModifierLocals that can be read by other modifiers to the right of this modifier, or modifiers that are children of the layout node that this modifier is attached to.