public final class StateStore

Class that contains a store that maintains compose state beyond individual Android components.

There is no limitation on where these instance should be instantiated as that is left up to the developer.

Summary

Public constructors

Public methods
final @NonNull Set<@NonNull StateStoreKey<@NonNull ?>>

The set of keys that are currently added to this StateStore.
final @NonNull State<@NonNull T>
<T extends Object> getState(
    @NonNull StateStoreKey<@NonNull T> stateKey,
    @NonNull T defaultValue
)

Returns the state associated with the given key.
final void
<T extends Object> setState(
    @NonNull StateStoreKey<@NonNull T> stateKey,
    @NonNull T value
)

Sets the state for the given key.
final void
<T extends Object> updateState(
    @NonNull StateStoreKey<@NonNull T> stateKey,
    @NonNull T defaultValue,
    @NonNull Function1<@NonNull T, @NonNull T> update
)

Retrieves the current state and uses that with the update lambda to set a new state for the specified key.

Extension functions
final void

Tracks changes to StateStore and syncs keys implementing PersistToDataStore to DataStore.
final void
StateStoreKt.syncToDataStore(
    @NonNull StateStore receiver,
    @NonNull String path,
    @NonNull CoroutineScope coroutineScope
)

Tracks changes to StateStore and persists keys implementing PersistToDataStore to a DataStore backed by a file.

Public constructors

StateStore

Added in 1.0.0-alpha01
public StateStore()

Public methods

getKeys

Added in 1.0.0-alpha01
public final @NonNull Set<@NonNull StateStoreKey<@NonNull ?>> getKeys()

The set of keys that are currently added to this StateStore.

This can be used in conjunction with the androidx.stateStore.transform APIs to provide a mechanism for reacting to state changes.

val scope = CoroutineScope(context + SupervisorJob())
val job = scope.launch {
    listen {
        val keys = stateStore.keys
        // Do some processing of the keys
    }
}

getState

Added in 1.0.0-alpha01
public final @NonNull State<@NonNull T> <T extends Object> getState(
    @NonNull StateStoreKey<@NonNull T> stateKey,
    @NonNull T defaultValue
)

Returns the state associated with the given key.

Parameters
@NonNull StateStoreKey<@NonNull T> stateKey

the key of the state to retrieve
@NonNull T defaultValue

the value to put if there is no value for the key

setState

Added in 1.0.0-alpha01
public final void <T extends Object> setState(
    @NonNull StateStoreKey<@NonNull T> stateKey,
    @NonNull T value
)

Sets the state for the given key.

If this is the first time the state is being set a listener is added to allow the given key to be automatically cleared from the map based on the StateStoreKey.autoClearKey and StateStoreKey.shouldClearState. For the automatic clearing, StateStoreKey.autoClearKey must be non-null, the value associated with this key must be non-null, and the StateStoreKey.shouldClearState condition must return true. AS long as all 3 of those conditions are not met, the listener will not be removed.

Parameters
@NonNull StateStoreKey<@NonNull T> stateKey

the key to set a value for
@NonNull T value

the value to set inside the StateStore

updateState

Added in 1.0.0-alpha01
public final void <T extends Object> updateState(
    @NonNull StateStoreKey<@NonNull T> stateKey,
    @NonNull T defaultValue,
    @NonNull Function1<@NonNull T, @NonNull T> update
)

Retrieves the current state and uses that with the update lambda to set a new state for the specified key.

Parameters
@NonNull StateStoreKey<@NonNull T> stateKey

the key to update
@NonNull T defaultValue

the value to use if no state has been set for the key
@NonNull Function1<@NonNull T, @NonNull T> update

lambda used to update the state using the current state

Extension functions

StateStoreKt.syncToDataStore

public final void StateStoreKt.syncToDataStore(
    @NonNull StateStore receiver,
    @NonNull DataStore<@NonNull StateStorePreferences> dataStore
)

Tracks changes to StateStore and syncs keys implementing PersistToDataStore to DataStore.

Keys must implement PersistToDataStore to be saved.

import androidx.appstate.datastore.syncToDataStore
import androidx.appstate.statestore.StateStore
import androidx.datastore.core.DataStore

val stateStore = StateStore()

// Register the key by getting the state
val state = stateStore.getState(SampleKey)

stateStore.syncToDataStore(dataStore)
Parameters
@NonNull DataStore<@NonNull StateStorePreferences> dataStore

the DataStore used to save and restore state

StateStoreKt.syncToDataStore

public final void StateStoreKt.syncToDataStore(
    @NonNull StateStore receiver,
    @NonNull String path,
    @NonNull CoroutineScope coroutineScope
)

Tracks changes to StateStore and persists keys implementing PersistToDataStore to a DataStore backed by a file.

Keys must implement PersistToDataStore to be saved.

import androidx.appstate.datastore.syncToDataStore
import androidx.appstate.statestore.StateStore
import androidx.datastore.core.DataStore

val stateStore = StateStore()

// Register the key by getting the state
val state = stateStore.getState(SampleKey)

// The path must include the directory, for example, on Android:
// val path = context.filesDir.resolve("stateStore.preferences_pb").absolutePath
val path = "/path/to/directory/stateStore.preferences_pb"

stateStore.syncToDataStore(path, CoroutineScope(Dispatchers.IO))
Parameters
@NonNull String path

the file path to save and restore state from
@NonNull CoroutineScope coroutineScope

the CoroutineScope used for the DataStore