NavDestination

Kotlin |Java

open class NavDestination

kotlin.Any
↳	androidx.navigation.NavDestination

Known Direct Subclasses ActivityNavigator.Destination, DialogFragmentNavigator.Destination, DynamicIncludeGraphNavigator.DynamicIncludeNavGraph, FragmentNavigator.Destination, NavGraph ActivityNavigator.Destination NavDestination for activity navigation DialogFragmentNavigator.Destination NavDestination specific to DialogFragmentNavigator. DynamicIncludeGraphNavigator.DynamicIncludeNavGraph The graph for dynamic-include. FragmentNavigator.Destination NavDestination specific to FragmentNavigator NavGraph NavGraph is a collection of NavDestination nodes fetchable by ID.

Known Indirect Subclasses DynamicActivityNavigator.Destination, DynamicFragmentNavigator.Destination, DynamicGraphNavigator.DynamicNavGraph DynamicActivityNavigator.Destination Destination for DynamicActivityNavigator. DynamicFragmentNavigator.Destination Destination for dynamic feature navigator. DynamicGraphNavigator.DynamicNavGraph The NavGraph for dynamic features.

NavDestination represents one node within an overall navigation graph.

Each destination is associated with a Navigator which knows how to navigate to this particular destination.

Destinations declare a set of actions that they support. These actions form a navigation API for the destination; the same actions declared on different destinations that fill similar roles allow application code to navigate based on semantic intent.

Each destination has a set of arguments that will be applied when navigating to that destination. Any default values for those arguments can be overridden at the time of navigation.

Summary

Nested classes
	ClassType This optional annotation allows tooling to offer auto-complete for the android:name attribute.

Public constructors
<init>(@NonNull navigator: Navigator<out NavDestination!>) NavDestinations should be created via Navigator#createDestination.
<init>(@NonNull navigatorName: String) NavDestinations should be created via Navigator#createDestination.

Public methods
Unit	addArgument(@NonNull argumentName: String, @NonNull argument: NavArgument) Sets an argument type for an argument name
Unit	addDeepLink(@NonNull uriPattern: String) Add a deep link to this destination.
Unit	addDeepLink(@NonNull navDeepLink: NavDeepLink) Add a deep link to this destination.
NavAction?	getAction(@IdRes id: Int) Returns the destination ID for a given action.
MutableMap<String!, NavArgument!>	getArguments() Get the arguments supported by this destination.
Int	getId() Returns the destination's unique ID.
CharSequence?	getLabel() Gets the descriptive label of this destination.
String	getNavigatorName() Returns the name associated with this destination's Navigator.
NavGraph?	getParent() Gets the NavGraph that contains this destination.
open Boolean	hasDeepLink(@NonNull deepLink: Uri) Checks the given deep link Uri, and determines whether it matches a Uri pattern added to the destination by a call to addDeepLink(String) .
open Boolean	hasDeepLink(@NonNull deepLinkRequest: NavDeepLinkRequest) Checks the given NavDeepLinkRequest, and determines whether it matches a NavDeepLink added to the destination by a call to addDeepLink(NavDeepLink).
open Unit	onInflate(@NonNull context: Context, @NonNull attrs: AttributeSet) Called when inflating a destination from a resource.
Unit	putAction(@IdRes actionId: Int, @IdRes destId: Int) Sets a destination ID for an action ID.
Unit	putAction(@IdRes actionId: Int, @NonNull action: NavAction) Sets a destination ID for an action ID.
Unit	removeAction(@IdRes actionId: Int) Unsets the destination ID for an action ID.
Unit	removeArgument(@NonNull argumentName: String) Unsets the argument type for an argument name.
Unit	setId(@IdRes id: Int) Sets the destination's unique ID.
Unit	setLabel(@Nullable label: CharSequence?) Sets the descriptive label of this destination.
open String	toString()

Protected methods
open static Class<out C>	parseClassFromName(@NonNull context: Context, @NonNull name: String, @NonNull expectedClassType: Class<out C>) Parse the class associated with this destination from a raw name, generally extracted from the android:name attribute added to the destination's XML.

Public constructors

<init>

NavDestination(@NonNull navigator: Navigator<out NavDestination!>)

NavDestinations should be created via Navigator#createDestination.

