Navigator

public abstract class Navigator
extends Object

java.lang.Object
   ↳ androidx.navigation.Navigator<D extends androidx.navigation.NavDestination>


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

@interface Navigator.Name

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

interface Navigator.OnNavigatorNavigatedListener

Listener for observing navigation events for this specific navigator. 

Constants

int BACK_STACK_DESTINATION_ADDED

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

int BACK_STACK_DESTINATION_POPPED

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

int BACK_STACK_UNCHANGED

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

Public constructors

Navigator()

Public methods

final void addOnNavigatorNavigatedListener(Navigator.OnNavigatorNavigatedListener listener)

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

abstract D createDestination()

Construct a new NavDestination associated with this Navigator.

final void dispatchOnNavigatorNavigated(int destId, int backStackEffect)

Dispatch a navigated event to all registered listeners.

abstract void navigate(D destination, Bundle args, NavOptions navOptions)

Navigate to a destination.

abstract boolean popBackStack()

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

final void removeOnNavigatorNavigatedListener(Navigator.OnNavigatorNavigatedListener listener)

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

Inherited methods

Constants

BACK_STACK_DESTINATION_ADDED

int BACK_STACK_DESTINATION_ADDED

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().

Constant Value: 1 (0x00000001)

BACK_STACK_DESTINATION_POPPED

int BACK_STACK_DESTINATION_POPPED

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

Constant Value: 2 (0x00000002)

BACK_STACK_UNCHANGED

int BACK_STACK_UNCHANGED

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.

Constant Value: 0 (0x00000000)

Public constructors

Navigator

Navigator ()

Public methods

addOnNavigatorNavigatedListener

void addOnNavigatorNavigatedListener (Navigator.OnNavigatorNavigatedListener listener)

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

createDestination

D createDestination ()

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

dispatchOnNavigatorNavigated

void dispatchOnNavigatorNavigated (int destId, 
                int backStackEffect)

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

navigate

void navigate (D destination, 
                Bundle args, 
                NavOptions navOptions)

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(int, int) to notify listeners of the resulting navigation destination.

Parameters
destination D: destination node to navigate to

args Bundle: arguments to use for navigation

navOptions NavOptions: additional options for navigation

popBackStack

boolean popBackStack ()

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

Implementations should dispatchOnNavigatorNavigated(int, int) 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.

Returns
boolean true if pop was successful

removeOnNavigatorNavigatedListener

void removeOnNavigatorNavigatedListener (Navigator.OnNavigatorNavigatedListener listener)

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

Parameters
listener Navigator.OnNavigatorNavigatedListener: listener to remove