NavDestination

public class NavDestination


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.

NavDestinations should be created via Navigator.createDestination.

Summary

Nested types

NavDestination.ClassType

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

NavDestination.Companion
NavDestination.DeepLinkMatch

Public fields

final @NonNull Map<@NonNull String, @NonNull NavArgument>

The arguments supported by this destination.

@NonNull String
final int

The destination's unique ID.

final @Nullable CharSequence

The descriptive label of this destination.

final @NonNull String

The name associated with this destination's Navigator.

final @Nullable NavGraph

Gets the NavGraph that contains this destination.

final @Nullable String

The destination's unique route.

Public constructors

NavDestinations should be created via Navigator.createDestination.

NavDestination(@NonNull String navigatorName)

Public methods

final void
addArgument(@NonNull String argumentName, @NonNull NavArgument argument)

Sets an argument type for an argument name

final void
addDeepLink(@NonNull String uriPattern)

Add a deep link to this destination.

final void

Add a deep link to this destination.

final @RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) @Nullable Bundle

Combines the default arguments for this destination with the arguments provided to construct the final set of arguments that should be used to navigate to this destination.

final @RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) @NonNull int[]
buildDeepLinkIds(@Nullable NavDestination previousDestination)

Build an array containing the hierarchy from the root down to this destination.

final @Nullable NavAction
getAction(@IdRes int id)

Returns the NavAction for the given action ID.

boolean
hasDeepLink(@NonNull Uri deepLink)

Checks the given deep link Uri, and determines whether it matches a Uri pattern added to the destination by a call to addDeepLink .

boolean

Checks the given NavDeepLinkRequest, and determines whether it matches a NavDeepLink added to the destination by a call to addDeepLink.

@RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) @Nullable NavDestination.DeepLinkMatch

Determines if this NavDestination has a deep link matching the given Uri.

@CallSuper void

Called when inflating a destination from a resource.

final void
putAction(@IdRes int actionId, @IdRes int destId)

Creates a NavAction for the given destId and associates it with the actionId.

final void
putAction(@IdRes int actionId, @NonNull NavAction action)

Sets the NavAction destination for an action ID.

final void
removeAction(@IdRes int actionId)

Unsets the NavAction for an action ID.

final void
removeArgument(@NonNull String argumentName)

Unsets the argument type for an argument name.

@RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) boolean
@NonNull String

Public fields

arguments

@NonNull
public final @NonNull Map<@NonNull String, @NonNull NavArgumentarguments

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 and removeArgument.

Returns
@NonNull Map<@NonNull String, @NonNull NavArgument>

Read-only map of argument names to arguments.

displayName

@NonNull
public @NonNull String displayName

id

@NonNull
public final int id

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

label

@Nullable
public final @Nullable CharSequence label

The descriptive label of this destination.

@NonNull
public final @NonNull String navigatorName

The name associated with this destination's Navigator.

parent

@Nullable
public final @Nullable NavGraph parent

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

route

@Nullable
public final @Nullable String route

The destination's unique route. Setting this will also update the id of the destinations so custom destination ids should only be set after setting the route.

Returns
@Nullable String

this destination's route, or null if no route is set

Throws
kotlin.IllegalArgumentException

is the given route is empty

Public constructors

@NonNull
public final NavDestination(@NonNull Navigator<@NonNull NavDestination> navigator)

NavDestinations should be created via Navigator.createDestination.

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

@NonNull
public final NavDestination(@NonNull String navigatorName)

Public methods

addArgument

@NonNull
public final void addArgument(@NonNull String argumentName, @NonNull NavArgument argument)

Sets an argument type for an argument name

Parameters
@NonNull String argumentName

argument object to associate with destination

@NonNull NavArgument argument

argument object to associate with destination

addDeepLink

@NonNull
public final void addDeepLink(@NonNull String uriPattern)

Add a deep link to this destination. Matching Uris sent to NavController.handleDeepLink or NavController.navigate 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
@NonNull String uriPattern

The uri pattern to add as a deep link

