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
|
Constants | |
---|---|
String |
KEY_DEEP_LINK_INTENT
The |
Public constructors | |
---|---|
NavController(Context context)
Constructs a new controller for a given |
Public methods | |
---|---|
void
|
addOnDestinationChangedListener(NavController.OnDestinationChangedListener listener)
Adds an |
NavDeepLinkBuilder
|
createDeepLink()
Create a deep link to a destination within this NavController. |
NavBackStackEntry
|
getBackStackEntry(int destinationId)
Gets the topmost |
NavDestination
|
getCurrentDestination()
Gets the current destination. |
NavGraph
|
getGraph()
Gets the topmost navigation graph associated with this NavController. |
NavInflater
|
getNavInflater()
Returns the |
NavigatorProvider
|
getNavigatorProvider()
Retrieve the NavController's |
ViewModelStoreOwner
|
getViewModelStoreOwner(int navGraphId)
Gets the |
boolean
|
handleDeepLink(Intent intent)
Checks the given Intent for a Navigation deep link and navigates to the deep link if present. |
void
|
navigate(Uri deepLink, NavOptions navOptions, Navigator.Extras navigatorExtras)
Navigate to a destination via the given deep link |
void
|
navigate(int resId, Bundle args)
Navigate to a destination from the current navigation graph. |
void
|
navigate(Uri deepLink)
Navigate to a destination via the given deep link |
void
|
navigate(NavDirections directions)
Navigate via the given |
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 |
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(NavDirections directions, Navigator.Extras navigatorExtras)
Navigate via the given |
void
|
navigate(Uri deepLink, NavOptions navOptions)
Navigate to a destination via the given deep link |
boolean
|
navigateUp()
Attempts to navigate up in the navigation hierarchy. |
boolean
|
popBackStack()
Attempts to pop the controller's back stack. |
boolean
|
popBackStack(int destinationId, boolean inclusive)
Attempts to pop the controller's back stack back to a specific destination. |
void
|
removeOnDestinationChangedListener(NavController.OnDestinationChangedListener listener)
Removes an |
void
|
restoreState(Bundle navState)
Restores all navigation controller state from a bundle. |
Bundle
|
saveState()
Saves all navigation controller state to a Bundle. |
void
|
setGraph(NavGraph graph, Bundle startDestinationArgs)
Sets the |
void
|
setGraph(int graphResId, Bundle startDestinationArgs)
Sets the |
void
|
setGraph(int graphResId)
Sets the |
void
|
setGraph(NavGraph graph)
Sets the |
Inherited methods | |
---|---|
Constants
KEY_DEEP_LINK_INTENT
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
NavController
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
|
getBackStackEntry
public NavBackStackEntry getBackStackEntry (int destinationId)
Gets the topmost NavBackStackEntry
for a destination id.
This is always safe to use with the current destination
or
its parent
or grandparent navigation graphs as these
destinations are guaranteed to be on the back stack.
Parameters | |
---|---|
destinationId |
int : ID of a destination that exists on the back stack |
Returns | |
---|---|
NavBackStackEntry |
Throws | |
---|---|
IllegalArgumentException |
if the destination is not on the back stack |
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() .
|
See also:
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.
|
getViewModelStoreOwner
public ViewModelStoreOwner getViewModelStoreOwner (int navGraphId)
Gets the ViewModelStoreOwner
for a NavGraph. This can be passed to
ViewModelProvider
to retrieve a ViewModel that is scoped
to the navigation graph - it will be cleared when the navigation graph is popped off
the back stack.
Parameters | |
---|---|
navGraphId |
int : ID of a NavGraph that exists on the back stack |
Returns | |
---|---|
ViewModelStoreOwner |
Throws | |
---|---|
IllegalStateException |
if called before the NavHost has called
NavHostController.setViewModelStore(ViewModelStore) . |
IllegalArgumentException |
if the NavGraph is not on the back stack |
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:
- Intents created by
NavDeepLinkBuilder
or
createDeepLink()
. This assumes that the current graph shares
the same hierarchy to get to the deep linked destination as when the deep link was
constructed.- Intents that include a
data Uri
. This Uri will be checked
against the Uri patterns added via NavDestination.addDeepLink(String)
.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. |
See also:
navigate
public void navigate (Uri deepLink, NavOptions navOptions, Navigator.Extras navigatorExtras)
Navigate to a destination via the given deep link Uri
.
NavDestination.hasDeepLink(Uri)
should be called on
the navigation graph
prior to calling this method to check if the deep
link is valid. If an invalid deep link is given, an IllegalArgumentException
will be
thrown.
Parameters | |
---|---|
deepLink |
Uri : deepLink to the destination reachable from the current NavGraph |
navOptions |
NavOptions : special options for this navigation operation |
navigatorExtras |
Navigator.Extras : extras to pass to the Navigator
|
navigate
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
|
navigate
public void navigate (Uri deepLink)
Navigate to a destination via the given deep link Uri
.
NavDestination.hasDeepLink(Uri)
should be called on
the navigation graph
prior to calling this method to check if the deep
link is valid. If an invalid deep link is given, an IllegalArgumentException
will be
thrown.
Parameters | |
---|---|
deepLink |
Uri : deepLink to the destination reachable from the current NavGraph
|
navigate
public void navigate (NavDirections directions)
Navigate via the given NavDirections
Parameters | |
---|---|
directions |
NavDirections : directions that describe this navigation operation
|
navigate
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
|
navigate
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
|
navigate
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
|
navigate
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
|
navigate
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
|
navigate
public void navigate (Uri deepLink, NavOptions navOptions)
Navigate to a destination via the given deep link Uri
.
NavDestination.hasDeepLink(Uri)
should be called on
the navigation graph
prior to calling this method to check if the deep
link is valid. If an invalid deep link is given, an IllegalArgumentException
will be
thrown.
Parameters | |
---|---|
deepLink |
Uri : deepLink to the destination reachable from the current NavGraph |
navOptions |
NavOptions : special options for this navigation operation
|
navigateUp
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 ()
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 and the user has been navigated to another destination, 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 and the user has been navigated to another destination, 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 (NavGraph graph, Bundle startDestinationArgs)
Sets the navigation graph
to the specified graph.
Any current navigation graph data (including back stack) will be replaced.
The graph can be retrieved later via getGraph()
.
Parameters | |
---|---|
graph |
NavGraph : graph to set |
startDestinationArgs |
Bundle |
See also:
setGraph
public void setGraph (int graphResId, Bundle startDestinationArgs)
Sets the navigation graph
to the specified resource.
Any current navigation graph data (including back stack) 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 (including back stack) 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)
Sets the navigation graph
to the specified graph.
Any current navigation graph data (including back stack) will be replaced.
The graph can be retrieved later via getGraph()
.
Parameters | |
---|---|
graph |
NavGraph : graph to set |
See also:
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.