androidx.navigation3.runtime

Interfaces

NavKey

Marker interface for keys.
Cmn

Classes

EntryClassProvider

Holds a Entry class, metadata, and content for that class
Cmn
EntryProvider

Holds a Entry class, metadata, and content for that key
Cmn
EntryProviderBuilder

DSL for constructing a new NavEntry
Cmn
NavEntry

Entry maintains and stores the key and the content represented by that key.
Cmn
NavEntryDecorator

Marker class to hold the onPop and decorator functions that will be invoked at runtime.
Cmn
NavEntryWrapper

Class that wraps a NavEntry within another NavEntry.
Cmn

Annotations

EntryDsl
Cmn

Type aliases

NavBackStack

A List of objects that extend the NavKey marker class.
android

Top-level functions summary

Unit
@Composable
<T : Any> DecorateNavEntry(
    entry: NavEntry<T>,
    entryDecorators: List<NavEntryDecorator<*>>
)

Wraps a NavEntry with the list of NavEntryDecorator in the order that the decorators were added to the list and invokes the content of the wrapped entry.
Cmn
Unit
@Composable
<T : Any> DecoratedNavEntryProvider(
    backStack: List<T>,
    entryProvider: (key) -> NavEntry<T>,
    entryDecorators: List<NavEntryDecorator<*>>,
    content: @Composable (List<NavEntry<T>>) -> Unit
)

Function that provides all of the NavEntrys wrapped with the given NavEntryDecorators.
Cmn
NavEntryDecorator<Any>

Wraps the content of a NavEntry with a SaveableStateHolder.SaveableStateProvider to ensure that calls to rememberSaveable within the content work properly and that state can be saved.
Cmn
inline (T) -> NavEntry<T>
<T : Any> entryProvider(
    noinline fallback: (unknownScreen) -> NavEntry<T>,
    builder: EntryProviderBuilder<T>.() -> Unit
)

Creates an EntryProviderBuilder with the entry providers provided in the builder.
Cmn
NavEntryDecorator<T>
<T : Any> navEntryDecorator(
    onPop: (contentKey: Any) -> Unit,
    decorator: @Composable (entry: NavEntry<T>) -> Unit
)

Function to decorate the NavEntry that are integrated with a DecoratedNavEntryProvider.
Cmn
SnapshotStateList<NavKey>
@Composable
<T : NavKey> rememberNavBackStack(vararg elements: T)

Provides a NavBackStack that is automatically remembered in the Compose hierarchy across process death and config changes.
android
NavEntryDecorator<Any>

Returns a SavedStateNavEntryDecorator that is remembered across recompositions.
Cmn

Extension functions summary

inline Unit
<T : Any> EntryProviderBuilder<*>.entry(
    noinline clazzContentKey: (key) -> Any,
    metadata: Map<String, Any>,
    noinline content: @Composable (T) -> Unit
)

Add an entry provider to the EntryProviderBuilder
Cmn
Unit
<T : Any> EntryProviderBuilder<T>.entry(
    key: T,
    contentKey: Any,
    metadata: Map<String, Any>,
    content: @Composable (T) -> Unit
)

Add an entry provider to the EntryProviderBuilder
Cmn

Top-level functions

DecorateNavEntry

Cmn 
@Composable
fun <T : Any> DecorateNavEntry(
    entry: NavEntry<T>,
    entryDecorators: List<NavEntryDecorator<*>>
): Unit

Wraps a NavEntry with the list of NavEntryDecorator in the order that the decorators were added to the list and invokes the content of the wrapped entry.

Parameters
<T : Any>

the type of the backStack key
entry: NavEntry<T>

the NavEntry to wrap
entryDecorators: List<NavEntryDecorator<*>>

the list of decorators to wrap the entry with

DecoratedNavEntryProvider

Cmn 
@Composable
fun <T : Any> DecoratedNavEntryProvider(
    backStack: List<T>,
    entryProvider: (key) -> NavEntry<T>,
    entryDecorators: List<NavEntryDecorator<*>> = listOf(rememberSavedStateNavEntryDecorator()),
    content: @Composable (List<NavEntry<T>>) -> Unit
): Unit

Function that provides all of the NavEntrys wrapped with the given NavEntryDecorators. It is responsible for executing the functions provided by each NavEntryDecorator appropriately.

Note: the order in which the NavEntryDecorators are added to the list determines their scope, i.e. a NavEntryDecorator added earlier in a list has its data available to those added later.

Parameters
<T : Any>

the type of the backStack key
backStack: List<T>

the list of keys that represent the backstack
entryProvider: (key) -> NavEntry<T>

a function that returns the NavEntry for a given key
entryDecorators: List<NavEntryDecorator<*>> = listOf(rememberSavedStateNavEntryDecorator())

the NavEntryDecorators that are providing data to the content
content: @Composable (List<NavEntry<T>>) -> Unit

the content to be displayed

SavedStateNavEntryDecorator

Cmn 
fun SavedStateNavEntryDecorator(saveableStateHolder: SaveableStateHolder): NavEntryDecorator<Any>

