Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

Navigator

abstract class Navigator<D : NavDestination!>
kotlin.Any
   ↳ androidx.navigation.Navigator

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 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">

Summary

Nested classes

abstract

Interface indicating that this class should be passed to its respective Navigator to enable Navigator specific behavior.

This annotation should be added to each Navigator subclass to denote the default name used to register the Navigator with a NavigatorProvider.

Public constructors

Navigator defines a mechanism for navigating within an app.

Public methods

abstract D

Construct a new NavDestination associated with this Navigator.

abstract NavDestination?
navigate(@NonNull destination: D, @Nullable args: Bundle?, @Nullable navOptions: NavOptions?, @Nullable navigatorExtras: Navigator.Extras?)

Navigate to a destination.

open Unit
onRestoreState(@NonNull savedState: Bundle)

Restore any state previously saved in onSaveState().

open Bundle?

Called to ask for a Bundle representing the Navigator's state.

abstract Boolean

Attempt to pop this navigator's back stack, performing the appropriate navigation.

Public constructors

<init>

Navigator()

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 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">

Public methods

createDestination

@NonNull 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.

Return
D: a new NavDestination

navigate

@Nullable abstract fun navigate(@NonNull destination: D, @Nullable args: Bundle?, @Nullable navOptions: NavOptions?, @Nullable 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 D: arguments to use for navigation
navOptions D: additional options for navigation
navigatorExtras D: extras unique to your Navigator.
Return
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).

onRestoreState

open fun onRestoreState(@NonNull savedState: Bundle): Unit

Restore any state previously saved in onSaveState(). This will be called before any calls to navigate(NavDestination, Bundle, NavOptions, Navigator.Extras) 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 Bundle: The state previously saved

onSaveState

@Nullable open fun onSaveState(): Bundle?

Called to ask for a Bundle representing the Navigator's state. This will be restored in onRestoreState(Bundle).

popBackStack

abstract 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.

Return
Boolean: true if pop was successful