NavigatorState

abstract class NavigatorState

Known direct subclasses
TestNavigatorState

An implementation of NavigatorState that allows testing a androidx.navigation.Navigator in isolation (i.e., without requiring a androidx.navigation.NavController).

The NavigatorState encapsulates the state shared between the Navigator and the NavController.

Summary

Public constructors

Public functions
abstract NavBackStackEntry
createBackStackEntry(destination: NavDestination, arguments: SavedState?)

Create a new NavBackStackEntry from a given destination and arguments.
open Unit

This removes the given NavBackStackEntry from the set of the transitions in progress.
open Unit

Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation.
open Unit

Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation.
open Unit
pop(popUpTo: NavBackStackEntry, saveState: Boolean)

Pop all destinations up to and including popUpTo.
open Unit

Pops all destinations up to and including popUpTo.
open Unit

This prepares the given NavBackStackEntry for transition.
open Unit
push(backStackEntry: NavBackStackEntry)

Adds the given backStackEntry to the backStack.
open Unit

Adds the given backStackEntry to the backStack.

Public properties
StateFlow<List<NavBackStackEntry>>

While the NavController is responsible for the combined back stack across all Navigators, this back stack is specifically the set of destinations associated with this Navigator.
StateFlow<Set<NavBackStackEntry>>

This is the set of currently running transitions.

Public constructors

Added in 2.4.0
NavigatorState()

Public functions

createBackStackEntry

abstract fun createBackStackEntry(destination: NavDestination, arguments: SavedState?): NavBackStackEntry

Create a new NavBackStackEntry from a given destination and arguments.

markTransitionComplete

Added in 2.4.0
open fun markTransitionComplete(entry: NavBackStackEntry): Unit

This removes the given NavBackStackEntry from the set of the transitions in progress. This should be called in conjunction with pushWithTransition and popWithTransition as those call are responsible for adding entries to transitionsInProgress.

This should also always be called in conjunction with prepareForTransition to ensure all NavBackStackEntries settle into the proper state.

Failing to call this method could result in entries being prevented from reaching their final Lifecycle.State}.

See also
pushWithTransition
popWithTransition

onLaunchSingleTop

Added in 2.4.0
@CallSuper
open fun onLaunchSingleTop(backStackEntry: NavBackStackEntry): Unit

Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation.

Replaces the topmost entry with same id with the new backStackEntry

Parameters
backStackEntry: NavBackStackEntry

the NavBackStackEntry to replace the old Entry within the backStack

onLaunchSingleTopWithTransition

Added in 2.6.0
@CallSuper
open fun onLaunchSingleTopWithTransition(backStackEntry: NavBackStackEntry): Unit

Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation. This also adds the given and previous entry to the set of in progress transitions. Added entries have their Lifecycle capped at Lifecycle.State.STARTED until an entry is passed into the markTransitionComplete callback, when they are allowed to go to Lifecycle.State.RESUMED while previous entries have their Lifecycle held at Lifecycle.State.CREATED until an entry is passed into the markTransitionComplete callback, when they are allowed to go to Lifecycle.State.DESTROYED and have their state cleared.

Replaces the topmost entry with same id with the new backStackEntry

Parameters
backStackEntry: NavBackStackEntry

the NavBackStackEntry to replace the old Entry within the backStack

pop

Added in 2.4.0
open fun pop(popUpTo: NavBackStackEntry, saveState: Boolean): Unit

Pop all destinations up to and including popUpTo. This will remove those destinations from the backStack, saving their state if saveState is true.

popWithTransition

Added in 2.4.0
open fun popWithTransition(popUpTo: NavBackStackEntry, saveState: Boolean): Unit

Pops all destinations up to and including popUpTo. This also adds the given and incoming entry to the set of in progress transitions. Added entries have their Lifecycle held at Lifecycle.State.CREATED until an entry is passed into the markTransitionComplete callback, when they are allowed to go to Lifecycle.State.DESTROYED and have their state cleared.

This will remove those destinations from the backStack, saving their state if saveState is true.

See also
transitionsInProgress
markTransitionComplete
pushWithTransition

prepareForTransition

Added in 2.6.0
@CallSuper
open fun prepareForTransition(entry: NavBackStackEntry): Unit

This prepares the given NavBackStackEntry for transition. This should be called in conjunction with markTransitionComplete as that is responsible for settling the NavBackStackEntry into its final state.

See also
markTransitionComplete

push

Added in 2.4.0
open fun push(backStackEntry: NavBackStackEntry): Unit

Adds the given backStackEntry to the backStack.

pushWithTransition

Added in 2.4.0
open fun pushWithTransition(backStackEntry: NavBackStackEntry): Unit

Adds the given backStackEntry to the backStack. This also adds the given and previous entry to the set of in progress transitions. Added entries have their Lifecycle capped at Lifecycle.State.STARTED until an entry is passed into the markTransitionComplete callback, when they are allowed to go to Lifecycle.State.RESUMED.

See also
transitionsInProgress
markTransitionComplete
popWithTransition

Public properties

backStack

Added in 2.4.0
val backStack: StateFlow<List<NavBackStackEntry>>

While the NavController is responsible for the combined back stack across all Navigators, this back stack is specifically the set of destinations associated with this Navigator.

Changing the back stack must be done via push and pop.

transitionsInProgress

Added in 2.4.0
val transitionsInProgress: StateFlow<Set<NavBackStackEntry>>

This is the set of currently running transitions. Use this set to retrieve the entry and call markTransitionComplete once the transition is complete.