NavController
open class NavController
kotlin.Any | |
↳ | 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 |
|
---|---|
abstract |
OnDestinationChangedListener receives a callback when the |
Constants |
|
---|---|
static String |
The |
Public constructors |
|
---|---|
Constructs a new controller for a given |
Public methods |
|
---|---|
open Unit |
Adds an |
open NavDeepLinkBuilder |
Create a deep link to a destination within this NavController. |
open NavBackStackEntry |
getBackStackEntry(@IdRes : Int) Gets the topmost |
open NavDestination? |
Gets the current destination. |
open NavGraph |
getGraph() Gets the topmost navigation graph associated with this NavController. |
open NavInflater |
Returns the |
open NavigatorProvider |
Retrieve the NavController's |
open ViewModelStoreOwner |
getViewModelStoreOwner(@IdRes : Int) Gets the |
open Boolean |
handleDeepLink(@Nullable : Intent?) Checks the given Intent for a Navigation deep link and navigates to the deep link if present. |
open Unit |
Navigate to a destination from the current navigation graph. |
open Unit |
Navigate to a destination from the current navigation graph. |
open Unit |
navigate(@IdRes : Int, @Nullable : Bundle?, @Nullable : NavOptions?) Navigate to a destination from the current navigation graph. |
open Unit |
navigate(@IdRes : Int, @Nullable : Bundle?, @Nullable : NavOptions?, @Nullable : Navigator.Extras?) Navigate to a destination from the current navigation graph. |
open Unit |
Navigate to a destination via the given deep link |
open Unit |
navigate(@NonNull : Uri, @Nullable : NavOptions?) Navigate to a destination via the given deep link |
open Unit |
navigate(@NonNull : Uri, @Nullable : NavOptions?, @Nullable : Navigator.Extras?) Navigate to a destination via the given deep link |
open Unit |
navigate(@NonNull : NavDirections) Navigate via the given |
open Unit |
navigate(@NonNull : NavDirections, @Nullable : NavOptions?) Navigate via the given |
open Unit |
navigate(@NonNull : NavDirections, @NonNull : Navigator.Extras) Navigate via the given |
open Boolean |
Attempts to navigate up in the navigation hierarchy. |
open Boolean |
Attempts to pop the controller's back stack. |
open Boolean |
popBackStack(@IdRes : Int, : Boolean) Attempts to pop the controller's back stack back to a specific destination. |
open Unit |
Removes an |
open Unit |
restoreState(@Nullable : Bundle?) Restores all navigation controller state from a bundle. |
open Bundle? |
Saves all navigation controller state to a Bundle. |
open Unit |
Sets the |
open Unit |
Sets the |
open Unit |
Sets the |
open Unit |
Sets the |
Extension functions |
||||
---|---|---|---|---|
From androidx.navigation
|
||||
From androidx.navigation.ui
|
Constants
KEY_DEEP_LINK_INTENT
@NonNull static val KEY_DEEP_LINK_INTENT: String
The Intent
that triggered a deep link to the current destination.
Value: "android-support-nav:controller:deepLinkIntent"
Public constructors
<init>
NavController(@NonNull : 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
open fun addOnDestinationChangedListener(@NonNull : NavController.OnDestinationChangedListener): Unit
Adds an 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
@NonNull open fun createDeepLink(): NavDeepLinkBuilder
Create a deep link to a destination within this NavController.
Return | |
---|---|
NavDeepLinkBuilder: a NavDeepLinkBuilder suitable for constructing a deep link |
getBackStackEntry
@NonNull open fun getBackStackEntry(@IdRes : Int): NavBackStackEntry
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 |
Exceptions | |
---|---|
IllegalArgumentException |
if the destination is not on the back stack |
getCurrentDestination
@Nullable open fun getCurrentDestination(): NavDestination?
Gets the current destination.
getGraph
@NonNull open fun getGraph(): NavGraph
Gets the topmost navigation graph associated with this NavController.
Exceptions | |
---|---|
IllegalStateException |
if called before setGraph() . |
See Also
getNavInflater
@NonNull open fun getNavInflater(): NavInflater
Returns the inflater
for this controller.
Return | |
---|---|
NavInflater: inflater for loading navigation resources |
getNavigatorProvider
@NonNull open fun getNavigatorProvider(): NavigatorProvider
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.
Return | |
---|---|
NavigatorProvider: The NavigatorProvider used by this NavController. |
getViewModelStoreOwner
@NonNull open fun getViewModelStoreOwner(@IdRes : Int): ViewModelStoreOwner
Gets the ViewModelStoreOwner
for a NavGraph. This can be passed to androidx.lifecycle.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 |
Exceptions | |
---|---|
IllegalStateException |
if called before the NavHost has called NavHostController#setViewModelStore . |
IllegalArgumentException |
if the NavGraph is not on the back stack |
handleDeepLink
open fun handleDeepLink(@Nullable : Intent?): Boolean
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 |
Return | |
---|---|
Boolean: True if the navigation controller found a valid deep link and navigated to it. |
See Also
navigate
open fun navigate(@IdRes : Int): Unit
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
open fun navigate(@IdRes : Int, @Nullable : Bundle?): Unit
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 |
Int: arguments to pass to the destination |
navigate
open fun navigate(@IdRes : Int, @Nullable : Bundle?, @Nullable : NavOptions?): Unit
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 |
Int: arguments to pass to the destination |
navOptions |
Int: special options for this navigation operation |
navigate
open fun navigate(@IdRes : Int, @Nullable : Bundle?, @Nullable : NavOptions?, @Nullable : Navigator.Extras?): Unit
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 |
Int: arguments to pass to the destination |
navOptions |
Int: special options for this navigation operation |
navigatorExtras |
Int: extras to pass to the Navigator |
navigate
open fun navigate(@NonNull : Uri): Unit
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
open fun navigate(@NonNull : Uri, @Nullable : NavOptions?): Unit
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 |
Uri: special options for this navigation operation |
navigate
open fun navigate(@NonNull : Uri, @Nullable : NavOptions?, @Nullable : Navigator.Extras?): Unit
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 |
Uri: special options for this navigation operation |
navigatorExtras |
Uri: extras to pass to the Navigator |
navigate
open fun navigate(@NonNull : NavDirections): Unit
Navigate via the given NavDirections
Parameters | |
---|---|
directions |
NavDirections: directions that describe this navigation operation |
navigate
open fun navigate(@NonNull : NavDirections, @Nullable : NavOptions?): Unit
Navigate via the given NavDirections
Parameters | |
---|---|
directions |
NavDirections: directions that describe this navigation operation |
navOptions |
NavDirections: special options for this navigation operation |
navigate
open fun navigate(@NonNull : NavDirections, @NonNull : Navigator.Extras): Unit
Navigate via the given NavDirections
Parameters | |
---|---|
directions |
NavDirections: directions that describe this navigation operation |
navigatorExtras |
NavDirections: extras to pass to the Navigator |
navigateUp
open fun navigateUp(): Boolean
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.
Return | |
---|---|
Boolean: true if navigation was successful, false otherwise |
popBackStack
open fun popBackStack(): Boolean
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.
Return | |
---|---|
Boolean: true if the stack was popped and the user has been navigated to another destination, false otherwise |
popBackStack
open fun popBackStack(@IdRes : Int, : Boolean): Boolean
Attempts to pop the controller's back stack back to a specific destination.
Parameters | |
---|---|
destinationId |
Int: The topmost destination to retain |
inclusive |
Int: Whether the given destination should also be popped. |
Return | |
---|---|
Boolean: true if the stack was popped at least once and the user has been navigated to another destination, false otherwise |
removeOnDestinationChangedListener
open fun removeOnDestinationChangedListener(@NonNull : NavController.OnDestinationChangedListener): Unit
Removes an OnDestinationChangedListener
from this controller. It will no longer receive callbacks.
Parameters | |
---|---|
listener |
NavController.OnDestinationChangedListener: the listener to remove |
restoreState
@CallSuper open fun restoreState(@Nullable : Bundle?): Unit
Restores all navigation controller state from a bundle. This should be called before any call to setGraph
.
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
@CallSuper @Nullable open fun saveState(): Bundle?
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
.
Return | |
---|---|
Bundle?: saved state for this controller |
setGraph
@CallSuper open fun setGraph(@NavigationRes : Int): Unit
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
@CallSuper open fun setGraph(@NavigationRes : Int, @Nullable : Bundle?): Unit
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 |
Int: arguments to send to the start destination of the graph |
setGraph
@CallSuper open fun setGraph(@NonNull : NavGraph): Unit
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
setGraph
@CallSuper open fun setGraph(@NonNull : NavGraph, @Nullable : Bundle?): Unit
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