This constructor requires that the given Navigator has a Navigator.Name annotation.

<init>

NavDestination(@NonNull navigatorName: String)

NavDestinations should be created via Navigator#createDestination.

Public methods

addArgument

fun addArgument(
    @NonNull argumentName: String, 
    @NonNull argument: NavArgument
): Unit

Sets an argument type for an argument name

Parameters
argumentName	String: argument object to associate with destination

addDeepLink

fun addDeepLink(@NonNull uriPattern: String): Unit

Add a deep link to this destination. Matching Uris sent to NavController#handleDeepLink(Intent) or NavController#navigate(Uri) will trigger navigating to this destination.

In addition to a direct Uri match, the following features are supported:

• Uris without a scheme are assumed as http and https. For example, www.example.com will match http://www.example.com and https://www.example.com.
• Placeholders in the form of {placeholder_name} matches 1 or more characters. The String value of the placeholder will be available in the arguments Bundle with a key of the same name. For example, http://www.example.com/users/{id} will match http://www.example.com/users/4.
• The .* wildcard can be used to match 0 or more characters.

These Uris can be declared in your navigation XML files by adding one or more <deepLink app:uri="uriPattern" /> elements as a child to your destination.

Deep links added in navigation XML files will automatically replace instances of ${applicationId} with the applicationId of your app. Programmatically added deep links should use Context#getPackageName() directly when constructing the uriPattern.

Parameters
uriPattern	String: The uri pattern to add as a deep link

See Also

• NavController#handleDeepLink(Intent)
• NavController#navigate(Uri)
• #addDeepLink(NavDeepLink)

addDeepLink

fun addDeepLink(@NonNull navDeepLink: NavDeepLink): Unit

Add a deep link to this destination. Uris that match the given NavDeepLink uri sent to NavController#handleDeepLink(Intent) or NavController#navigate(NavDeepLinkRequest) will trigger navigating to this destination.

In addition to a direct Uri match, the following features are supported:

• Uris without a scheme are assumed as http and https. For example, www.example.com will match http://www.example.com and https://www.example.com.
• Placeholders in the form of {placeholder_name} matches 1 or more characters. The String value of the placeholder will be available in the arguments Bundle with a key of the same name. For example, http://www.example.com/users/{id} will match http://www.example.com/users/4.
• The .* wildcard can be used to match 0 or more characters.

These Uris can be declared in your navigation XML files by adding one or more <deepLink app:uri="uriPattern" /> elements as a child to your destination.

Custom actions and mimetypes are also supported by NavDeepLink and can be declared in your navigation XML files by adding <app:action="android.intent.action.SOME_ACTION" /> or <app:mimetype="type/subtype" /> as part of your deepLink declaration.

Deep link Uris, actions, and mimetypes added in navigation XML files will automatically replace instances of ${applicationId} with the applicationId of your app. Programmatically added deep links should use Context#getPackageName() directly when constructing the uriPattern.

When matching deep links for calls to NavController#handleDeepLink(Intent) or NavController#navigate(NavDeepLinkRequest) the order of precedence is as follows: the deep link with the most matching arguments will be chosen, followed by the deep link with a matching action, followed by the best matching mimeType (e.i. when matching mimeType image/jpg: image/* > *\/jpg > *\/*).

Parameters
navDeepLink	NavDeepLink: The NavDeepLink to add as a deep link

See Also

• NavController#handleDeepLink(Intent)
• NavController#navigate(NavDeepLinkRequest)

getAction

@Nullable fun getAction(@IdRes id: Int): NavAction?

Returns the destination ID for a given action. This will recursively check the parent of this destination if the action destination is not found in this destination.

Parameters
id	Int: action ID to fetch

Return
NavAction?	destination ID mapped to the given action id, or 0 if none

getArguments

@NonNull fun getArguments(): MutableMap<String!, NavArgument!>

Get the arguments supported by this destination. Returns a read-only map of argument names to NavArgument objects that can be used to check the type, default value and nullability of the argument.

To add and remove arguments for this NavDestination use addArgument(String, NavArgument) and removeArgument(String).

Return
MutableMap<String!, NavArgument!>	Read-only map of argument names to arguments.

getId

@IdRes fun getId(): Int

