ProvidableCompositionLocal


A ProvidableCompositionLocal can be used in CompositionLocalProvider to provide values.

Summary

Public functions

infix ProvidedValue<T>
provides(value: T)

Associates a CompositionLocal key to a value in a call to CompositionLocalProvider.

Cmn
infix ProvidedValue<T>

Associates a CompositionLocal key to a lambda, compute, in a call to CompositionLocal.

Cmn
infix ProvidedValue<T>
providesDefault(value: T)

Associates a CompositionLocal key to a value in a call to CompositionLocalProvider if the key does not already have an associated value.

Cmn

Inherited properties

From androidx.compose.runtime.CompositionLocal
T

Return the value provided by the nearest CompositionLocalProvider component that invokes, directly or indirectly, the composable function that uses this property.

Cmn

Public functions

provides

infix fun provides(value: T): ProvidedValue<T>

Associates a CompositionLocal key to a value in a call to CompositionLocalProvider.

providesComputed

infix fun providesComputed(compute: CompositionLocalAccessorScope.() -> T): ProvidedValue<T>

Associates a CompositionLocal key to a lambda, compute, in a call to CompositionLocal. The compute lambda is invoked whenever the key is retrieved. The lambda is executed in the context of a CompositionLocalContext which allow retrieving the current values of other composition locals by calling CompositionLocalAccessorScope.currentValue, which is an extension function provided by the context for a CompositionLocal key.

The lambda passed to providesComputed will be invoked every time the CompositionLocal.current is evaluated for the composition local and computes its value based on the current value of the locals referenced in the lambda at the time CompositionLocal.current is evaluated. This allows providing values that can be derived from other locals. For example, if accent colors can be calculated from a single base color, the accent colors can be provided as computed composition locals. Providing a new base color would automatically update all the accent colors.

import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.compositionLocalOf

val LocalValue = compositionLocalOf { 10 }
val LocalLargerValue = compositionLocalOf { 12 }

@Composable
fun App() {
    CompositionLocalProvider(
        LocalLargerValue providesComputed { LocalValue.currentValue + 10 }
    ) {
        SomeScreen()
    }
}
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.compositionLocalOf
import androidx.compose.runtime.compositionLocalWithComputedDefaultOf

val LocalValue = compositionLocalOf { 10 }
val LocalLargerValue = compositionLocalOf { 12 }
val LocalComputedValue = compositionLocalWithComputedDefaultOf { LocalValue.currentValue + 4 }

// In this example `LocalLargerValue` needs to be re-provided
// whenever `LocalValue` is provided to keep its value larger
// then `LocalValue`. However, `LocalComputedValue` does not
// need to be re-provided to stay larger than `LocalValue` as
// it is calculated based on the currently provided value for
// `LocalValue`. Whenever `LocalValue` is provided the value
// of `LocalComputedValue` is computed based on the currently
// provided value for `LocalValue`.

@Composable
fun App() {
    // Value is 10, the default value for LocalValue
    val value = LocalValue.current
    // Value is 12, the default value
    val largerValue = LocalLargerValue.current
    // Value is computed to be 14
    val computedValue = LocalComputedValue.current
    CompositionLocalProvider(LocalValue provides 20) {
        // Value is 20 provided above
        val nestedValue = LocalValue.current
        // Value is still 12 as an updated value was not re-provided
        val nestedLargerValue = LocalLargerValue.current
        // Values is computed to be 24; LocalValue.current + 4
        val nestedComputedValue = LocalComputedValue.current
        CompositionLocalProvider(LocalLargerValue provides LocalValue.current + 2) {
            // Value is 22 provided above
            val newLargerValue = LocalLargerValue.current

            CompositionLocalProvider(LocalValue provides 50) {
                // Value is now 50 provided above
                val finalValue = LocalValue.current
                // Value is still 22
                val finalLargerValue = LocalLargerValue.current
                // Value is now computed to be 54
                val finalComputed = LocalComputedValue.current
            }
        }
    }
}

providesDefault

infix fun providesDefault(value: T): ProvidedValue<T>

Associates a CompositionLocal key to a value in a call to CompositionLocalProvider if the key does not already have an associated value.