1 /*
2 * Copyright 2018 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 @file:JvmName("NavHostKt")
18 @file:JvmMultifileClass
19
20 package androidx.navigation
21
22 import kotlin.jvm.JvmMultifileClass
23 import kotlin.jvm.JvmName
24 import kotlin.jvm.JvmSuppressWildcards
25 import kotlin.reflect.KClass
26 import kotlin.reflect.KType
27
28 /**
29 * A host is a single context or container for navigation via a [NavController].
30 *
31 * It is strongly recommended to construct the nav controller by instantiating a
32 * [NavHostController], which offers additional APIs specifically for a NavHost. The
33 * NavHostController should still only be externally accessible as a [NavController], rather than
34 * directly exposing it as a [NavHostController].
35 *
36 * Navigation hosts must:
37 * * Handle [saving][NavController.saveState] and [restoring][NavController.restoreState] their
38 * controller's state
39 * * Call [Navigation.setViewNavController] on their root view
40 * * Route system Back button events to the NavController either by manually calling
41 * [NavController.popBackStack] or by calling [NavHostController.setOnBackPressedDispatcher] when
42 * constructing the NavController.
43 *
44 * Optionally, a navigation host should consider calling:
45 * * Call [NavHostController.setLifecycleOwner] to associate the NavController with a specific
46 * Lifecycle.
47 * * Call [NavHostController.setViewModelStore] to enable usage of
48 * [NavController.getViewModelStoreOwner] and navigation graph scoped ViewModels.
49 */
50 public interface NavHost {
51 /** The [navigation controller][NavController] for this navigation host. */
52 public val navController: NavController
53 }
54
55 /** Construct a new [NavGraph] */
createGraphnull56 public inline fun NavHost.createGraph(
57 startDestination: String,
58 route: String? = null,
59 builder: NavGraphBuilder.() -> Unit
60 ): NavGraph = navController.createGraph(startDestination, route, builder)
61
62 /**
63 * Construct a new [NavGraph]
64 *
65 * @param startDestination the starting destination's route from a [KClass] for this NavGraph. The
66 * respective NavDestination must be added as a [KClass] in order to match.
67 * @param route the graph's unique route from a [KClass]
68 * @param typeMap A mapping of KType to custom NavType<*> in the [route]. May be empty if [route]
69 * does not use custom NavTypes.
70 * @param builder the builder used to construct the graph
71 */
72 public inline fun NavHost.createGraph(
73 startDestination: KClass<*>,
74 route: KClass<*>? = null,
75 typeMap: Map<KType, @JvmSuppressWildcards NavType<*>> = emptyMap(),
76 builder: NavGraphBuilder.() -> Unit
77 ): NavGraph = navController.createGraph(startDestination, route, typeMap, builder)
78
79 /**
80 * Construct a new [NavGraph]
81 *
82 * @param startDestination the starting destination's route from an Object for this NavGraph. The
83 * respective NavDestination must be added as a [KClass] in order to match.
84 * @param route the graph's unique route from a [KClass]
85 * @param typeMap A mapping of KType to custom NavType<*> in the [route]. May be empty if [route]
86 * does not use custom NavTypes.
87 * @param builder the builder used to construct the graph
88 */
89 public inline fun NavHost.createGraph(
90 startDestination: Any,
91 route: KClass<*>? = null,
92 typeMap: Map<KType, @JvmSuppressWildcards NavType<*>> = emptyMap(),
93 builder: NavGraphBuilder.() -> Unit
94 ): NavGraph = navController.createGraph(startDestination, route, typeMap, builder)
95