Returns the destination's unique ID. This should be an ID resource generated by the Android resource system.

Return
Int	this destination's ID

getLabel

@Nullable fun getLabel(): CharSequence?

Gets the descriptive label of this destination.

getNavigatorName

@NonNull fun getNavigatorName(): String

Returns the name associated with this destination's Navigator.

Return
String	the name associated with this destination's navigator

getParent

@Nullable fun getParent(): NavGraph?

Gets the NavGraph that contains this destination. This will be set when a destination is added to a NavGraph via NavGraph#addDestination.

Return
NavGraph?

hasDeepLink

open fun hasDeepLink(@NonNull deepLink: Uri): Boolean

Checks the given deep link Uri, and determines whether it matches a Uri pattern added to the destination by a call to addDeepLink(String) . It returns true if the deep link is a valid match, and false otherwise.

This should be called prior to NavController#navigate(Uri) to ensure the deep link can be navigated to.

Parameters
deepLink	Uri: to the destination reachable from the current NavGraph

Return
Boolean	True if the deepLink exists for the destination.

See Also

• #addDeepLink(String)
• NavController#navigate(Uri)
• #hasDeepLink(NavDeepLinkRequest)

hasDeepLink

open fun hasDeepLink(@NonNull deepLinkRequest: NavDeepLinkRequest): Boolean

Checks the given NavDeepLinkRequest, and determines whether it matches a NavDeepLink added to the destination by a call to addDeepLink(NavDeepLink). It returns true if the request is a valid match, and false otherwise.

This should be called prior to NavController#navigate(NavDeepLinkRequest) to ensure the deep link can be navigated to.

Parameters
deepLinkRequest	NavDeepLinkRequest: to the destination reachable from the current NavGraph

Return
Boolean	True if the deepLink exists for the destination.

See Also

• #addDeepLink(NavDeepLink)
• NavController#navigate(NavDeepLinkRequest)

onInflate

@CallSuper open fun onInflate(
    @NonNull context: Context, 
    @NonNull attrs: AttributeSet
): Unit

Called when inflating a destination from a resource.

Parameters
context	Context: local context performing inflation
attrs	AttributeSet: attrs to parse during inflation

putAction

fun putAction(
    @IdRes actionId: Int, 
    @IdRes destId: Int
): Unit

Sets a destination ID for an action ID.

Parameters
actionId	Int: action ID to bind
destId	Int: destination ID for the given action

putAction

fun putAction(
    @IdRes actionId: Int, 
    @NonNull action: NavAction
): Unit

Sets a destination ID for an action ID.

Parameters
actionId	Int: action ID to bind
action	NavAction: action to associate with this action ID

removeAction

fun removeAction(@IdRes actionId: Int): Unit

Unsets the destination ID for an action ID.

Parameters
actionId	Int: action ID to remove

removeArgument

fun removeArgument(@NonNull argumentName: String): Unit

Unsets the argument type for an argument name.

Parameters
argumentName	String: argument to remove

setId

fun setId(@IdRes id: Int): Unit

Sets the destination's unique ID. This should be an ID resource generated by the Android resource system.

Parameters
id	Int: this destination's new ID

setLabel

fun setLabel(@Nullable label: CharSequence?): Unit

Sets the descriptive label of this destination.

Parameters
label	CharSequence?: A descriptive label of this destination.

toString

@NonNull open fun toString(): String

Protected methods

parseClassFromName

@NonNull protected open static fun <C : Any!> parseClassFromName(
    @NonNull context: Context, 
    @NonNull name: String, 
    @NonNull expectedClassType: Class<out C>
): Class<out C>

Parse the class associated with this destination from a raw name, generally extracted from the android:name attribute added to the destination's XML. This should be the class providing the visual representation of the destination that the user sees after navigating to this destination.

This method does name -> Class caching and should be strongly preferred over doing your own parsing if your Navigator supports the android:name attribute to give consistent behavior across all Navigators.

Parameters
context	Context: Context providing the package name for use with relative class names and the ClassLoader
name	String: Absolute or relative class name. Null names will be ignored.
expectedClassType	Class<out C>: The expected class type

Return
Class<out C>	The parsed class

Exceptions
IllegalArgumentException	if the class is not found in the provided Context's ClassLoader or if the class is not of the expected type