Navigator
-
Cmn
abstract class Navigator<D : NavDestination>
ActivityNavigator |
ActivityNavigator implements cross-activity navigation. |
BottomSheetNavigator |
Navigator that drives a |
ComposableFragmentNavigator |
This Navigator intercepts the inflation of |
ComposeNavigator |
Navigator that navigates through |
DialogFragmentNavigator |
Navigator that uses |
DialogNavigator |
Navigator that navigates through |
DynamicIncludeGraphNavigator |
Navigator for |
FragmentNavigator |
Navigator that navigates through |
NavGraphNavigator |
A Navigator built specifically for |
WearNavigator |
Navigator that navigates through |
DynamicFragmentNavigator |
The |
DynamicGraphNavigator |
Navigator for graphs in dynamic feature modules. |
Navigator defines a mechanism for navigating within an app.
Each Navigator sets the policy for a specific type of navigation, e.g. ActivityNavigator knows how to launch into destinations backed by activities using Context.startActivity.
Navigators should be able to manage their own back stack when navigating between two destinations that belong to that navigator. The NavController manages a back stack of navigators representing the current navigation stack across all navigators.
Each Navigator should add the Navigator.Name annotation to their class. Any custom attributes used by the associated destination subclass should have a name corresponding with the name of the Navigator, e.g., ActivityNavigator uses <declare-styleable name="ActivityNavigator">
| Parameters | |
|---|---|
<D : NavDestination> |
the subclass of |
Summary
Nested types |
|---|
interface Navigator.ExtrasInterface indicating that this class should be passed to its respective |
@Retention(value = AnnotationRetention.RUNTIME)This annotation should be added to each Navigator subclass in Android to denote the default name used to register the Navigator with a |
Public constructors |
|
|---|---|
<D : NavDestination> Navigator() |
Cmn
|
Public functions |
||
|---|---|---|
abstract D |
Construct a new NavDestination associated with this Navigator. |
Cmn
|
open Unit |
navigate(Navigate to a destination. |
Cmn
|
open NavDestination? |
navigate(Navigate to a destination. |
Cmn
|
open Unit |
@CallSuperIndicator that this Navigator is actively being used by a |
Cmn
|
open Unit |
onLaunchSingleTop(backStackEntry: NavBackStackEntry)Informational callback indicating that the given |
Cmn
|
open Unit |
onRestoreState(savedState: SavedState)Restore any state previously saved in |
Cmn
|
open SavedState? |
Called to ask for a |
Cmn
|
open Boolean |
Attempt to pop this navigator's back stack, performing the appropriate navigation. |
Cmn
|
open Unit |
popBackStack(popUpTo: NavBackStackEntry, savedState: Boolean)Attempt to pop this navigator's back stack, performing the appropriate navigation. |
Cmn
|
Public properties |
||
|---|---|---|
Boolean |
Whether this Navigator is actively being used by a |
Cmn
|
Protected properties |
||
|---|---|---|
NavigatorState |
The state of the Navigator is the communication conduit between the Navigator and the |
Cmn
|
Public constructors
Public functions
createDestination
abstract fun createDestination(): D
Construct a new NavDestination associated with this Navigator.
Any initialization of the destination should be done in the destination's constructor as it is not guaranteed that every destination will be created through this method.
| Returns | |
|---|---|
D |
a new NavDestination |
navigate
open fun navigate(
entries: List<NavBackStackEntry>,
navOptions: NavOptions?,
navigatorExtras: Navigator.Extras?
): Unit
Navigate to a destination.
Requests navigation to a given destination associated with this navigator in the navigation graph. This method generally should not be called directly; NavController will delegate to it when appropriate.
| Parameters | |
|---|---|
entries: List<NavBackStackEntry> |
destination(s) to navigate to |
navOptions: NavOptions? |
additional options for navigation |
navigatorExtras: Navigator.Extras? |
extras unique to your Navigator. |
navigate
open fun navigate(
destination: D,
args: SavedState?,
navOptions: NavOptions?,
navigatorExtras: Navigator.Extras?
): NavDestination?
Navigate to a destination.
Requests navigation to a given destination associated with this navigator in the navigation graph. This method generally should not be called directly; NavController will delegate to it when appropriate.
| Parameters | |
|---|---|
destination: D |
destination node to navigate to |
args: SavedState? |
arguments to use for navigation |
navOptions: NavOptions? |
additional options for navigation |
navigatorExtras: Navigator.Extras? |
extras unique to your Navigator. |
| Returns | |
|---|---|
NavDestination? |
The NavDestination that should be added to the back stack or null if no change was made to the back stack (i.e., in cases of single top operations where the destination is already on top of the back stack). |
onAttach
@CallSuper
open fun onAttach(state: NavigatorState): Unit
Indicator that this Navigator is actively being used by a NavController. This is called when the NavController's state is ready to be restored.
onLaunchSingleTop
open fun onLaunchSingleTop(backStackEntry: NavBackStackEntry): Unit
Informational callback indicating that the given backStackEntry has been affected by a NavOptions.shouldLaunchSingleTop operation. The entry provided is a new NavBackStackEntry instance with all the previous state of the old entry and possibly new arguments.
onRestoreState
open fun onRestoreState(savedState: SavedState): Unit
Restore any state previously saved in onSaveState. This will be called before any calls to navigate or popBackStack.
Calls to createDestination should not be dependent on any state restored here as createDestination can be called before the state is restored.
| Parameters | |
|---|---|
savedState: SavedState |
The state previously saved |
onSaveState
open fun onSaveState(): SavedState?
Called to ask for a SavedState representing the Navigator's state. This will be restored in onRestoreState.
popBackStack
open fun popBackStack(): Boolean
Attempt to pop this navigator's back stack, performing the appropriate navigation.
Implementations should return true if navigation was successful. Implementations should return false if navigation could not be performed, for example if the navigator's back stack was empty.
| Returns | |
|---|---|
Boolean |
|
popBackStack
open fun popBackStack(popUpTo: NavBackStackEntry, savedState: Boolean): Unit
Attempt to pop this navigator's back stack, performing the appropriate navigation.
All destinations back to popUpTo should be popped off the back stack.
| Parameters | |
|---|---|
popUpTo: NavBackStackEntry |
the entry that should be popped off the |
savedState: Boolean |
whether any Navigator specific state associated with |
Public properties
isAttached
val isAttached: Boolean
Whether this Navigator is actively being used by a NavController.
This is set to true when onAttach is called.
Protected properties
state
protected val state: NavigatorState
The state of the Navigator is the communication conduit between the Navigator and the NavController that has called onAttach.
It is the responsibility of the Navigator to call NavigatorState.push and NavigatorState.pop to in order to update the NavigatorState.backStack at the appropriate times.
| Throws | |
|---|---|
kotlin.IllegalStateException |
if |