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

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

abstract

Listener for observing navigation events for this specific navigator.

Constants
static Int

Indicator that the navigation event has added a new entry to the back stack.

static Int

Indicator that the navigation event has popped an entry off the back stack.

static Int

Indicator that the navigation event should not change the NavController's back stack.

Public constructors

Public methods
abstract Unit
navigate(destination: D, args: Bundle?, navOptions: NavOptions?)

Navigate to a destination.

Unit
dispatchOnNavigatorNavigated(destId: Int, backStackEffect: Int)

Dispatch a navigated event to all registered listeners.

abstract D

Construct a new NavDestination associated with this Navigator.

Unit

Add a listener to be notified when this navigator changes navigation destinations.

abstract Boolean

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

Unit

Remove a listener so that it will no longer be notified when this navigator changes navigation destinations.

Constants

BACK_STACK_DESTINATION_ADDED

static val BACK_STACK_DESTINATION_ADDED: Int

Indicator that the navigation event has added a new entry to the back stack. Only destinations added with this flag will be handled by NavController#navigateUp().

Value: 1

BACK_STACK_DESTINATION_POPPED

static val BACK_STACK_DESTINATION_POPPED: Int

Indicator that the navigation event has popped an entry off the back stack.

Value: 2

BACK_STACK_UNCHANGED

static val BACK_STACK_UNCHANGED: Int

Indicator that the navigation event should not change the NavController's back stack.

For example, a single top navigation event may not result in a back stack change if the existing destination is on the top of the stack.

Value: 0

Public constructors

<init>

Navigator()

Public methods

navigate

abstract fun navigate(destination: D, args: Bundle?, navOptions: NavOptions?): 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.

Implementations should #dispatchOnNavigatorNavigated to notify listeners of the resulting navigation destination.

Parameters
destination D: destination node to navigate to
args D: arguments to use for navigation
navOptions D: additional options for navigation

dispatchOnNavigatorNavigated

fun dispatchOnNavigatorNavigated(destId: Int, backStackEffect: Int): Unit

Dispatch a navigated event to all registered listeners. Utility for navigator implementations.

Parameters
destId Int: id of the new destination
backStackEffect Int: how the navigation event affects the back stack

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.

Return
D: a new NavDestination

addOnNavigatorNavigatedListener

fun addOnNavigatorNavigatedListener(listener: Navigator.OnNavigatorNavigatedListener): Unit

Add a listener to be notified when this navigator changes navigation destinations.

Most application code should use NavController#addOnNavigatedListener(NavController.OnNavigatedListener) instead.

Parameters
listener Navigator.OnNavigatorNavigatedListener: listener to add

popBackStack

abstract fun popBackStack(): Boolean

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

Implementations should #dispatchOnNavigatorNavigated to notify listeners of the resulting navigation destination and 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

removeOnNavigatorNavigatedListener

fun removeOnNavigatorNavigatedListener(listener: Navigator.OnNavigatorNavigatedListener): Unit

Remove a listener so that it will no longer be notified when this navigator changes navigation destinations.

Parameters
listener Navigator.OnNavigatorNavigatedListener: listener to remove