NavController

public class NavController
extends Object

java.lang.Object
   ↳ androidx.navigation.NavController


NavController manages app navigation within a NavHost.

Apps will generally obtain a controller directly from a host, or by using one of the utility methods on the Navigation class rather than create a controller directly.

Navigation flows and destinations are determined by the navigation graph owned by the controller. These graphs are typically inflated from an Android resource, but, like views, they can also be constructed or combined programmatically or for the case of dynamic navigation structure. (For example, if the navigation structure of the application is determined by live data obtained' from a remote server.)

Summary

Nested classes

interface NavController.OnDestinationChangedListener

OnDestinationChangedListener receives a callback when the NavController.getCurrentDestination() or its arguments change. 

Constants

String KEY_DEEP_LINK_INTENT

The Intent that triggered a deep link to the current destination.

Public constructors

NavController(Context context)

Constructs a new controller for a given Context.

Public methods

void addOnDestinationChangedListener(NavController.OnDestinationChangedListener listener)

Adds an NavController.OnDestinationChangedListener to this controller to receive a callback whenever the getCurrentDestination() or its arguments change.

NavDeepLinkBuilder createDeepLink()

Create a deep link to a destination within this NavController.

NavDestination getCurrentDestination()

Gets the current destination.

NavGraph getGraph()

Gets the topmost navigation graph associated with this NavController.

NavInflater getNavInflater()

Returns the inflater for this controller.

NavigatorProvider getNavigatorProvider()

Retrieve the NavController's NavigatorProvider.

boolean handleDeepLink(Intent intent)

Checks the given Intent for a Navigation deep link and navigates to the deep link if present.

void navigate(int resId)

Navigate to a destination from the current navigation graph.

void navigate(int resId, Bundle args, NavOptions navOptions)

Navigate to a destination from the current navigation graph.

void navigate(int resId, Bundle args)

Navigate to a destination from the current navigation graph.

void navigate(NavDirections directions, Navigator.Extras navigatorExtras)

Navigate via the given NavDirections

void navigate(NavDirections directions)

Navigate via the given NavDirections

void navigate(int resId, Bundle args, NavOptions navOptions, Navigator.Extras navigatorExtras)

Navigate to a destination from the current navigation graph.

void navigate(NavDirections directions, NavOptions navOptions)

Navigate via the given NavDirections

boolean navigateUp()

Attempts to navigate up in the navigation hierarchy.

boolean popBackStack(int destinationId, boolean inclusive)

Attempts to pop the controller's back stack back to a specific destination.

boolean popBackStack()

Attempts to pop the controller's back stack.

void removeOnDestinationChangedListener(NavController.OnDestinationChangedListener listener)

Removes an NavController.OnDestinationChangedListener from this controller.

void restoreState(Bundle navState)

Restores all navigation controller state from a bundle.

Bundle saveState()

Saves all navigation controller state to a Bundle.

void setGraph(int graphResId, Bundle startDestinationArgs)

Sets the navigation graph to the specified resource.

void setGraph(int graphResId)

Sets the navigation graph to the specified resource.

void setGraph(NavGraph graph, Bundle startDestinationArgs)

Sets the navigation graph to the specified graph.

void setGraph(NavGraph graph)

Sets the navigation graph to the specified graph.

Inherited methods

Constants

public static final String KEY_DEEP_LINK_INTENT

The Intent that triggered a deep link to the current destination.

Constant Value: "android-support-nav:controller:deepLinkIntent"

Public constructors

public NavController (Context context)

Constructs a new controller for a given Context. Controllers should not be used outside of their context and retain a hard reference to the context supplied. If you need a global controller, pass Context.getApplicationContext().

Apps should generally not construct controllers, instead obtain a relevant controller directly from a navigation host via NavHost.getNavController() or by using one of the utility methods on the Navigation class.

Note that controllers that are not constructed with an Activity context (or a wrapped activity context) will only be able to navigate to new tasks or new document tasks when navigating to new activities.

Parameters
context Context: context for this controller

Public methods

addOnDestinationChangedListener

public void addOnDestinationChangedListener (NavController.OnDestinationChangedListener listener)

Adds an NavController.OnDestinationChangedListener to this controller to receive a callback whenever the getCurrentDestination() or its arguments change.

The current destination, if any, will be immediately sent to your listener.

Parameters
listener NavController.OnDestinationChangedListener: the listener to receive events

createDeepLink

public NavDeepLinkBuilder createDeepLink ()

Create a deep link to a destination within this NavController.

Returns
NavDeepLinkBuilder a NavDeepLinkBuilder suitable for constructing a deep link

getCurrentDestination

public NavDestination getCurrentDestination ()

Gets the current destination.

Returns
NavDestination

getGraph

public NavGraph getGraph ()

Gets the topmost navigation graph associated with this NavController.

Returns
NavGraph

Throws
IllegalStateException if called before setGraph().

getNavInflater

public NavInflater getNavInflater ()

Returns the inflater for this controller.

Returns
NavInflater inflater for loading navigation resources

getNavigatorProvider

public NavigatorProvider getNavigatorProvider ()

Retrieve the NavController's NavigatorProvider. All Navigators used to construct the navigation graph for this nav controller should be added to this navigator provider before the graph is constructed.

Generally, the Navigators are set for you by the NavHost hosting this NavController and you do not need to manually interact with the navigator provider.

Returns
NavigatorProvider The NavigatorProvider used by this NavController.

handleDeepLink

public boolean handleDeepLink (Intent intent)

Checks the given Intent for a Navigation deep link and navigates to the deep link if present. This is called automatically for you the first time you set the graph if you've passed in an Activity as the context when constructing this NavController, but should be manually called if your Activity receives new Intents in Activity.onNewIntent(Intent).

The types of Intents that are supported include:

The navigation graph should be set before calling this method.

Parameters
intent Intent: The Intent that may contain a valid deep link

Returns
boolean True if the navigation controller found a valid deep link and navigated to it.

public void navigate (int resId)

Navigate to a destination from the current navigation graph. This supports both navigating via an action and directly navigating to a destination.

Parameters
resId int: an action id or a destination id to navigate to

public void navigate (int resId, 
                Bundle args, 
                NavOptions navOptions)

Navigate to a destination from the current navigation graph. This supports both navigating via an action and directly navigating to a destination.

Parameters
resId int: an action id or a destination id to navigate to

args Bundle: arguments to pass to the destination

navOptions NavOptions: special options for this navigation operation

public void navigate (int resId, 
                Bundle args)

Navigate to a destination from the current navigation graph. This supports both navigating via an action and directly navigating to a destination.

Parameters
resId int: an action id or a destination id to navigate to

args Bundle: arguments to pass to the destination

public void navigate (NavDirections directions, 
                Navigator.Extras navigatorExtras)

Navigate via the given NavDirections

Parameters
directions NavDirections: directions that describe this navigation operation

navigatorExtras Navigator.Extras: extras to pass to the Navigator

public void navigate (NavDirections directions)

Navigate via the given NavDirections

Parameters
directions NavDirections: directions that describe this navigation operation

public void navigate (int resId, 
                Bundle args, 
                NavOptions navOptions, 
                Navigator.Extras navigatorExtras)

Navigate to a destination from the current navigation graph. This supports both navigating via an action and directly navigating to a destination.

Parameters
resId int: an action id or a destination id to navigate to

args Bundle: arguments to pass to the destination

navOptions NavOptions: special options for this navigation operation

navigatorExtras Navigator.Extras: extras to pass to the Navigator

public void navigate (NavDirections directions, 
                NavOptions navOptions)

Navigate via the given NavDirections

Parameters
directions NavDirections: directions that describe this navigation operation

navOptions NavOptions: special options for this navigation operation

public boolean navigateUp ()

Attempts to navigate up in the navigation hierarchy. Suitable for when the user presses the "Up" button marked with a left (or start)-facing arrow in the upper left (or starting) corner of the app UI.

The intended behavior of Up differs from Back when the user did not reach the current destination from the application's own task. e.g. if the user is viewing a document or link in the current app in an activity hosted on another app's task where the user clicked the link. In this case the current activity (determined by the context used to create this NavController) will be finished and the user will be taken to an appropriate destination in this app on its own task.

Returns
boolean true if navigation was successful, false otherwise

popBackStack

public boolean popBackStack (int destinationId, 
                boolean inclusive)

Attempts to pop the controller's back stack back to a specific destination.

Parameters
destinationId int: The topmost destination to retain

inclusive boolean: Whether the given destination should also be popped.

Returns
boolean true if the stack was popped at least once, false otherwise

popBackStack

public boolean popBackStack ()

Attempts to pop the controller's back stack. Analogous to when the user presses the system Back button when the associated navigation host has focus.

Returns
boolean true if the stack was popped, false otherwise

removeOnDestinationChangedListener

public void removeOnDestinationChangedListener (NavController.OnDestinationChangedListener listener)

Removes an NavController.OnDestinationChangedListener from this controller. It will no longer receive callbacks.

Parameters
listener NavController.OnDestinationChangedListener: the listener to remove

restoreState

public void restoreState (Bundle navState)

Restores all navigation controller state from a bundle. This should be called before any call to setGraph(NavGraph).

State may be saved to a bundle by calling saveState(). Restoring controller state is the responsibility of a NavHost.

Parameters
navState Bundle: state bundle to restore

saveState

public Bundle saveState ()

Saves all navigation controller state to a Bundle.

State may be restored from a bundle returned from this method by calling restoreState(Bundle). Saving controller state is the responsibility of a NavHost.

Returns
Bundle saved state for this controller

setGraph

public void setGraph (int graphResId, 
                Bundle startDestinationArgs)

Sets the navigation graph to the specified resource. Any current navigation graph data will be replaced.

The inflated graph can be retrieved via getGraph().

Parameters
graphResId int: resource id of the navigation graph to inflate

startDestinationArgs Bundle: arguments to send to the start destination of the graph

setGraph

public void setGraph (int graphResId)

Sets the navigation graph to the specified resource. Any current navigation graph data will be replaced.

The inflated graph can be retrieved via getGraph().

Parameters
graphResId int: resource id of the navigation graph to inflate

setGraph

public void setGraph (NavGraph graph, 
                Bundle startDestinationArgs)

Sets the navigation graph to the specified graph. Any current navigation graph data will be replaced.

The graph can be retrieved later via getGraph().

Parameters
graph NavGraph: graph to set

startDestinationArgs Bundle

setGraph

public void setGraph (NavGraph graph)

Sets the navigation graph to the specified graph. Any current navigation graph data will be replaced.

The graph can be retrieved later via getGraph().

Parameters
graph NavGraph: graph to set