DecoratedNavEntriesKt
public final class DecoratedNavEntriesKt
Summary
Public methods |
|
|---|---|
static final @NonNull List<@NonNull NavEntry<@NonNull T>> |
@ComposableDecorates the |
static final @NonNull List<@NonNull NavEntry<@NonNull T>> |
@ComposableRemembers and returns a list of |
Public methods
rememberDecoratedNavEntries
@Composable
public static final @NonNull List<@NonNull NavEntry<@NonNull T>> <T extends Object> rememberDecoratedNavEntries(
@NonNull List<@NonNull NavEntry<@NonNull T>> entries,
@NonNull List<@NonNull NavEntryDecorator<@NonNull T>> entryDecorators
)
Decorates the entries with the entryDecorators and returns the list of decorated NavEntries.
WHEN TO USE This API can be used to decorate undecorated NavEntry as well as entries that have already been decorated with other NavEntryDecorator.
HOW IT WORKS When you redecorate NavEntries with this function, the entryDecorators passed in here will be invoked first, followed by the original decorators that decorated the entries. For example
val originalDecorator = listOf(navEntryDecorator { println("original") })
val originalEntries = rememberDecoratedNavEntries(backStack, originalDecorator, ...)
val newDecorator = listOf(navEntryDecorator { println("additional") })
val newEntries = rememberDecoratedNavEntries(originalEntries, newDecorator)
// println output
additional
original| Parameters | |
|---|---|
<T extends Object> |
the type of the backStack key |
@NonNull List<@NonNull NavEntry<@NonNull T>> entries |
the list of NavEntry to decorate. If this list is observable, i.e. a |
@NonNull List<@NonNull NavEntryDecorator<@NonNull T>> entryDecorators |
the |
rememberDecoratedNavEntries
@Composable
public static final @NonNull List<@NonNull NavEntry<@NonNull T>> <T extends Object> rememberDecoratedNavEntries(
@NonNull List<@NonNull T> backStack,
@NonNull List<@NonNull NavEntryDecorator<@NonNull T>> entryDecorators,
@NonNull Function1<@NonNull key, @NonNull NavEntry<@NonNull T>> entryProvider
)
Remembers and returns a list of NavEntry decorated with the list of entryDecorators
The returned list of NavEntry survives configuration change and recompositions but does not survive process death. To ensure that the backStack and its states are recovered properly, the backStack and the entryDecorators's states passed into this function should be hoisted and saved across process death.
For example:
// backStack saved during process death
val backStack = rememberNavBackStack()
// the hoisted SaveableStateHolder used by the decorator is saved during process death
val decorators = listOf(rememberSavedStateNavEntryDecorator())
// finally, decorate the entries
val entries = rememberDecoratedNavEntries(backStack, decorators, entryProvider)HOW TO USE The returned list of entries should be stored and reused for the same backStack. If you want to support multiple backStacks (i.e. each bottom tab with their own backStack), then each backStack should be their own rememberDecoratedNavEntries with new backStack and entryDecorators passed in.
MUTABLE BACKSTACK NAVIGATE/POP The backStack should be a hoisted OBSERVABLE list, and navigates or pops should be applied directly to this backStack. For example:
val backStack = mutableStateListOf(A)
val entries = rememberDecoratedNavEntries(backStack, ...)
// to navigate
backStack.add(B)
// to pop
backStack.removeLastOrNull()
IMMUTABLE BACKSTACK NAVIGATE/POP This composable also supports navigates and pops with immutable backStack. Simply replace the previous backStack with a new one but DO NOT replace the decorator states. Also, DO NOT create a brand new rememberDecoratedNavEntries. For example
val backStack = mutableStateOf(listOf(1, 2))
val entries = rememberDecoratedNavEntries(backStack, ...)
// to navigate
backStack.value = listOf(1, 2, 3)
// to pop
backStack.value = listOf(1)
MULTIPLE BACKSTACKS Each call to rememberDecoratedNavEntries represents a single backStack. To support multiple backStack, there should be one rememberDecoratedNavEntries for each backStack. For example
val homeBackStack = mutableStateListOf(HomeKey)
val homeDecorators = mutableStateListOf(rememberSavedStateNavEntryDecorator(), ...)
val homeTabEntries = rememberDecoratedNavEntries(homeBackStack, homeDecorators, ...)
val favoritesBackStack = mutableStateListOf(FavoritesKey)
val favoritesDecorators = mutableStateListOf(rememberSavedStateNavEntryDecorator(),...)
val favoritesTabEntries = rememberDecoratedNavEntries(favoritesBackStack, favoritesDecorators, ...)
You can also concatenate multiple backStacks to form a larger one. So, given the above setup:
val concatenatedEntries = homeTabEntries + favoritesTabEntries
// To navigate within the favorites backStack
favoritesBackStack.add(FavoritesDetailKey)
In this case, the updated favoritesBackStack and updated states will be reflected in concatenatedEntries.
| Parameters | |
|---|---|
<T extends Object> |
the type of the backStack key |
@NonNull List<@NonNull T> backStack |
the list of keys that represent the backstack. If this backStack is observable, i.e. a |
@NonNull List<@NonNull NavEntryDecorator<@NonNull T>> entryDecorators |
the |
@NonNull Function1<@NonNull key, @NonNull NavEntry<@NonNull T>> entryProvider |
a function that returns the |