Wraps the content of a NavEntry with a SaveableStateHolder.SaveableStateProvider to ensure that calls to rememberSaveable within the content work properly and that state can be saved. Also provides the content of a NavEntry with a SavedStateRegistryOwner which can be accessed in the content with LocalSavedStateRegistryOwner.

This NavEntryDecorator is the only one that is required as saving state is considered a non-optional feature.

Parameters
saveableStateHolder: SaveableStateHolder

the SaveableStateHolder that holds the state defined with rememberSaveable. A saved state can only be restored from the SaveableStateHolder that it was saved with.

entryProvider

Cmn 
inline fun <T : Any> entryProvider(
    noinline fallback: (unknownScreen) -> NavEntry<T> = {
        throw IllegalStateException("Unknown screen $it")
    },
    builder: EntryProviderBuilder<T>.() -> Unit
): (T) -> NavEntry<T>

Creates an EntryProviderBuilder with the entry providers provided in the builder.

Parameters
<T : Any>

the type of the NavEntry key
noinline fallback: (unknownScreen) -> NavEntry<T> = { throw IllegalStateException("Unknown screen $it") }

the fallback NavEntry when the provider cannot find an entry associated with a given key on the backStack
builder: EntryProviderBuilder<T>.() -> Unit

the EntryProviderBuilder DSL extension that builds NavEntries for the provider
Cmn 
fun <T : Any> navEntryDecorator(
    onPop: (contentKey: Any) -> Unit = {},
    decorator: @Composable (entry: NavEntry<T>) -> Unit
): NavEntryDecorator<T>

Function to decorate the NavEntry that are integrated with a DecoratedNavEntryProvider.

Primary usages include but are not limited to:

  1. provide information to entries with androidx.compose.runtime.CompositionLocal, i.e.

val decorator = navEntryDecorator<Any> { entry ->
   ...
   CompositionLocalProvider(LocalMyStateProvider provides myState) {
       entry.content.invoke(entry.key)
   }
}

  1. Wrap entry content with other composable content

val decorator = navEntryDecorator<Any> { entry ->
   ...
   MyComposableFunction {
       entry.content.invoke(entry.key)
   }
}
Parameters
<T : Any>

the type of the backStack key
onPop: (contentKey: Any) -> Unit = {}

the callback to clean up the decorator state for a NavEntry when the entry is popped from the backstack and is leaving composition.The lambda provides the NavEntry.key of the popped entry as input.
decorator: @Composable (entry: NavEntry<T>) -> Unit

the composable function to decorate a NavEntry. Note that this function only gets invoked for NavEntries that are actually getting rendered (i.e. by invoking the NavEntry.content.)

rememberNavBackStack

android 
@Composable
fun <T : NavKey> rememberNavBackStack(vararg elements: T): SnapshotStateList<NavKey>

Provides a NavBackStack that is automatically remembered in the Compose hierarchy across process death and config changes.

Classes/objects added to the NavBackStack should be annotated with Serializable to ensure they can be saved and restored properly.

Parameters
vararg elements: T

the starting keys of this backStack

rememberSavedStateNavEntryDecorator

Cmn 
@Composable
fun rememberSavedStateNavEntryDecorator(
    saveableStateHolder: SaveableStateHolder = rememberSaveableStateHolder()
): NavEntryDecorator<Any>

Returns a SavedStateNavEntryDecorator that is remembered across recompositions.

Parameters
saveableStateHolder: SaveableStateHolder = rememberSaveableStateHolder()

the SaveableStateHolder that scopes the returned NavEntryDecorator

Extension functions

entry

Cmn 
inline fun <T : Any> EntryProviderBuilder<*>.entry(
    noinline clazzContentKey: (key) -> Any = { defaultContentKey(it) },
    metadata: Map<String, Any> = emptyMap(),
    noinline content: @Composable (T) -> Unit
): Unit

Add an entry provider to the EntryProviderBuilder

Parameters
<T : Any>

the type of the key for this NavEntry
noinline clazzContentKey: (key) -> Any = { defaultContentKey(it) }

A factory of unique, stable ids that uniquely identifies the content of this NavEntry. To maximize stability, it should ge derived from the factory's provided key. The resulting key must be saveable (i.e. on Android, it should be saveable via Android). The generated key will be stored in NavEntry.contentKey.
metadata: Map<String, Any> = emptyMap()

provides information to the display
noinline content: @Composable (T) -> Unit

content for this entry to be displayed when this entry is active

entry

Cmn 
fun <T : Any> EntryProviderBuilder<T>.entry(
    key: T,
    contentKey: Any = defaultContentKey(key),
    metadata: Map<String, Any> = emptyMap(),
    content: @Composable (T) -> Unit
): Unit

Add an entry provider to the EntryProviderBuilder

Parameters
<T : Any>

the type of the key for this NavEntry
key: T

key for this entry
contentKey: Any = defaultContentKey(key)

A unique, stable id that uniquely identifies the content of this NavEntry. To maximize stability, it should ge derived from the key. The contentKey type must be saveable (i.e. on Android, it should be saveable via Android). Defaults to key.toString().
metadata: Map<String, Any> = emptyMap()

provides information to the display
content: @Composable (T) -> Unit

content for this entry to be displayed when this entry is active