NavDestination

public class NavDestination

Known direct subclasses
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
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 putAction 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
public static class NavDestination.Companion

Public constructors
NavDestination(@NonNull String navigatorName)

NavDestinations should be created via Navigator.createDestination.

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

Sets an argument type for an argument name
final void

Add a deep link to this destination.
final void
addDeepLink(@NonNull String uriPattern)

Add a deep link to this destination.
final @NonNull Map<@NonNull String, @NonNull NavArgument>

The arguments supported by this destination.
@NonNull String
static final @NonNull Sequence<@NonNull NavDestination>

Provides a sequence of the NavDestination's hierarchy.
final CharSequence

The descriptive label of this destination.
final @NonNull String

The name associated with this destination's Navigator.
final NavGraph

Gets the NavGraph that contains this destination.
final String

The destination's unique route.
boolean

Checks the given deep link NavUri, 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.
static final boolean
<T extends Object> hasRoute(@NonNull NavDestination receiver)

Checks if the NavDestination's route was generated from T
static final boolean
<T extends Object> hasRoute(
    @NonNull NavDestination receiver,
    @NonNull KClass<@NonNull T> route
)

Checks if the NavDestination's route was generated from T
final void
removeArgument(@NonNull String argumentName)

Unsets the argument type for an argument name.
final void

The descriptive label of this destination.
final void

Gets the NavGraph that contains this destination.
final void

The destination's unique route.

Public constructors

Added in 1.0.0
public NavDestination(@NonNull String navigatorName)
Added in 1.0.0
public 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.

Public methods

addArgument

Added in 1.0.0
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

Added in 2.3.0
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 SavedState 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
See also
handleDeepLink
navigate

addDeepLink

Added in 1.0.0
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 parsed value of the placeholder will be available in the arguments SavedState 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
See also
handleDeepLink
navigate
addDeepLink

getArguments

Added in 1.0.0
public final @NonNull Map<@NonNull String, @NonNull NavArgument> getArguments()

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.

getDisplayName

public @NonNull String getDisplayName()

getHierarchy

Added in 2.4.0
public static final @NonNull Sequence<@NonNull NavDestination> getHierarchy(@NonNull NavDestination receiver)

Provides a sequence of the NavDestination's hierarchy. The hierarchy starts with this destination itself and is then followed by this destination's NavDestination.parent, then that graph's parent, and up the hierarchy until you've reached the root navigation graph.

getLabel

Added in 1.0.0
public final CharSequence getLabel()

The descriptive label of this destination.

getNavigatorName

Added in 1.0.0
public final @NonNull String getNavigatorName()

The name associated with this destination's Navigator.

getParent

Added in 1.0.0
public final NavGraph getParent()

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

getRoute

Added in 2.4.0
public final String getRoute()

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
String

this destination's route, or null if no route is set
Throws
kotlin.IllegalArgumentException

is the given route is empty

hasDeepLink

public boolean hasDeepLink(@NonNull NavUri deepLink)

Checks the given deep link NavUri, 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 NavUri deepLink

to the destination reachable from the current NavGraph
Returns
boolean

True if the deepLink exists for the destination.
See also
addDeepLink
navigate
hasDeepLink

hasDeepLink

Added in 2.3.0
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.
See also
addDeepLink
navigate

hasRoute

public static final boolean <T extends Object> hasRoute(@NonNull NavDestination receiver)

Checks if the NavDestination's route was generated from T

Returns true if equal, false otherwise.

Parameters
<T extends Object>

the route from KClass

hasRoute

Added in 2.8.0
public static final boolean <T extends Object> hasRoute(
    @NonNull NavDestination receiver,
    @NonNull KClass<@NonNull T> route
)

Checks if the NavDestination's route was generated from T

Returns true if equal, false otherwise.

Parameters
@NonNull KClass<@NonNull T> route

the route from KClass

removeArgument

Added in 1.0.0
public final void removeArgument(@NonNull String argumentName)

Unsets the argument type for an argument name.

Parameters
@NonNull String argumentName

argument to remove

setLabel

Added in 1.0.0
public final void setLabel(CharSequence label)

The descriptive label of this destination.

setParent

public final void setParent(NavGraph parent)

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

setRoute

Added in 2.4.0
public final void setRoute(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
void

this destination's route, or null if no route is set
Throws
kotlin.IllegalArgumentException

is the given route is empty