addDeepLink

@NonNull
public final void addDeepLink(@NonNull NavDeepLink navDeepLink)

Add a deep link to this destination. Uris that match the given NavDeepLink uri sent to NavController.handleDeepLink or NavController.navigate 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 or NavController.navigate 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
@NonNull NavDeepLink navDeepLink

The NavDeepLink to add as a deep link

addInDefaultArgs

@RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP])
@Nullable
public final @RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) Bundle addInDefaultArgs(@Nullable Bundle args)

Combines the default arguments for this destination with the arguments provided to construct the final set of arguments that should be used to navigate to this destination.

buildDeepLinkIds

@RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP])
@NonNull
public final @RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) int[] buildDeepLinkIds(@Nullable NavDestination previousDestination)

Build an array containing the hierarchy from the root down to this destination.

Parameters
@Nullable NavDestination previousDestination

the previous destination we are starting at

Returns
@RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) int[]

An array containing all of the ids from the previous destination (or the root of the graph if null) to this destination

getAction

@Nullable
public final NavAction getAction(@IdRes int id)

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

Parameters
@IdRes int id

action ID to fetch

Returns
NavAction

the NavAction mapped to the given action id, or null if one has not been set

hasDeepLink

@NonNull
public boolean hasDeepLink(@NonNull Uri deepLink)

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

This should be called prior to NavController.navigate to ensure the deep link can be navigated to.

Parameters
@NonNull Uri deepLink

to the destination reachable from the current NavGraph

Returns
boolean

True if the deepLink exists for the destination.

hasDeepLink

@NonNull
public boolean hasDeepLink(@NonNull NavDeepLinkRequest deepLinkRequest)

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

This should be called prior to NavController.navigate to ensure the deep link can be navigated to.

Parameters
@NonNull NavDeepLinkRequest deepLinkRequest

to the destination reachable from the current NavGraph

Returns
boolean

True if the deepLink exists for the destination.

matchDeepLink

@RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP])
@Nullable
public @RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) NavDestination.DeepLinkMatch matchDeepLink(@NonNull NavDeepLinkRequest navDeepLinkRequest)

Determines if this NavDestination has a deep link matching the given Uri.

Parameters
@NonNull NavDeepLinkRequest navDeepLinkRequest

The request to match against all deep links added in addDeepLink

Returns
@RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) NavDestination.DeepLinkMatch

The matching NavDestination and the appropriate Bundle of arguments extracted from the Uri, or null if no match was found.

onInflate

@CallSuper
@NonNull
public @CallSuper void onInflate(@NonNull Context context, @NonNull AttributeSet attrs)

Called when inflating a destination from a resource.

Parameters
@NonNull Context context

local context performing inflation

@NonNull AttributeSet attrs

attrs to parse during inflation

putAction

@NonNull
public final void putAction(@IdRes int actionId, @IdRes int destId)

Creates a NavAction for the given destId and associates it with the actionId.

Parameters
@IdRes int actionId

action ID to bind

@IdRes int destId

destination ID for the given action

putAction

@NonNull
public final void putAction(@IdRes int actionId, @NonNull NavAction action)

Sets the NavAction destination for an action ID.

Parameters
@IdRes int actionId

action ID to bind

@NonNull NavAction action

action to associate with this action ID

Throws
kotlin.UnsupportedOperationException

this destination is considered a terminal destination and does not support actions

removeAction

@NonNull
public final void removeAction(@IdRes int actionId)

Unsets the NavAction for an action ID.

Parameters
@IdRes int actionId

action ID to remove

removeArgument

@NonNull
public final void removeArgument(@NonNull String argumentName)

Unsets the argument type for an argument name.

Parameters
@NonNull String argumentName

argument to remove

supportsActions

@RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP])
@NonNull
public @RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) boolean supportsActions()
Returns
@RestrictTo(value = [RestrictTo.Scope.LIBRARY_GROUP]) boolean

Whether this NavDestination supports outgoing actions

See also
putAction

toString

@NonNull
public String toString()