Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

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

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

@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, Navigator.Extras navigatorExtras)

Navigate to a destination.

void onActive()

Called when the number of listeners change from 0 to 1

void onInactive()

Called when the number of listeners change from 1 to 0

void onRestoreState(Bundle savedState)

Restore any state previously saved in onSaveState().

Bundle onSaveState()

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

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

public static final 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

public static final 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

public static final 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

public Navigator ()

Public methods

addOnNavigatorNavigatedListener

public final 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

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

public final 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

public abstract void navigate (D destination, 
                Bundle args, 
                NavOptions navOptions, 
                Navigator.Extras navigatorExtras)

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

navigatorExtras Navigator.Extras: extras unique to your Navigator.

onActive

public void onActive ()

Called when the number of listeners change from 0 to 1

onInactive

public void onInactive ()

Called when the number of listeners change from 1 to 0

onRestoreState

public void onRestoreState (Bundle savedState)

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

public Bundle onSaveState ()

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

Returns
Bundle

popBackStack

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

public final 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