From 917a444bf0c56d7bdfad0415274e71d604a31c68 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Mon, 21 Jul 2025 15:16:50 +0100 Subject: [PATCH 01/64] Adding tests for Navigator --- app/build.gradle.kts | 1 + app/src/main/AndroidManifest.xml | 5 + .../navigator/basic/NavigatorActivity.kt | 184 ++++++++++++++++++ .../navigator/basic/NavigatorTest.kt | 76 ++++++++ 4 files changed, 266 insertions(+) create mode 100644 app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt create mode 100644 app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt diff --git a/app/build.gradle.kts b/app/build.gradle.kts index f1b2051..e42693a 100644 --- a/app/build.gradle.kts +++ b/app/build.gradle.kts @@ -91,4 +91,5 @@ dependencies { androidTestImplementation(libs.androidx.ui.test.junit4) debugImplementation(libs.androidx.ui.tooling) debugImplementation(libs.androidx.ui.test.manifest) + testImplementation(kotlin("test")) } \ No newline at end of file diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index e99f46a..dafb614 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -51,6 +51,11 @@ android:exported="true" android:label="@string/app_name" android:theme="@style/Theme.Nav3Recipes"/> + = listOf(Home, ChatList, Camera) + +class NavigatorActivity : ComponentActivity() { + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navigator = remember { Navigator(Home) } + + Scaffold( + bottomBar = { + NavigationBar { + TOP_LEVEL_ROUTES.forEach { topLevelRoute -> + + val isSelected = topLevelRoute == navigator.topLevelRoute + NavigationBarItem( + selected = isSelected, + onClick = { + navigator.navigate(topLevelRoute) + }, + icon = { + Icon( + imageVector = topLevelRoute.icon, + contentDescription = null + ) + } + ) + } + } + } + ) { _ -> + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider { + entry{ + ContentRed("Home screen") + } + entry{ + ContentGreen("Chat list screen"){ + Button(onClick = { navigator.navigate(ChatDetail) }) { + Text("Go to conversation") + } + } + } + entry{ + ContentBlue("Chat detail screen") + } + entry{ + ContentPurple("Camera screen") + } + }, + ) + } + } + } +} + +class Navigator( + startRoute: T, + private val canStartRouteMove: Boolean = false, + private val shouldPopOtherTopLevelRoutesWhenNavigatingToTopLevelRoute: Boolean = true, + private val shouldRemoveChildRoutesWhenNavigatingBack: Boolean = false +) { + + // Maintain a stack for each top level route + private var topLevelStacks : LinkedHashMap> = linkedMapOf( + startRoute to mutableStateListOf(startRoute) + ) + + // Expose the current top level route for consumers + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Expose the back stack so it can be rendered by the NavDisplay + val backStack = mutableStateListOf(startRoute) + + private fun updateBackStack() = + backStack.apply { + clear() + addAll(topLevelStacks.flatMap { it.value }) + } + + private fun navigateToTopLevel(key: T){ + + // Remove any other top level stacks first + if (shouldPopOtherTopLevelRoutesWhenNavigatingToTopLevelRoute) + topLevelStacks.keys.filter { it != key }.forEach { topLevelStacks.remove(it) } + + val doesStackExist = topLevelStacks.keys.contains(key) + + if (doesStackExist){ + // Move it to the end of the stacks + topLevelStacks.apply { + remove(key)?.let { + put(key, it) + } + } + } else { + topLevelStacks.put(key, mutableStateListOf(key)) + } + topLevelRoute = key + updateBackStack() + } + + fun navigate(key: T){ + if (key is Route.TopLevel){ + navigateToTopLevel(key) + } else { + topLevelStacks[topLevelRoute]?.add(key) + } + updateBackStack() + } + + fun goBack(){ + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + } + + interface Route { + interface TopLevel + interface Unique // Non-top level route that is unique on the back stack (can move between top level stacks) + } +} \ No newline at end of file diff --git a/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt new file mode 100644 index 0000000..5433f7b --- /dev/null +++ b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt @@ -0,0 +1,76 @@ +package com.example.nav3recipes.navigator.basic + +import androidx.compose.foundation.layout.add +import org.junit.Test +import kotlin.test.assertEquals + +class NavigatorTest { + + private data object Home : Navigator.Route.TopLevel + private data object ChatList : Navigator.Route.TopLevel + private data object ChatDetail + private data object Camera : Navigator.Route.TopLevel + private data object Search : Navigator.Route.Unique + + @Test + fun backStackContainsStartKey(){ + val navigator = Navigator(startRoute = Home) + assert(navigator.backStack.contains(Home)) + } + + @Test + fun navigatingToTopRoute_addsRouteToTopOfStack(){ + val navigator = Navigator(startRoute = Home) + + // Back stack start state [Home] + // Navigate to ChatList + // Expected back stack state [Home, ChatList] + navigator.navigate(ChatList) + assertEquals(listOf(Home, ChatList), navigator.backStack) + } + + @Test + fun addingNonTopLevelRoute_addsToCurrentTopLevelStack() { + val navigator = Navigator(startRoute = Home) // Current: Home, Stack: [Home] + + // Navigate to ChatList, making it the current top-level route + navigator.navigate(ChatList) + // Current: ChatList, Stack: [Home, ChatList] + assertEquals(listOf(Home, ChatList), navigator.backStack, "Backstack after adding ChatList") + assertEquals(ChatList, navigator.topLevelRoute, "Current top level route should be ChatList") + + // Add ChatDetail (non-top-level) to the ChatList stack + navigator.navigate(ChatDetail) + // Current: ChatList, Stack: [Home, ChatList, ChatDetail] + assertEquals(listOf(Home, ChatList, ChatDetail), navigator.backStack, "Backstack after adding ChatDetail") + } + + @Test + fun navigatingToNewTopLevel_withDefaultConfig_popsOtherTopLevelAndItsChildren() { + // Default config: shouldPopOtherTopLevelRoutesWhenNavigatingToTopLevelRoute = true + val navigator = Navigator(startRoute = Home) + navigator.navigate(Search) // BackStack: [Home, Search] + navigator.navigate(Camera) // BackStack: [Home, Search, Camera] + navigator.navigate(ChatList) + val expected = listOf(Home, Search, ChatList) // Camera is popped before ChatList is added + assertEquals(expected, navigator.backStack) + } + + @Test + fun navigatingToNewTopLevel_whenStartRouteCannotMove_popsOtherTopLevelStacksExceptStartRoute() { + val navigator = Navigator(startRoute = Home) + navigator.navigate(Camera) + val expected = listOf(Home, Camera) // Home is locked in place + assertEquals(expected, navigator.backStack) + } + + @Test + fun navigatingToNewTopLevel_whenStartRouteCanMove_popsAllOtherTopLevelStacks() { + val navigator = Navigator(startRoute = Home, canStartRouteMove = true) + navigator.navigate(Camera) + val expected = listOf(Camera) // Home is popped + assertEquals(expected, navigator.backStack) + } + + +} \ No newline at end of file From e88d4707dab0273f5f4eb3f1714916ca5d4c42e6 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Wed, 30 Jul 2025 23:23:33 +0100 Subject: [PATCH 02/64] First draft of Navigator for nested and shared destinations --- .../nav3recipes/navigator/basic/Navigator.kt | 123 ++++++++++++++++ .../navigator/basic/NavigatorActivity.kt | 129 +++++++---------- .../example/nav3recipes/ExampleUnitTest.kt | 33 ----- .../navigator/basic/NavigatorTest.kt | 132 ++++++++++++------ 4 files changed, 261 insertions(+), 156 deletions(-) create mode 100644 app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt delete mode 100644 app/src/test/java/com/example/nav3recipes/ExampleUnitTest.kt diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt new file mode 100644 index 0000000..d1d751a --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt @@ -0,0 +1,123 @@ +package com.example.nav3recipes.navigator.basic + +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue + +/** + * This class models navigation behavior. It provides a back stack + * as a Compose snapshot-state backed list that can be used with a `NavDisplay`. + * + * It supports a single level of nested navigation. Top level + * routes can be defined using the `Route` class and setting + * `isTopLevel` to `true`. It also supports shared routes. + * These are routes that can be nested under multiple top level + * routes, though only one instance of the route will ever be + * present in the stack. Shared routes can be defined using + * `Route.isShared`. + * + * The start route is always the first item in the back stack and + * cannot be moved. Navigating to the start route removes all other + * top level routes and their associated stacks. + * + * @param startRoute - The start route for the back stack. + * @param canTopLevelRoutesExistTogether - Determines whether other + * top level routes can exist together on the back stack. Default `false`, + * meaning other top level routes (and their stacks) will be popped off + * the back stack when navigating to a top level route. + * + * For example, if A, B and C are all top level routes: + * + * ``` + * val navigator = Navigator(startRoute = A) // back stack is [A] + * navigator.navigate(B) // back stack [A, B] + * navigator.navigate(C) // back stack [A, C] - B is popped before C is added + * + * When set to `true`, the resulting back stack would be [A, B, C] + * ``` + * + * @see `NavigatorTest`. + */ +class Navigator( + private val startRoute: T, + private val canTopLevelRoutesExistTogether: Boolean = false +) { + + val backStack = mutableStateListOf(startRoute) + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Maintain a stack for each top level route + private var topLevelStacks : LinkedHashMap> = linkedMapOf( + startRoute to mutableListOf(startRoute) + ) + + private fun updateBackStack() = + backStack.apply { + clear() + addAll(topLevelStacks.flatMap { it.value }) + } + + private fun navigateToTopLevel(route: T){ + + if (route == startRoute){ + clearAllExceptStartStack() + } else { + + // Get the existing stack or create a new one. + val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) + + if (!canTopLevelRoutesExistTogether) { + clearAllExceptStartStack() + } + + topLevelStacks.put(route, topLevelStack) + } + + topLevelRoute = route + } + + private fun clearAllExceptStartStack(){ + // Remove all other top level stacks, except the start stack + val startStack = topLevelStacks[startRoute]!! + topLevelStacks.clear() + topLevelStacks.put(startRoute, startStack) + } + + /** + * Navigate to the given route. + */ + fun navigate(route: T){ + if (route.isTopLevel){ + navigateToTopLevel(route) + } else { + if (route.isShared){ + // If the key is already in a stack, remove it + topLevelStacks.forEach { stack -> + if (stack.value.contains(route)){ + topLevelStacks[stack.key]?.remove(route) + } + } + } + topLevelStacks[topLevelRoute]?.add(route) + } + updateBackStack() + } + + /** + * Go back to the previous route. + */ + fun goBack(){ + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + } +} + +abstract class Route( + val isTopLevel : Boolean = false, + val isShared : Boolean = false +) \ No newline at end of file diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt index ce40ec4..decda42 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt @@ -19,41 +19,46 @@ package com.example.nav3recipes.navigator.basic import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent +import androidx.compose.foundation.layout.padding import androidx.compose.material.icons.Icons import androidx.compose.material.icons.filled.Face import androidx.compose.material.icons.filled.Home import androidx.compose.material.icons.filled.PlayArrow +import androidx.compose.material.icons.filled.Search import androidx.compose.material3.Button +import androidx.compose.material3.ExperimentalMaterial3Api import androidx.compose.material3.Icon +import androidx.compose.material3.IconButton import androidx.compose.material3.NavigationBar import androidx.compose.material3.NavigationBarItem import androidx.compose.material3.Scaffold import androidx.compose.material3.Text +import androidx.compose.material3.TextField +import androidx.compose.material3.TopAppBar +import androidx.compose.runtime.Composable import androidx.compose.runtime.getValue -import androidx.compose.runtime.mutableStateListOf import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember +import androidx.compose.runtime.saveable.rememberSaveable import androidx.compose.runtime.setValue -import androidx.compose.runtime.snapshots.SnapshotStateList +import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.vector.ImageVector import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.ui.NavDisplay import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.content.ContentPink import com.example.nav3recipes.content.ContentPurple import com.example.nav3recipes.content.ContentRed import com.example.nav3recipes.ui.setEdgeToEdgeConfig -import kotlin.collections.remove - -private sealed interface NavBarItem : Navigator.Route.TopLevel { - val icon: ImageVector -} -private data object Home : NavBarItem { override val icon = Icons.Default.Home } -private data object ChatList : NavBarItem { override val icon = Icons.Default.Face } -private data object ChatDetail -private data object Camera : NavBarItem { override val icon = Icons.Default.PlayArrow } +private abstract class NavBarItem(val icon: ImageVector): Route(isTopLevel = true) +private data object Home : NavBarItem(icon = Icons.Default.Home) +private data object ChatList : NavBarItem(icon = Icons.Default.Face) +private data object ChatDetail : Route() +private data object Camera : NavBarItem(icon = Icons.Default.PlayArrow) +private data object Search : Route(isShared = true) private val TOP_LEVEL_ROUTES : List = listOf(Home, ChatList, Camera) @@ -62,9 +67,12 @@ class NavigatorActivity : ComponentActivity() { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) setContent { - val navigator = remember { Navigator(Home) } + val navigator = remember { Navigator(Home) } Scaffold( + topBar = { + TopAppBarWithSearch { navigator.navigate(Search) } + }, bottomBar = { NavigationBar { TOP_LEVEL_ROUTES.forEach { topLevelRoute -> @@ -85,8 +93,9 @@ class NavigatorActivity : ComponentActivity() { } } } - ) { _ -> + ) { paddingValues -> NavDisplay( + modifier = Modifier.padding(paddingValues), backStack = navigator.backStack, onBack = { navigator.goBack() }, entryProvider = entryProvider { @@ -102,10 +111,22 @@ class NavigatorActivity : ComponentActivity() { } entry{ ContentBlue("Chat detail screen") + } entry{ ContentPurple("Camera screen") } + entry{ + ContentPink("Search screen"){ + var text by rememberSaveable { mutableStateOf("") } + TextField( + value = text, + onValueChange = { newText -> text = newText}, + label = { Text("Enter search here") }, + singleLine = true + ) + } + } }, ) } @@ -113,72 +134,24 @@ class NavigatorActivity : ComponentActivity() { } } -class Navigator( - startRoute: T, - private val canStartRouteMove: Boolean = false, - private val shouldPopOtherTopLevelRoutesWhenNavigatingToTopLevelRoute: Boolean = true, - private val shouldRemoveChildRoutesWhenNavigatingBack: Boolean = false +@OptIn(ExperimentalMaterial3Api::class) +@Composable +fun TopAppBarWithSearch( + onSearchClick: () -> Unit ) { - - // Maintain a stack for each top level route - private var topLevelStacks : LinkedHashMap> = linkedMapOf( - startRoute to mutableStateListOf(startRoute) - ) - - // Expose the current top level route for consumers - var topLevelRoute by mutableStateOf(startRoute) - private set - - // Expose the back stack so it can be rendered by the NavDisplay - val backStack = mutableStateListOf(startRoute) - - private fun updateBackStack() = - backStack.apply { - clear() - addAll(topLevelStacks.flatMap { it.value }) - } - - private fun navigateToTopLevel(key: T){ - - // Remove any other top level stacks first - if (shouldPopOtherTopLevelRoutesWhenNavigatingToTopLevelRoute) - topLevelStacks.keys.filter { it != key }.forEach { topLevelStacks.remove(it) } - - val doesStackExist = topLevelStacks.keys.contains(key) - - if (doesStackExist){ - // Move it to the end of the stacks - topLevelStacks.apply { - remove(key)?.let { - put(key, it) - } + TopAppBar( + title = { + Text("Navigator Activity") + }, + actions = { + IconButton(onClick = onSearchClick) { + Icon( + imageVector = Icons.Filled.Search, + contentDescription = "Search" + ) } - } else { - topLevelStacks.put(key, mutableStateListOf(key)) - } - topLevelRoute = key - updateBackStack() - } - fun navigate(key: T){ - if (key is Route.TopLevel){ - navigateToTopLevel(key) - } else { - topLevelStacks[topLevelRoute]?.add(key) - } - updateBackStack() - } - - fun goBack(){ - val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() - // If the removed key was a top level key, remove the associated top level stack - topLevelStacks.remove(removedKey) - topLevelRoute = topLevelStacks.keys.last() - updateBackStack() - } + }, + ) +} - interface Route { - interface TopLevel - interface Unique // Non-top level route that is unique on the back stack (can move between top level stacks) - } -} \ No newline at end of file diff --git a/app/src/test/java/com/example/nav3recipes/ExampleUnitTest.kt b/app/src/test/java/com/example/nav3recipes/ExampleUnitTest.kt deleted file mode 100644 index 32b7a81..0000000 --- a/app/src/test/java/com/example/nav3recipes/ExampleUnitTest.kt +++ /dev/null @@ -1,33 +0,0 @@ -/* - * Copyright 2025 The Android Open Source Project - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package com.example.nav3recipes - -import org.junit.Test - -import org.junit.Assert.* - -/** - * Example local unit test, which will execute on the development machine (host). - * - * See [testing documentation](http://d.android.com/tools/testing). - */ -class ExampleUnitTest { - @Test - fun addition_isCorrect() { - assertEquals(4, 2 + 2) - } -} \ No newline at end of file diff --git a/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt index 5433f7b..783a202 100644 --- a/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt +++ b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt @@ -1,76 +1,118 @@ package com.example.nav3recipes.navigator.basic -import androidx.compose.foundation.layout.add import org.junit.Test import kotlin.test.assertEquals +import kotlin.test.assertFailsWith class NavigatorTest { - private data object Home : Navigator.Route.TopLevel - private data object ChatList : Navigator.Route.TopLevel - private data object ChatDetail - private data object Camera : Navigator.Route.TopLevel - private data object Search : Navigator.Route.Unique + private data object A : Route(isTopLevel = true) + + private data object A1 : Route() + private data object B : Route(isTopLevel = true) + private data object B1 : Route() + private data object C : Route(isTopLevel = true) + private data object D : Route(isShared = true) @Test - fun backStackContainsStartKey(){ - val navigator = Navigator(startRoute = Home) - assert(navigator.backStack.contains(Home)) + fun backStackContainsOnlyStartRoute(){ + val navigator = Navigator(startRoute = A) + assertEquals(listOf(A), navigator.backStack) } @Test - fun navigatingToTopRoute_addsRouteToTopOfStack(){ - val navigator = Navigator(startRoute = Home) - - // Back stack start state [Home] - // Navigate to ChatList - // Expected back stack state [Home, ChatList] - navigator.navigate(ChatList) - assertEquals(listOf(Home, ChatList), navigator.backStack) + fun navigatingToTopLevelRoute_addsRouteToTopOfStack(){ + val navigator = Navigator(startRoute = A) + navigator.navigate(B) + assertEquals(listOf(A, B), navigator.backStack) } @Test - fun addingNonTopLevelRoute_addsToCurrentTopLevelStack() { - val navigator = Navigator(startRoute = Home) // Current: Home, Stack: [Home] - - // Navigate to ChatList, making it the current top-level route - navigator.navigate(ChatList) - // Current: ChatList, Stack: [Home, ChatList] - assertEquals(listOf(Home, ChatList), navigator.backStack, "Backstack after adding ChatList") - assertEquals(ChatList, navigator.topLevelRoute, "Current top level route should be ChatList") - - // Add ChatDetail (non-top-level) to the ChatList stack - navigator.navigate(ChatDetail) - // Current: ChatList, Stack: [Home, ChatList, ChatDetail] - assertEquals(listOf(Home, ChatList, ChatDetail), navigator.backStack, "Backstack after adding ChatDetail") + fun navigatingToChildRoute_addsToCurrentTopLevelStack() { + val navigator = Navigator(startRoute = A) + navigator.navigate(B) + navigator.navigate(B1) + assertEquals(listOf(A, B, B1), navigator.backStack) + } + + @Test + fun navigatingToNewTopLevelRoute_popsOtherTopLevelStacks() { + val navigator = Navigator(startRoute = A) + navigator.navigate(A1) // [A, A1] + navigator.navigate(C) // [A, A1, C] + navigator.navigate(B) // [A, A1, B] + val expected = listOf(A, A1, B) + assertEquals(expected, navigator.backStack) } @Test - fun navigatingToNewTopLevel_withDefaultConfig_popsOtherTopLevelAndItsChildren() { - // Default config: shouldPopOtherTopLevelRoutesWhenNavigatingToTopLevelRoute = true - val navigator = Navigator(startRoute = Home) - navigator.navigate(Search) // BackStack: [Home, Search] - navigator.navigate(Camera) // BackStack: [Home, Search, Camera] - navigator.navigate(ChatList) - val expected = listOf(Home, Search, ChatList) // Camera is popped before ChatList is added + fun navigatingToSharedRoute_whenItsAlreadyOnStack_movesItToNewStack() { + val navigator = Navigator(startRoute = A) + navigator.navigate(D) // [A, D] + navigator.navigate(C) // [A, D, C] + navigator.navigate(D) // [A, C, D] + val expected = listOf(A, C, D) assertEquals(expected, navigator.backStack) } @Test - fun navigatingToNewTopLevel_whenStartRouteCannotMove_popsOtherTopLevelStacksExceptStartRoute() { - val navigator = Navigator(startRoute = Home) - navigator.navigate(Camera) - val expected = listOf(Home, Camera) // Home is locked in place + fun navigatingToStartRoute_whenOtherRoutesAreOnStack_popsAllOtherRoutes() { + val navigator = Navigator(startRoute = A) + navigator.navigate(B) // [A, B] + navigator.navigate(C) // [A, B, C] + navigator.navigate(A) // [A] + val expected : List = listOf(A) assertEquals(expected, navigator.backStack) } @Test - fun navigatingToNewTopLevel_whenStartRouteCanMove_popsAllOtherTopLevelStacks() { - val navigator = Navigator(startRoute = Home, canStartRouteMove = true) - navigator.navigate(Camera) - val expected = listOf(Camera) // Home is popped + fun navigatingToStartRoute_whenItHasSubRoutes_retainsSubRoutes() { + val navigator = Navigator(startRoute = A) + navigator.navigate(A1) // [A, A1] + navigator.navigate(B) // [A, A1, B] + navigator.navigate(A) // [A, A1] + val expected : List = listOf(A, A1) assertEquals(expected, navigator.backStack) } + @Test + fun repeatedlyNavigatingToTopLevelRoute_retainsSubRoutes(){ + val navigator = Navigator(startRoute = A) + navigator.navigate(B) + navigator.navigate(B1) + navigator.navigate(B) + + val expected = listOf(A, B, B1) + assertEquals(expected, navigator.backStack) + } + @Test + fun navigatingToTopLevelRoute_whenTopLevelRoutesCanExistTogether_retainsSubRoutes(){ + val navigator = Navigator(startRoute = A, canTopLevelRoutesExistTogether = true) + navigator.navigate(A) + navigator.navigate(A1) + navigator.navigate(B) + navigator.navigate(B1) + navigator.navigate(C) + navigator.navigate(B) + + val expected = listOf(A, A1, C, B, B1) + assertEquals(expected, navigator.backStack) + } + + @Test + fun navigatingBack_isChronological(){ + val navigator = Navigator(startRoute = A) + navigator.navigate(A1) + navigator.navigate(B) + navigator.navigate(B1) + assertEquals(listOf(A, A1, B, B1), navigator.backStack) + navigator.goBack() + assertEquals(listOf(A, A1, B), navigator.backStack) + navigator.goBack() + assertEquals(listOf(A, A1), navigator.backStack) + navigator.goBack() + assertEquals(listOf(A), navigator.backStack) + + } } \ No newline at end of file From 1b9681caf825c45d491508c030b51b94ad0342bd Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 31 Jul 2025 11:32:43 +0100 Subject: [PATCH 03/64] Address AI feedback --- .../nav3recipes/navigator/basic/Navigator.kt | 16 +++++++++++----- .../navigator/basic/NavigatorActivity.kt | 13 ++++++++----- .../nav3recipes/navigator/basic/NavigatorTest.kt | 4 ++-- 3 files changed, 21 insertions(+), 12 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt index d1d751a..9a6854e 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt @@ -53,6 +53,9 @@ class Navigator( startRoute to mutableListOf(startRoute) ) + // Maintain a map of shared routes to their parent stacks + private var sharedRoutes : MutableMap = mutableMapOf() + private fun updateBackStack() = backStack.apply { clear() @@ -80,7 +83,7 @@ class Navigator( private fun clearAllExceptStartStack(){ // Remove all other top level stacks, except the start stack - val startStack = topLevelStacks[startRoute]!! + val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) topLevelStacks.clear() topLevelStacks.put(startRoute, startStack) } @@ -94,11 +97,11 @@ class Navigator( } else { if (route.isShared){ // If the key is already in a stack, remove it - topLevelStacks.forEach { stack -> - if (stack.value.contains(route)){ - topLevelStacks[stack.key]?.remove(route) - } + val oldParent = sharedRoutes[route] + if (oldParent != null) { + topLevelStacks[oldParent]?.remove(route) } + sharedRoutes[route] = topLevelRoute } topLevelStacks[topLevelRoute]?.add(route) } @@ -109,6 +112,9 @@ class Navigator( * Go back to the previous route. */ fun goBack(){ + if (backStack.size <= 1){ + return + } val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() // If the removed key was a top level key, remove the associated top level stack topLevelStacks.remove(removedKey) diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt index decda42..aa79ae5 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt @@ -53,11 +53,14 @@ import com.example.nav3recipes.content.ContentPurple import com.example.nav3recipes.content.ContentRed import com.example.nav3recipes.ui.setEdgeToEdgeConfig -private abstract class NavBarItem(val icon: ImageVector): Route(isTopLevel = true) -private data object Home : NavBarItem(icon = Icons.Default.Home) -private data object ChatList : NavBarItem(icon = Icons.Default.Face) +private abstract class NavBarItem( + val icon: ImageVector, + val description: String +): Route(isTopLevel = true) +private data object Home : NavBarItem(icon = Icons.Default.Home, description = "Home") +private data object ChatList : NavBarItem(icon = Icons.Default.Face, description = "Chat list") private data object ChatDetail : Route() -private data object Camera : NavBarItem(icon = Icons.Default.PlayArrow) +private data object Camera : NavBarItem(icon = Icons.Default.PlayArrow, description = "Camera") private data object Search : Route(isShared = true) private val TOP_LEVEL_ROUTES : List = listOf(Home, ChatList, Camera) @@ -86,7 +89,7 @@ class NavigatorActivity : ComponentActivity() { icon = { Icon( imageVector = topLevelRoute.icon, - contentDescription = null + contentDescription = topLevelRoute.description ) } ) diff --git a/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt index 783a202..8c051f1 100644 --- a/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt +++ b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt @@ -24,7 +24,7 @@ class NavigatorTest { fun navigatingToTopLevelRoute_addsRouteToTopOfStack(){ val navigator = Navigator(startRoute = A) navigator.navigate(B) - assertEquals(listOf(A, B), navigator.backStack) + assertEquals(listOf(A, B), navigator.backStack) } @Test @@ -36,7 +36,7 @@ class NavigatorTest { } @Test - fun navigatingToNewTopLevelRoute_popsOtherTopLevelStacks() { + fun navigatingToNewTopLevelRoute_popsOtherStacksExceptStartStack() { val navigator = Navigator(startRoute = A) navigator.navigate(A1) // [A, A1] navigator.navigate(C) // [A, A1, C] From 8a36488b6d1f4a3f27bbde27a5fe367410f2bc9b Mon Sep 17 00:00:00 2001 From: Don Turner Date: Wed, 16 Jul 2025 11:29:33 +0100 Subject: [PATCH 04/64] Add Nav2 activity and dependencies --- app/build.gradle.kts | 1 + app/src/main/AndroidManifest.xml | 8 ++ .../migration/start/MainActivity.kt | 70 ++++++++++ .../migration/step1/MainActivity.kt | 125 ++++++++++++++++++ gradle/libs.versions.toml | 10 +- 5 files changed, 210 insertions(+), 4 deletions(-) create mode 100644 app/src/main/java/com/example/nav3recipes/migration/start/MainActivity.kt create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step1/MainActivity.kt diff --git a/app/build.gradle.kts b/app/build.gradle.kts index e42693a..d8d8e06 100644 --- a/app/build.gradle.kts +++ b/app/build.gradle.kts @@ -80,6 +80,7 @@ dependencies { implementation(libs.androidx.hilt.navigation.compose) implementation(libs.androidx.lifecycle.viewmodel.navigation3) implementation(libs.androidx.material.icons.extended) + implementation(libs.androidx.navigation2) implementation(libs.hilt.android) ksp(libs.hilt.compiler) diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index dafb614..d4df092 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -95,6 +95,14 @@ android:exported="true" android:label="@string/app_name" android:theme="@style/Theme.Nav3Recipes"/> + + diff --git a/app/src/main/java/com/example/nav3recipes/migration/start/MainActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/start/MainActivity.kt new file mode 100644 index 0000000..f7b2a14 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/start/MainActivity.kt @@ -0,0 +1,70 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.migration.start + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.padding +import androidx.compose.material3.Button +import androidx.compose.material3.Scaffold +import androidx.compose.material3.Text +import androidx.compose.ui.Modifier +import androidx.navigation.compose.NavHost +import androidx.navigation.compose.composable +import androidx.navigation.compose.rememberNavController +import androidx.navigation.toRoute +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable + +/** + * Basic Navigation2 example with two screens. This will be the starting point for migration to + * Navigation 3. + */ + +@Serializable +private data object RouteA + +@Serializable +private data class RouteB(val id: String) + +class MainActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navController = rememberNavController() + Scaffold { paddingValues -> + NavHost(navController = navController, startDestination = RouteA, modifier = Modifier.padding(paddingValues)) { + composable { + Column { + Text("Route A") + Button(onClick = { navController.navigate(route = RouteB(id = "123")) }) { + Text("Go to B") + } + } + } + composable { key -> + Text("Route B: ${key.toRoute().id}") + } + } + } + } + } +} diff --git a/app/src/main/java/com/example/nav3recipes/migration/step1/MainActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step1/MainActivity.kt new file mode 100644 index 0000000..3017720 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step1/MainActivity.kt @@ -0,0 +1,125 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.migration.step1 + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.padding +import androidx.compose.material3.Button +import androidx.compose.material3.Scaffold +import androidx.compose.material3.Text +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.remember +import androidx.compose.ui.Modifier +import androidx.navigation.NavHostController +import androidx.navigation.compose.NavHost +import androidx.navigation.compose.composable +import androidx.navigation.compose.rememberNavController +import androidx.navigation.toRoute +import androidx.navigation3.runtime.NavEntry +import androidx.navigation3.runtime.entryProvider +import androidx.navigation3.ui.NavDisplay +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch +import kotlinx.serialization.Serializable + +/** + * Basic Navigation2 example with two screens. This will be the starting point for migration to + * Navigation 3. + */ + +@Serializable +private data object RouteA + +@Serializable +private data class RouteB(val id: String) + +class MainActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navController = rememberNavController() + val nav3Navigator = remember { Nav3NavigatorSimple(navController) } + + Scaffold { paddingValues -> + NavDisplay( + backStack = nav3Navigator.backStack, + entryProvider = entryProvider(fallback = { key -> + println("Key $key not handled by entryProvider, using fallback") + NavEntry(key = key) { + NavHost( + navController = navController, + startDestination = RouteA, + modifier = Modifier.padding(paddingValues) + ) { + composable { + Column { + Text("Route A") + Button(onClick = { navController.navigate(route = RouteB(id = "123")) }) { + Text("Go to B") + } + } + } + composable { key -> + Text("Route B: ${key.toRoute().id}") + } + } + } + } + ) { + // Empty entryProvider + }) + } + } + } +} + +class Nav3NavigatorSimple(val navController: NavHostController){ + + val coroutineScope = CoroutineScope(Job()) + + // We need a single element to avoid "backStack cannot be empty" error b/430023647 + val backStack = mutableStateListOf(Unit) + + init { + coroutineScope.launch { + navController.currentBackStack.collect { nav2BackStack -> + with(backStack) { + if (nav2BackStack.isNotEmpty()){ + clear() + val entriesToAdd = nav2BackStack.mapNotNull { entry -> + // Ignore nav graph root entries + if (entry.destination::class.qualifiedName == "androidx.navigation.compose.ComposeNavGraphNavigator.ComposeNavGraph"){ + null + } else { + entry + } + } + addAll(entriesToAdd) + } + } + } + } + } +} + diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 7712e00..2d91164 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -14,21 +14,22 @@ [versions] agp = "8.10.1" -kotlin = "2.2.0-RC2" -kotlinSerialization = "2.1.21" +kotlin = "2.2.0" +kotlinSerialization = "2.2.0" coreKtx = "1.16.0" junit = "4.13.2" junitVersion = "1.2.1" espressoCore = "3.6.1" -kotlinxSerializationCore = "1.8.1" +kotlinxSerializationCore = "1.9.0" lifecycleRuntimeKtx = "2.9.1" lifecycleViewmodel = "1.0.0-SNAPSHOT" activityCompose = "1.12.0-alpha02" composeBom = "2025.06.00" +navigation2 = "2.9.1" navigation3 = "1.0.0-alpha04" material3 = "1.4.0-alpha15" nav3Material = "1.0.0-SNAPSHOT" -ksp = "2.2.0-RC2-2.0.1" +ksp = "2.2.0-2.0.2" hilt = "2.56.2" hiltNavigationCompose = "1.2.0" @@ -51,6 +52,7 @@ androidx-material3-windowsizeclass = { group = "androidx.compose.material3", nam androidx-adaptive-layout = { group = "androidx.compose.material3.adaptive", name = "adaptive-layout" } androidx-hilt-navigation-compose = { module = "androidx.hilt:hilt-navigation-compose", version.ref = "hiltNavigationCompose" } androidx-lifecycle-viewmodel-navigation3 = { module = "androidx.lifecycle:lifecycle-viewmodel-navigation3", version.ref = "lifecycleViewmodel" } +androidx-navigation2 = { module = "androidx.navigation:navigation-compose", version.ref = "navigation2" } androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "navigation3" } androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "navigation3" } hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" } From 2104f890a72f662cf5d66973842dbb77b0ed07e5 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 31 Jul 2025 17:28:27 +0100 Subject: [PATCH 05/64] Add starting point for migration --- .../nav3recipes/ExampleInstrumentedTest.kt | 40 ---- .../MigrationActivityNavigationTest.kt | 112 +++++++++ app/src/main/AndroidManifest.xml | 2 +- .../migration/start/MainActivity.kt | 70 ------ .../migration/start/MigrationActivity.kt | 224 ++++++++++++++++++ .../migration/step1/MainActivity.kt | 125 ---------- .../nav3recipes/navigator/basic/Navigator.kt | 9 + .../navigator/basic/NavigatorActivity.kt | 28 ++- 8 files changed, 363 insertions(+), 247 deletions(-) delete mode 100644 app/src/androidTest/java/com/example/nav3recipes/ExampleInstrumentedTest.kt create mode 100644 app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt delete mode 100644 app/src/main/java/com/example/nav3recipes/migration/start/MainActivity.kt create mode 100644 app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt delete mode 100644 app/src/main/java/com/example/nav3recipes/migration/step1/MainActivity.kt diff --git a/app/src/androidTest/java/com/example/nav3recipes/ExampleInstrumentedTest.kt b/app/src/androidTest/java/com/example/nav3recipes/ExampleInstrumentedTest.kt deleted file mode 100644 index 5121c2a..0000000 --- a/app/src/androidTest/java/com/example/nav3recipes/ExampleInstrumentedTest.kt +++ /dev/null @@ -1,40 +0,0 @@ -/* - * Copyright 2025 The Android Open Source Project - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package com.example.nav3recipes - -import androidx.test.platform.app.InstrumentationRegistry -import androidx.test.ext.junit.runners.AndroidJUnit4 - -import org.junit.Test -import org.junit.runner.RunWith - -import org.junit.Assert.* - -/** - * Instrumented test, which will execute on an Android device. - * - * See [testing documentation](http://d.android.com/tools/testing). - */ -@RunWith(AndroidJUnit4::class) -class ExampleInstrumentedTest { - @Test - fun useAppContext() { - // Context of the app under test. - val appContext = InstrumentationRegistry.getInstrumentation().targetContext - assertEquals("com.example.nav3recipes", appContext.packageName) - } -} \ No newline at end of file diff --git a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt new file mode 100644 index 0000000..86fe38e --- /dev/null +++ b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt @@ -0,0 +1,112 @@ +package com.example.nav3recipes + +import androidx.compose.ui.test.assertIsSelected +import androidx.compose.ui.test.hasText +import androidx.compose.ui.test.isSelectable +import androidx.compose.ui.test.junit4.createAndroidComposeRule +import androidx.compose.ui.test.onNodeWithText +import androidx.compose.ui.test.performClick +import com.example.nav3recipes.migration.start.MigrationActivity +import org.junit.Rule +import org.junit.Test + + +class MigrationActivityNavigationTest { + + @get:Rule(order = 0) + val composeTestRule = createAndroidComposeRule() + + @Test + fun firstScreen_isA() { + composeTestRule.apply { + onNode(hasText("Route A") and isSelectable()).assertIsSelected() + onNodeWithText("Route A title").assertExists() + } + } + + @Test + fun navigateToB_selectsB() { + composeTestRule.apply { + onNode(hasText("Route B") and isSelectable()).performClick() + onNode(hasText("Route B") and isSelectable()).assertIsSelected() + onNodeWithText("Route B title").assertExists() + } + } + + @Test + fun navigateToA1_keepsASelected() { + composeTestRule.apply { + onNode(hasText("Route A") and isSelectable()).assertIsSelected() + onNodeWithText("Route A title").assertExists() + onNodeWithText("Go to A1").performClick() + onNodeWithText("Route A1 title").assertExists() + onNode(hasText("Route A") and isSelectable()).assertIsSelected() + } + } + + @Test + fun navigateAtoBtoC_selectsCAndShowsContent() { + composeTestRule.apply { + onNode(hasText("Route B") and isSelectable()).performClick() + onNode(hasText("Route B") and isSelectable()).assertIsSelected() + onNodeWithText("Route B title").assertExists() + + onNode(hasText("Route C") and isSelectable()).performClick() + onNode(hasText("Route C") and isSelectable()).assertIsSelected() + onNodeWithText("Route C title").assertExists() + } + } + + @Test + fun navigateAtoB_pressBack_showsA() { + composeTestRule.apply { + onNode(hasText("Route B") and isSelectable()).performClick() + onNode(hasText("Route B") and isSelectable()).assertIsSelected() + onNodeWithText("Route B title").assertExists() + + composeTestRule.runOnUiThread { + composeTestRule.activity.onBackPressedDispatcher.onBackPressed() + } + + onNode(hasText("Route A") and isSelectable()).assertIsSelected() + onNodeWithText("Route A title").assertExists() + } + } + + @Test + fun navigateAtoA1_pressBack_showsAContent() { + composeTestRule.apply { + onNodeWithText("Go to A1").performClick() + onNodeWithText("Route A1 title").assertExists() + onNode(hasText("Route A") and isSelectable()).assertIsSelected() + + composeTestRule.runOnUiThread { + composeTestRule.activity.onBackPressedDispatcher.onBackPressed() + } + + onNodeWithText("Route A title").assertExists() + onNode(hasText("Route A") and isSelectable()).assertIsSelected() + } + } + + @Test + fun navigateAtoBtoC_thenBack_showsA() { + composeTestRule.apply { + onNode(hasText("Route B") and isSelectable()).performClick() + onNode(hasText("Route B") and isSelectable()).assertIsSelected() + onNodeWithText("Route B title").assertExists() + + onNode(hasText("Route C") and isSelectable()).performClick() + onNode(hasText("Route C") and isSelectable()).assertIsSelected() + onNodeWithText("Route C title").assertExists() + + composeTestRule.runOnUiThread { + composeTestRule.activity.onBackPressedDispatcher.onBackPressed() + } + + onNode(hasText("Route A") and isSelectable()).assertIsSelected() + onNodeWithText("Route A title").assertExists() + onNodeWithText("Route B title").assertDoesNotExist() + } + } +} diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index d4df092..02ce9c3 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -96,7 +96,7 @@ android:label="@string/app_name" android:theme="@style/Theme.Nav3Recipes"/> - NavHost(navController = navController, startDestination = RouteA, modifier = Modifier.padding(paddingValues)) { - composable { - Column { - Text("Route A") - Button(onClick = { navController.navigate(route = RouteB(id = "123")) }) { - Text("Go to B") - } - } - } - composable { key -> - Text("Route B: ${key.toRoute().id}") - } - } - } - } - } -} diff --git a/app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt new file mode 100644 index 0000000..5232b2d --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt @@ -0,0 +1,224 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.migration.start + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.padding +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.filled.Camera +import androidx.compose.material.icons.filled.Face +import androidx.compose.material.icons.filled.Home +import androidx.compose.material3.Button +import androidx.compose.material3.Icon +import androidx.compose.material3.NavigationBar +import androidx.compose.material3.NavigationBarItem +import androidx.compose.material3.Scaffold +import androidx.compose.material3.Text +import androidx.compose.runtime.getValue +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.graphics.vector.ImageVector +import androidx.navigation.NavDestination +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavDestination.Companion.hierarchy +import androidx.navigation.NavGraphBuilder +import androidx.navigation.NavHostController +import androidx.navigation.compose.NavHost +import androidx.navigation.compose.composable +import androidx.navigation.compose.currentBackStackEntryAsState +import androidx.navigation.compose.dialog +import androidx.navigation.compose.navigation +import androidx.navigation.compose.rememberNavController +import androidx.navigation.navOptions +import androidx.navigation.toRoute +import com.example.nav3recipes.content.ContentBlue +import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.content.ContentMauve +import com.example.nav3recipes.content.ContentPink +import com.example.nav3recipes.content.ContentPurple +import com.example.nav3recipes.content.ContentRed +import com.example.nav3recipes.navigator.basic.Route +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable +import kotlin.reflect.KClass + +/** + * Basic Navigation2 example with the following navigation graph: + * + * A -> A, A1, E + * B -> B, B1, E + * C -> C, E + * D + * + * - The starting destination (or home screen) is A. + * - A, B and C are top level destinations that appear in a navigation bar. + * - D is a dialog destination. + * - E is a shared destination that can appear under any of the top level destinations. + * - Navigating to a top level destination pops all other top level destinations off the stack, + * except for the start destination. + * - Navigating back from the start destination exits the app. + * + * This will be the starting point for migration to Navigation 3. + */ + +@Serializable private data object BaseRouteA : Route(isTopLevel = true) +@Serializable private data object RouteA : Route() +@Serializable private data object RouteA1 : Route() + +@Serializable private data object BaseRouteB : Route(isTopLevel = true) +@Serializable private data object RouteB : Route() +@Serializable private data class RouteB1(val id: String) + +@Serializable private data object BaseRouteC : Route(isTopLevel = true) +@Serializable private data object RouteC : Route() +@Serializable private data object RouteD : Route() +@Serializable private data object RouteE : Route() + +private val TOP_LEVEL_ROUTES = mapOf( + BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), + BaseRouteB to NavBarItem(icon = Icons.Default.Face, description = "Route B"), + BaseRouteC to NavBarItem(icon = Icons.Default.Camera, description = "Route C"), +) + +class NavBarItem( + val icon: ImageVector, + val description: String +) + +class MigrationActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navController = rememberNavController() + val currentBackStackEntry by navController.currentBackStackEntryAsState() + + Scaffold(bottomBar = { + NavigationBar { + TOP_LEVEL_ROUTES.forEach { (key, value) -> + val isSelected = currentBackStackEntry?.destination.isRouteInHierarchy(key::class) + NavigationBarItem( + selected = isSelected, + onClick = { + navController.navigate(key, navOptions { + popUpTo(route = RouteA) + }) + }, + icon = { + Icon( + imageVector = value.icon, + contentDescription = value.description + ) + }, + label = { Text(value.description) } + ) + } + } + }) + + { paddingValues -> + NavHost( + navController = navController, + startDestination = BaseRouteA, + modifier = Modifier.padding(paddingValues) + ) { + featureASection(navController) + featureBSection(navController) + featureCSection(navController) + dialog { key -> + Text(modifier = Modifier.background(Color.White), text = "Route D title (dialog)") + } + } + } + } + } +} + +private fun NavGraphBuilder.featureCSection(navController: NavHostController) { + navigation(startDestination = RouteC) { + composable { + ContentMauve("Route C title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { navController.navigate(route = RouteD) }) { + Text("Open dialog D") + } + Button(onClick = { navController.navigate(route = RouteE) }) { + Text("Go to E") + } + } + } + } + composable { ContentBlue("Route E title") } + } +} + +private fun NavGraphBuilder.featureBSection(navController: NavHostController) { + navigation(startDestination = RouteB) { + composable { + ContentGreen("Route B title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { navController.navigate(route = RouteB1(id = "ABC")) }) { + Text("Go to B1") + } + Button(onClick = { navController.navigate(route = RouteD) }) { + Text("Open dialog D") + } + Button(onClick = { navController.navigate(route = RouteE) }) { + Text("Go to E") + } + } + } + } + composable { key -> + ContentPurple("Route B1 title. ID: ${key.toRoute().id}") + } + composable { ContentBlue("Route E title") } + } +} + +private fun NavGraphBuilder.featureASection(navController: NavHostController) { + navigation(startDestination = RouteA) { + composable { + ContentRed("Route A title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { navController.navigate(route = RouteA1) }) { + Text("Go to A1") + } + Button(onClick = { navController.navigate(route = RouteD) }) { + Text("Open dialog D") + } + Button(onClick = { navController.navigate(route = RouteE) }) { + Text("Go to E") + } + } + } + } + composable { ContentPink("Route A1 title") } + composable { ContentBlue("Route E title") } + } +} + +private fun NavDestination?.isRouteInHierarchy(route: KClass<*>) = + this?.hierarchy?.any { + it.hasRoute(route) + } ?: false \ No newline at end of file diff --git a/app/src/main/java/com/example/nav3recipes/migration/step1/MainActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step1/MainActivity.kt deleted file mode 100644 index 3017720..0000000 --- a/app/src/main/java/com/example/nav3recipes/migration/step1/MainActivity.kt +++ /dev/null @@ -1,125 +0,0 @@ -/* - * Copyright 2025 The Android Open Source Project - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package com.example.nav3recipes.migration.step1 - -import android.os.Bundle -import androidx.activity.ComponentActivity -import androidx.activity.compose.setContent -import androidx.compose.foundation.layout.Column -import androidx.compose.foundation.layout.padding -import androidx.compose.material3.Button -import androidx.compose.material3.Scaffold -import androidx.compose.material3.Text -import androidx.compose.runtime.mutableStateListOf -import androidx.compose.runtime.remember -import androidx.compose.ui.Modifier -import androidx.navigation.NavHostController -import androidx.navigation.compose.NavHost -import androidx.navigation.compose.composable -import androidx.navigation.compose.rememberNavController -import androidx.navigation.toRoute -import androidx.navigation3.runtime.NavEntry -import androidx.navigation3.runtime.entryProvider -import androidx.navigation3.ui.NavDisplay -import com.example.nav3recipes.ui.setEdgeToEdgeConfig -import kotlinx.coroutines.CoroutineScope -import kotlinx.coroutines.Job -import kotlinx.coroutines.launch -import kotlinx.serialization.Serializable - -/** - * Basic Navigation2 example with two screens. This will be the starting point for migration to - * Navigation 3. - */ - -@Serializable -private data object RouteA - -@Serializable -private data class RouteB(val id: String) - -class MainActivity : ComponentActivity() { - - override fun onCreate(savedInstanceState: Bundle?) { - setEdgeToEdgeConfig() - super.onCreate(savedInstanceState) - setContent { - val navController = rememberNavController() - val nav3Navigator = remember { Nav3NavigatorSimple(navController) } - - Scaffold { paddingValues -> - NavDisplay( - backStack = nav3Navigator.backStack, - entryProvider = entryProvider(fallback = { key -> - println("Key $key not handled by entryProvider, using fallback") - NavEntry(key = key) { - NavHost( - navController = navController, - startDestination = RouteA, - modifier = Modifier.padding(paddingValues) - ) { - composable { - Column { - Text("Route A") - Button(onClick = { navController.navigate(route = RouteB(id = "123")) }) { - Text("Go to B") - } - } - } - composable { key -> - Text("Route B: ${key.toRoute().id}") - } - } - } - } - ) { - // Empty entryProvider - }) - } - } - } -} - -class Nav3NavigatorSimple(val navController: NavHostController){ - - val coroutineScope = CoroutineScope(Job()) - - // We need a single element to avoid "backStack cannot be empty" error b/430023647 - val backStack = mutableStateListOf(Unit) - - init { - coroutineScope.launch { - navController.currentBackStack.collect { nav2BackStack -> - with(backStack) { - if (nav2BackStack.isNotEmpty()){ - clear() - val entriesToAdd = nav2BackStack.mapNotNull { entry -> - // Ignore nav graph root entries - if (entry.destination::class.qualifiedName == "androidx.navigation.compose.ComposeNavGraphNavigator.ComposeNavGraph"){ - null - } else { - entry - } - } - addAll(entriesToAdd) - } - } - } - } - } -} - diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt index 9a6854e..8e9c8a6 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt @@ -4,6 +4,8 @@ import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateListOf import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.setValue +import androidx.compose.ui.graphics.vector.ImageVector +import kotlinx.serialization.Serializable /** * This class models navigation behavior. It provides a back stack @@ -123,7 +125,14 @@ class Navigator( } } +@Serializable abstract class Route( val isTopLevel : Boolean = false, val isShared : Boolean = false +) + +class NavBarItem( + val route: T, + val icon: ImageVector, + val description: String ) \ No newline at end of file diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt index aa79ae5..09e8d57 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt @@ -52,18 +52,25 @@ import com.example.nav3recipes.content.ContentPink import com.example.nav3recipes.content.ContentPurple import com.example.nav3recipes.content.ContentRed import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable -private abstract class NavBarItem( - val icon: ImageVector, - val description: String -): Route(isTopLevel = true) -private data object Home : NavBarItem(icon = Icons.Default.Home, description = "Home") -private data object ChatList : NavBarItem(icon = Icons.Default.Face, description = "Chat list") +@Serializable +private data object Home : Route(isTopLevel = true) +@Serializable +private data object ChatList : Route(isTopLevel = true) + +@Serializable private data object ChatDetail : Route() -private data object Camera : NavBarItem(icon = Icons.Default.PlayArrow, description = "Camera") +@Serializable +private data object Camera : Route(isTopLevel = true) +@Serializable private data object Search : Route(isShared = true) -private val TOP_LEVEL_ROUTES : List = listOf(Home, ChatList, Camera) +private val TOP_LEVEL_ROUTES : List> = listOf( + NavBarItem(Home, icon = Icons.Default.Home, description = "Home"), + NavBarItem(ChatList, icon = Icons.Default.Face, description = "Chat list"), + NavBarItem(Camera, icon = Icons.Default.PlayArrow, description = "Camera") +) class NavigatorActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { @@ -79,12 +86,11 @@ class NavigatorActivity : ComponentActivity() { bottomBar = { NavigationBar { TOP_LEVEL_ROUTES.forEach { topLevelRoute -> - - val isSelected = topLevelRoute == navigator.topLevelRoute + val isSelected = topLevelRoute.route == navigator.topLevelRoute NavigationBarItem( selected = isSelected, onClick = { - navigator.navigate(topLevelRoute) + navigator.navigate(topLevelRoute.route) }, icon = { Icon( From 6a56eca5ad4625c98ec8c42025913495fbda68ba Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 31 Jul 2025 18:43:23 +0100 Subject: [PATCH 06/64] Step 1 of migration complete --- .../MigrationActivityNavigationTest.kt | 2 +- app/src/main/AndroidManifest.xml | 2 +- .../migration/start/MigrationActivity.kt | 7 +- .../migration/step1/MigrationActivity.kt | 240 ++++++++++++++++++ .../nav3recipes/migration/step1/Navigator.kt | 41 +++ .../nav3recipes/navigator/basic/Navigator.kt | 6 - .../navigator/basic/NavigatorActivity.kt | 6 + 7 files changed, 295 insertions(+), 9 deletions(-) create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step1/MigrationActivity.kt create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step1/Navigator.kt diff --git a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt index 86fe38e..6e12c6a 100644 --- a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +++ b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt @@ -6,7 +6,7 @@ import androidx.compose.ui.test.isSelectable import androidx.compose.ui.test.junit4.createAndroidComposeRule import androidx.compose.ui.test.onNodeWithText import androidx.compose.ui.test.performClick -import com.example.nav3recipes.migration.start.MigrationActivity +import com.example.nav3recipes.migration.step1.MigrationActivity import org.junit.Rule import org.junit.Test diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 02ce9c3..543eb3d 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -100,7 +100,7 @@ android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> diff --git a/app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt index 5232b2d..2525122 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt @@ -56,7 +56,6 @@ import com.example.nav3recipes.content.ContentMauve import com.example.nav3recipes.content.ContentPink import com.example.nav3recipes.content.ContentPurple import com.example.nav3recipes.content.ContentRed -import com.example.nav3recipes.navigator.basic.Route import com.example.nav3recipes.ui.setEdgeToEdgeConfig import kotlinx.serialization.Serializable import kotlin.reflect.KClass @@ -104,6 +103,12 @@ class NavBarItem( val description: String ) +@Serializable +abstract class Route( + val isTopLevel : Boolean = false, + val isShared : Boolean = false +) + class MigrationActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { diff --git a/app/src/main/java/com/example/nav3recipes/migration/step1/MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step1/MigrationActivity.kt new file mode 100644 index 0000000..f954e40 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step1/MigrationActivity.kt @@ -0,0 +1,240 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.migration.step1 + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.padding +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.filled.Camera +import androidx.compose.material.icons.filled.Face +import androidx.compose.material.icons.filled.Home +import androidx.compose.material3.Button +import androidx.compose.material3.Icon +import androidx.compose.material3.NavigationBar +import androidx.compose.material3.NavigationBarItem +import androidx.compose.material3.Scaffold +import androidx.compose.material3.Text +import androidx.compose.runtime.getValue +import androidx.compose.runtime.key +import androidx.compose.runtime.remember +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.graphics.vector.ImageVector +import androidx.navigation.NavDestination +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavDestination.Companion.hierarchy +import androidx.navigation.NavGraphBuilder +import androidx.navigation.NavHostController +import androidx.navigation.compose.NavHost +import androidx.navigation.compose.composable +import androidx.navigation.compose.currentBackStackEntryAsState +import androidx.navigation.compose.dialog +import androidx.navigation.compose.navigation +import androidx.navigation.compose.rememberNavController +import androidx.navigation.navOptions +import androidx.navigation.toRoute +import androidx.navigation3.runtime.NavEntry +import androidx.navigation3.runtime.entryProvider +import androidx.navigation3.ui.NavDisplay +import com.example.nav3recipes.content.ContentBlue +import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.content.ContentMauve +import com.example.nav3recipes.content.ContentPink +import com.example.nav3recipes.content.ContentPurple +import com.example.nav3recipes.content.ContentRed +import com.example.nav3recipes.navigator.basic.Route +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable +import kotlin.reflect.KClass + +/** + * Step 1 of migration: + * + * - Create your own back stack class (`Navigator`) that mirrors the state of `NavController`'s back + * stack. + * - Make `Navigator` available everywhere that `NavController` is + * - Wrap `NavHost` with a `NavDisplay` + */ + +@Serializable private data object BaseRouteA : Route(isTopLevel = true) +@Serializable private data object RouteA : Route() +@Serializable private data object RouteA1 : Route() + +@Serializable private data object BaseRouteB : Route(isTopLevel = true) +@Serializable private data object RouteB : Route() +@Serializable private data class RouteB1(val id: String) + +@Serializable private data object BaseRouteC : Route(isTopLevel = true) +@Serializable private data object RouteC : Route() +@Serializable private data object RouteD : Route() +@Serializable private data object RouteE : Route() + +private val TOP_LEVEL_ROUTES = mapOf( + BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), + BaseRouteB to NavBarItem(icon = Icons.Default.Face, description = "Route B"), + BaseRouteC to NavBarItem(icon = Icons.Default.Camera, description = "Route C"), +) + +data class NavBarItem( + val icon: ImageVector, + val description: String +) + +@Serializable +abstract class Route( + val isTopLevel : Boolean = false, + val isShared : Boolean = false +) + +class MigrationActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navController = rememberNavController() + val navigator = remember { Navigator(navController) } + val currentBackStackEntry by navController.currentBackStackEntryAsState() + + Scaffold(bottomBar = { + NavigationBar { + TOP_LEVEL_ROUTES.forEach { (key, value) -> + val isSelected = currentBackStackEntry?.destination.isRouteInHierarchy(key::class) + NavigationBarItem( + selected = isSelected, + onClick = { + navController.navigate(key, navOptions { + popUpTo(route = RouteA) + }) + }, + icon = { + Icon( + imageVector = value.icon, + contentDescription = value.description + ) + }, + label = { Text(value.description) } + ) + } + } + }) + + { paddingValues -> + NavDisplay( + backStack = navigator.backStack, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) { + NavHost( + navController = navController, + startDestination = BaseRouteA, + modifier = Modifier.padding(paddingValues) + ) { + featureASection(navController, navigator) + featureBSection(navController, navigator) + featureCSection(navController, navigator) + dialog { key -> + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } + } + } + } + ) { + // No nav entries added yet. + } + ) + } + } + } +} + +private fun NavGraphBuilder.featureCSection(navController: NavHostController, navigator: Navigator) { + navigation(startDestination = RouteC) { + composable { + ContentMauve("Route C title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { navController.navigate(route = RouteD) }) { + Text("Open dialog D") + } + Button(onClick = { navController.navigate(route = RouteE) }) { + Text("Go to E") + } + } + } + } + composable { ContentBlue("Route E title") } + } +} + +private fun NavGraphBuilder.featureBSection(navController: NavHostController, navigator: Navigator) { + navigation(startDestination = RouteB) { + composable { + ContentGreen("Route B title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { navController.navigate(route = RouteB1(id = "ABC")) }) { + Text("Go to B1") + } + Button(onClick = { navController.navigate(route = RouteD) }) { + Text("Open dialog D") + } + Button(onClick = { navController.navigate(route = RouteE) }) { + Text("Go to E") + } + } + } + } + composable { key -> + ContentPurple("Route B1 title. ID: ${key.toRoute().id}") + } + composable { ContentBlue("Route E title") } + } +} + +private fun NavGraphBuilder.featureASection(navController: NavHostController, navigator: Navigator) { + navigation(startDestination = RouteA) { + composable { + ContentRed("Route A title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { navController.navigate(route = RouteA1) }) { + Text("Go to A1") + } + Button(onClick = { navController.navigate(route = RouteD) }) { + Text("Open dialog D") + } + Button(onClick = { navController.navigate(route = RouteE) }) { + Text("Go to E") + } + } + } + } + composable { ContentPink("Route A1 title") } + composable { ContentBlue("Route E title") } + } +} + +private fun NavDestination?.isRouteInHierarchy(route: KClass<*>) = + this?.hierarchy?.any { + it.hasRoute(route) + } ?: false \ No newline at end of file diff --git a/app/src/main/java/com/example/nav3recipes/migration/step1/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step1/Navigator.kt new file mode 100644 index 0000000..933c814 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step1/Navigator.kt @@ -0,0 +1,41 @@ +package com.example.nav3recipes.migration.step1 + +import android.annotation.SuppressLint +import androidx.compose.runtime.mutableStateListOf +import androidx.navigation.NavHostController +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch + +/** + * Navigator that mirrors `NavController`'s back stack + */ +@SuppressLint("RestrictedApi") +class Navigator( + private val navController: NavHostController +) { + + val coroutineScope = CoroutineScope(Job()) + + init { + coroutineScope.launch { + navController.currentBackStack.collect { nav2BackStack -> + if (nav2BackStack.isNotEmpty()){ + backStack.clear() + val entriesToAdd = nav2BackStack.mapNotNull { entry -> + // We only care about navigable destinations + val navigatorName = entry.destination.navigatorName + if (navigatorName == "composable" || navigatorName == "dialog"){ + entry + } else { + null + } + } + backStack.addAll(entriesToAdd) + } + } + } + } + + val backStack = mutableStateListOf(Unit) +} \ No newline at end of file diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt index 8e9c8a6..8cd2cf7 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt @@ -130,9 +130,3 @@ abstract class Route( val isTopLevel : Boolean = false, val isShared : Boolean = false ) - -class NavBarItem( - val route: T, - val icon: ImageVector, - val description: String -) \ No newline at end of file diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt index 09e8d57..0c5d74e 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt @@ -164,3 +164,9 @@ fun TopAppBarWithSearch( ) } +class NavBarItem( + val route: T, + val icon: ImageVector, + val description: String +) + From 24d2fb9f741f07dfab35c9afecefc16abe8e48d3 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 31 Jul 2025 21:19:16 +0100 Subject: [PATCH 07/64] Lots of refactoring --- .../MigrationActivityNavigationTest.kt | 5 +- app/src/main/AndroidManifest.xml | 8 +- ...nActivity.kt => StartMigrationActivity.kt} | 97 +++++--- .../migration/step2/Step2MigrationActivity.kt | 231 ++++++++++++++++++ .../migration/{step1 => step3}/Navigator.kt | 2 +- .../Step3MigrationActivity.kt} | 123 ++++++---- .../nav3recipes/navigator/basic/Navigator.kt | 1 - .../navigator/basic/NavigatorTest.kt | 1 - 8 files changed, 373 insertions(+), 95 deletions(-) rename app/src/main/java/com/example/nav3recipes/migration/start/{MigrationActivity.kt => StartMigrationActivity.kt} (77%) create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt rename app/src/main/java/com/example/nav3recipes/migration/{step1 => step3}/Navigator.kt (96%) rename app/src/main/java/com/example/nav3recipes/migration/{step1/MigrationActivity.kt => step3/Step3MigrationActivity.kt} (73%) diff --git a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt index 6e12c6a..c03535e 100644 --- a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +++ b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt @@ -6,15 +6,16 @@ import androidx.compose.ui.test.isSelectable import androidx.compose.ui.test.junit4.createAndroidComposeRule import androidx.compose.ui.test.onNodeWithText import androidx.compose.ui.test.performClick -import com.example.nav3recipes.migration.step1.MigrationActivity +import com.example.nav3recipes.migration.start.StartMigrationActivity import org.junit.Rule import org.junit.Test class MigrationActivityNavigationTest { + // To test each step in the migration plan, change the Activity name below. @get:Rule(order = 0) - val composeTestRule = createAndroidComposeRule() + val composeTestRule = createAndroidComposeRule() @Test fun firstScreen_isA() { diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 543eb3d..949669d 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -96,11 +96,15 @@ android:label="@string/app_name" android:theme="@style/Theme.Nav3Recipes"/> + diff --git a/app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt similarity index 77% rename from app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt rename to app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt index 2525122..7636b2f 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/start/MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt @@ -77,20 +77,22 @@ import kotlin.reflect.KClass * - Navigating back from the start destination exits the app. * * This will be the starting point for migration to Navigation 3. + * + * @see `MigrationActivityNavigationTest` for instrumented tests that verify this behavior. */ -@Serializable private data object BaseRouteA : Route(isTopLevel = true) -@Serializable private data object RouteA : Route() -@Serializable private data object RouteA1 : Route() +@Serializable private data object BaseRouteA +@Serializable private data object RouteA +@Serializable private data object RouteA1 -@Serializable private data object BaseRouteB : Route(isTopLevel = true) -@Serializable private data object RouteB : Route() +@Serializable private data object BaseRouteB +@Serializable private data object RouteB @Serializable private data class RouteB1(val id: String) -@Serializable private data object BaseRouteC : Route(isTopLevel = true) -@Serializable private data object RouteC : Route() -@Serializable private data object RouteD : Route() -@Serializable private data object RouteE : Route() +@Serializable private data object BaseRouteC +@Serializable private data object RouteC +@Serializable private data object RouteD +@Serializable private data object RouteE private val TOP_LEVEL_ROUTES = mapOf( BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), @@ -103,13 +105,7 @@ class NavBarItem( val description: String ) -@Serializable -abstract class Route( - val isTopLevel : Boolean = false, - val isShared : Boolean = false -) - -class MigrationActivity : ComponentActivity() { +class StartMigrationActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { setEdgeToEdgeConfig() @@ -147,9 +143,20 @@ class MigrationActivity : ComponentActivity() { startDestination = BaseRouteA, modifier = Modifier.padding(paddingValues) ) { - featureASection(navController) - featureBSection(navController) - featureCSection(navController) + featureASection( + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureBSection( + onDetailClick = { id -> navController.navigate(RouteB1(id)) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureCSection( + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) dialog { key -> Text(modifier = Modifier.background(Color.White), text = "Route D title (dialog)") } @@ -159,36 +166,48 @@ class MigrationActivity : ComponentActivity() { } } -private fun NavGraphBuilder.featureCSection(navController: NavHostController) { - navigation(startDestination = RouteC) { - composable { - ContentMauve("Route C title") { +private fun NavGraphBuilder.featureASection( + onSubRouteClick: () -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteA) { + composable { + ContentRed("Route A title") { Column(horizontalAlignment = Alignment.CenterHorizontally) { - Button(onClick = { navController.navigate(route = RouteD) }) { + Button(onClick = onSubRouteClick) { + Text("Go to A1") + } + Button(onClick = onDialogClick) { Text("Open dialog D") } - Button(onClick = { navController.navigate(route = RouteE) }) { + Button(onClick = onOtherClick) { Text("Go to E") } } } } + composable { ContentPink("Route A1 title") } composable { ContentBlue("Route E title") } } } -private fun NavGraphBuilder.featureBSection(navController: NavHostController) { +private fun NavGraphBuilder.featureBSection( + onDetailClick: (id: String) -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit +) { navigation(startDestination = RouteB) { composable { ContentGreen("Route B title") { Column(horizontalAlignment = Alignment.CenterHorizontally) { - Button(onClick = { navController.navigate(route = RouteB1(id = "ABC")) }) { + Button(onClick = { onDetailClick("ABC") }) { Text("Go to B1") } - Button(onClick = { navController.navigate(route = RouteD) }) { + Button(onClick = onDialogClick) { Text("Open dialog D") } - Button(onClick = { navController.navigate(route = RouteE) }) { + Button(onClick = onOtherClick) { Text("Go to E") } } @@ -201,28 +220,28 @@ private fun NavGraphBuilder.featureBSection(navController: NavHostController) { } } -private fun NavGraphBuilder.featureASection(navController: NavHostController) { - navigation(startDestination = RouteA) { - composable { - ContentRed("Route A title") { +private fun NavGraphBuilder.featureCSection( + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteC) { + composable { + ContentMauve("Route C title") { Column(horizontalAlignment = Alignment.CenterHorizontally) { - Button(onClick = { navController.navigate(route = RouteA1) }) { - Text("Go to A1") - } - Button(onClick = { navController.navigate(route = RouteD) }) { + Button(onClick = onDialogClick) { Text("Open dialog D") } - Button(onClick = { navController.navigate(route = RouteE) }) { + Button(onClick = onOtherClick) { Text("Go to E") } } } } - composable { ContentPink("Route A1 title") } composable { ContentBlue("Route E title") } } } + private fun NavDestination?.isRouteInHierarchy(route: KClass<*>) = this?.hierarchy?.any { it.hasRoute(route) diff --git a/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt new file mode 100644 index 0000000..b46eb5a --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt @@ -0,0 +1,231 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.migration.step2 + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.padding +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.filled.Camera +import androidx.compose.material.icons.filled.Face +import androidx.compose.material.icons.filled.Home +import androidx.compose.material3.Button +import androidx.compose.material3.Icon +import androidx.compose.material3.NavigationBar +import androidx.compose.material3.NavigationBarItem +import androidx.compose.material3.Scaffold +import androidx.compose.material3.Text +import androidx.compose.runtime.getValue +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.graphics.vector.ImageVector +import androidx.navigation.NavDestination +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavDestination.Companion.hierarchy +import androidx.navigation.NavGraphBuilder +import androidx.navigation.NavHostController +import androidx.navigation.compose.NavHost +import androidx.navigation.compose.composable +import androidx.navigation.compose.currentBackStackEntryAsState +import androidx.navigation.compose.dialog +import androidx.navigation.compose.navigation +import androidx.navigation.compose.rememberNavController +import androidx.navigation.navOptions +import androidx.navigation.toRoute +import com.example.nav3recipes.content.ContentBlue +import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.content.ContentMauve +import com.example.nav3recipes.content.ContentPink +import com.example.nav3recipes.content.ContentPurple +import com.example.nav3recipes.content.ContentRed +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable +import kotlin.reflect.KClass + +@Serializable private data object BaseRouteA +@Serializable private data object RouteA : Route.TopLevel +@Serializable private data object RouteA1 + +@Serializable private data object BaseRouteB +@Serializable private data object RouteB : Route.TopLevel +@Serializable private data class RouteB1(val id: String) + +@Serializable private data object BaseRouteC +@Serializable private data object RouteC : Route.TopLevel +@Serializable private data object RouteD : Route.Dialog +@Serializable private data object RouteE + +private val TOP_LEVEL_ROUTES = mapOf( + BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), + BaseRouteB to NavBarItem(icon = Icons.Default.Face, description = "Route B"), + BaseRouteC to NavBarItem(icon = Icons.Default.Camera, description = "Route C"), +) + +data class NavBarItem( + val icon: ImageVector, + val description: String +) + +sealed interface Route { + interface TopLevel : Route + interface Dialog : Route +} + +class Step2MigrationActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navController = rememberNavController() + val currentBackStackEntry by navController.currentBackStackEntryAsState() + + Scaffold(bottomBar = { + NavigationBar { + TOP_LEVEL_ROUTES.forEach { (key, value) -> + val isSelected = currentBackStackEntry?.destination.isRouteInHierarchy(key::class) + NavigationBarItem( + selected = isSelected, + onClick = { + navController.navigate(key, navOptions { + popUpTo(route = RouteA) + }) + }, + icon = { + Icon( + imageVector = value.icon, + contentDescription = value.description + ) + }, + label = { Text(value.description) } + ) + } + } + }) + + { paddingValues -> + NavHost( + navController = navController, + startDestination = BaseRouteA, + modifier = Modifier.padding(paddingValues) + ) { + featureASection( + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureBSection( + onDetailClick = { id -> navController.navigate(RouteB1(id)) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureCSection( + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + dialog { key -> + Text(modifier = Modifier.background(Color.White), text = "Route D title (dialog)") + } + } + } + } + } +} + +private fun NavGraphBuilder.featureASection( + onSubRouteClick: () -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteA) { + composable { + ContentRed("Route A title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onSubRouteClick) { + Text("Go to A1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + composable { ContentPink("Route A1 title") } + composable { ContentBlue("Route E title") } + } +} + +private fun NavGraphBuilder.featureBSection( + onDetailClick: (id: String) -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit +) { + navigation(startDestination = RouteB) { + composable { + ContentGreen("Route B title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { onDetailClick("ABC") }) { + Text("Go to B1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + composable { key -> + ContentPurple("Route B1 title. ID: ${key.toRoute().id}") + } + composable { ContentBlue("Route E title") } + } +} + +private fun NavGraphBuilder.featureCSection( + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteC) { + composable { + ContentMauve("Route C title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + composable { ContentBlue("Route E title") } + } +} + +private fun NavDestination?.isRouteInHierarchy(route: KClass<*>) = + this?.hierarchy?.any { + it.hasRoute(route) + } ?: false \ No newline at end of file diff --git a/app/src/main/java/com/example/nav3recipes/migration/step1/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt similarity index 96% rename from app/src/main/java/com/example/nav3recipes/migration/step1/Navigator.kt rename to app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt index 933c814..85d92e5 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step1/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt @@ -1,4 +1,4 @@ -package com.example.nav3recipes.migration.step1 +package com.example.nav3recipes.migration.step3 import android.annotation.SuppressLint import androidx.compose.runtime.mutableStateListOf diff --git a/app/src/main/java/com/example/nav3recipes/migration/step1/MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt similarity index 73% rename from app/src/main/java/com/example/nav3recipes/migration/step1/MigrationActivity.kt rename to app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt index f954e40..d8a7553 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step1/MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt @@ -14,7 +14,7 @@ * limitations under the License. */ -package com.example.nav3recipes.migration.step1 +package com.example.nav3recipes.migration.step3 import android.os.Bundle import androidx.activity.ComponentActivity @@ -33,7 +33,6 @@ import androidx.compose.material3.NavigationBarItem import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.runtime.getValue -import androidx.compose.runtime.key import androidx.compose.runtime.remember import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier @@ -61,32 +60,36 @@ import com.example.nav3recipes.content.ContentMauve import com.example.nav3recipes.content.ContentPink import com.example.nav3recipes.content.ContentPurple import com.example.nav3recipes.content.ContentRed -import com.example.nav3recipes.navigator.basic.Route import com.example.nav3recipes.ui.setEdgeToEdgeConfig import kotlinx.serialization.Serializable import kotlin.reflect.KClass /** - * Step 1 of migration: - * - * - Create your own back stack class (`Navigator`) that mirrors the state of `NavController`'s back - * stack. - * - Make `Navigator` available everywhere that `NavController` is - * - Wrap `NavHost` with a `NavDisplay` + * Step 2 of migration */ -@Serializable private data object BaseRouteA : Route(isTopLevel = true) -@Serializable private data object RouteA : Route() -@Serializable private data object RouteA1 : Route() +@Serializable +private data object BaseRouteA +@Serializable +private data object RouteA : Route.TopLevel +@Serializable +private data object RouteA1 -@Serializable private data object BaseRouteB : Route(isTopLevel = true) -@Serializable private data object RouteB : Route() -@Serializable private data class RouteB1(val id: String) +@Serializable +private data object BaseRouteB +@Serializable +private data object RouteB : Route.TopLevel +@Serializable +private data class RouteB1(val id: String) -@Serializable private data object BaseRouteC : Route(isTopLevel = true) -@Serializable private data object RouteC : Route() -@Serializable private data object RouteD : Route() -@Serializable private data object RouteE : Route() +@Serializable +private data object BaseRouteC +@Serializable +private data object RouteC : Route.TopLevel +@Serializable +private data object RouteD : Route.Dialog +@Serializable +private data object RouteE private val TOP_LEVEL_ROUTES = mapOf( BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), @@ -99,13 +102,12 @@ data class NavBarItem( val description: String ) -@Serializable -abstract class Route( - val isTopLevel : Boolean = false, - val isShared : Boolean = false -) +sealed interface Route { + interface TopLevel : Route + interface Dialog : Route +} -class MigrationActivity : ComponentActivity() { +class Step3MigrationActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { setEdgeToEdgeConfig() @@ -118,7 +120,8 @@ class MigrationActivity : ComponentActivity() { Scaffold(bottomBar = { NavigationBar { TOP_LEVEL_ROUTES.forEach { (key, value) -> - val isSelected = currentBackStackEntry?.destination.isRouteInHierarchy(key::class) + val isSelected = + currentBackStackEntry?.destination.isRouteInHierarchy(key::class) NavigationBarItem( selected = isSelected, onClick = { @@ -149,9 +152,20 @@ class MigrationActivity : ComponentActivity() { startDestination = BaseRouteA, modifier = Modifier.padding(paddingValues) ) { - featureASection(navController, navigator) - featureBSection(navController, navigator) - featureCSection(navController, navigator) + featureASection( + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureBSection( + onDetailClick = { id -> navController.navigate(RouteB1(id)) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureCSection( + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) dialog { key -> Text( modifier = Modifier.background(Color.White), @@ -170,36 +184,48 @@ class MigrationActivity : ComponentActivity() { } } -private fun NavGraphBuilder.featureCSection(navController: NavHostController, navigator: Navigator) { - navigation(startDestination = RouteC) { - composable { - ContentMauve("Route C title") { +private fun NavGraphBuilder.featureASection( + onSubRouteClick: () -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteA) { + composable { + ContentRed("Route A title") { Column(horizontalAlignment = Alignment.CenterHorizontally) { - Button(onClick = { navController.navigate(route = RouteD) }) { + Button(onClick = onSubRouteClick) { + Text("Go to A1") + } + Button(onClick = onDialogClick) { Text("Open dialog D") } - Button(onClick = { navController.navigate(route = RouteE) }) { + Button(onClick = onOtherClick) { Text("Go to E") } } } } + composable { ContentPink("Route A1 title") } composable { ContentBlue("Route E title") } } } -private fun NavGraphBuilder.featureBSection(navController: NavHostController, navigator: Navigator) { +private fun NavGraphBuilder.featureBSection( + onDetailClick: (id: String) -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit +) { navigation(startDestination = RouteB) { composable { ContentGreen("Route B title") { Column(horizontalAlignment = Alignment.CenterHorizontally) { - Button(onClick = { navController.navigate(route = RouteB1(id = "ABC")) }) { + Button(onClick = { onDetailClick("ABC") }) { Text("Go to B1") } - Button(onClick = { navController.navigate(route = RouteD) }) { + Button(onClick = onDialogClick) { Text("Open dialog D") } - Button(onClick = { navController.navigate(route = RouteE) }) { + Button(onClick = onOtherClick) { Text("Go to E") } } @@ -212,24 +238,23 @@ private fun NavGraphBuilder.featureBSection(navController: NavHostController, na } } -private fun NavGraphBuilder.featureASection(navController: NavHostController, navigator: Navigator) { - navigation(startDestination = RouteA) { - composable { - ContentRed("Route A title") { +private fun NavGraphBuilder.featureCSection( + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteC) { + composable { + ContentMauve("Route C title") { Column(horizontalAlignment = Alignment.CenterHorizontally) { - Button(onClick = { navController.navigate(route = RouteA1) }) { - Text("Go to A1") - } - Button(onClick = { navController.navigate(route = RouteD) }) { + Button(onClick = onDialogClick) { Text("Open dialog D") } - Button(onClick = { navController.navigate(route = RouteE) }) { + Button(onClick = onOtherClick) { Text("Go to E") } } } } - composable { ContentPink("Route A1 title") } composable { ContentBlue("Route E title") } } } diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt index 8cd2cf7..17151df 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt @@ -4,7 +4,6 @@ import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateListOf import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.setValue -import androidx.compose.ui.graphics.vector.ImageVector import kotlinx.serialization.Serializable /** diff --git a/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt index 8c051f1..fabc88c 100644 --- a/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt +++ b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt @@ -2,7 +2,6 @@ package com.example.nav3recipes.navigator.basic import org.junit.Test import kotlin.test.assertEquals -import kotlin.test.assertFailsWith class NavigatorTest { From caed0271418623840b1190ff38a2346fbaeccae1 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 1 Aug 2025 15:50:57 +0100 Subject: [PATCH 08/64] Add Step 4 of the migration --- .../MigrationActivityNavigationTest.kt | 61 +++- app/src/main/AndroidManifest.xml | 4 + .../nav3recipes/migration/step3/Navigator.kt | 1 + .../migration/step3/Step3MigrationActivity.kt | 4 - .../nav3recipes/migration/step4/Navigator.kt | 191 +++++++++++++ .../migration/step4/Step4MigrationActivity.kt | 269 ++++++++++++++++++ 6 files changed, 516 insertions(+), 14 deletions(-) create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt diff --git a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt index c03535e..6e86616 100644 --- a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +++ b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt @@ -6,7 +6,11 @@ import androidx.compose.ui.test.isSelectable import androidx.compose.ui.test.junit4.createAndroidComposeRule import androidx.compose.ui.test.onNodeWithText import androidx.compose.ui.test.performClick +import androidx.test.espresso.Espresso import com.example.nav3recipes.migration.start.StartMigrationActivity +import com.example.nav3recipes.migration.step2.Step2MigrationActivity +import com.example.nav3recipes.migration.step3.Step3MigrationActivity +import com.example.nav3recipes.migration.step4.Step4MigrationActivity import org.junit.Rule import org.junit.Test @@ -15,7 +19,7 @@ class MigrationActivityNavigationTest { // To test each step in the migration plan, change the Activity name below. @get:Rule(order = 0) - val composeTestRule = createAndroidComposeRule() + val composeTestRule = createAndroidComposeRule() @Test fun firstScreen_isA() { @@ -65,9 +69,7 @@ class MigrationActivityNavigationTest { onNode(hasText("Route B") and isSelectable()).assertIsSelected() onNodeWithText("Route B title").assertExists() - composeTestRule.runOnUiThread { - composeTestRule.activity.onBackPressedDispatcher.onBackPressed() - } + Espresso.pressBack() onNode(hasText("Route A") and isSelectable()).assertIsSelected() onNodeWithText("Route A title").assertExists() @@ -81,9 +83,7 @@ class MigrationActivityNavigationTest { onNodeWithText("Route A1 title").assertExists() onNode(hasText("Route A") and isSelectable()).assertIsSelected() - composeTestRule.runOnUiThread { - composeTestRule.activity.onBackPressedDispatcher.onBackPressed() - } + Espresso.pressBack() onNodeWithText("Route A title").assertExists() onNode(hasText("Route A") and isSelectable()).assertIsSelected() @@ -101,13 +101,54 @@ class MigrationActivityNavigationTest { onNode(hasText("Route C") and isSelectable()).assertIsSelected() onNodeWithText("Route C title").assertExists() - composeTestRule.runOnUiThread { - composeTestRule.activity.onBackPressedDispatcher.onBackPressed() - } + Espresso.pressBack() onNode(hasText("Route A") and isSelectable()).assertIsSelected() onNodeWithText("Route A title").assertExists() onNodeWithText("Route B title").assertDoesNotExist() } } + + @Test + fun navigateToDialogD_onA_showsDialogContentAndDismisses() { + composeTestRule.apply { + + onNodeWithText("Open dialog D").performClick() + onNodeWithText("Route D title (dialog)").assertExists() + Espresso.pressBack() + onNodeWithText("Route A title").assertExists() + } + } + + /** + * These 2 tests fail and they shouldn't + */ + @Test + fun navigateToDialogD_onB_showsDialogContentAndDismisses() { + composeTestRule.apply { + + onNode(hasText("Route B") and isSelectable()).performClick() + + onNodeWithText("Open dialog D").performClick() + onNodeWithText("Route D title (dialog)").assertExists() + Espresso.pressBack() + onNodeWithText("Route B title").assertExists() + } + } + + + @Test + fun navigateToDialogD_onC_showsDialogContentAndDismisses() { + composeTestRule.apply { + + onNode(hasText("Route C") and isSelectable()).performClick() + + onNodeWithText("Open dialog D").performClick() + onNodeWithText("Route D title (dialog)").assertExists() + Espresso.pressBack() + onNodeWithText("Route C title").assertExists() + } + } + + } diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 949669d..2be8a4f 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -107,6 +107,10 @@ android:name=".migration.step3.Step3MigrationActivity" android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> + diff --git a/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt index 85d92e5..fdf60ae 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt @@ -31,6 +31,7 @@ class Navigator( null } } + println("Back stack: $entriesToAdd") backStack.addAll(entriesToAdd) } } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt index d8a7553..1203dcb 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt @@ -64,10 +64,6 @@ import com.example.nav3recipes.ui.setEdgeToEdgeConfig import kotlinx.serialization.Serializable import kotlin.reflect.KClass -/** - * Step 2 of migration - */ - @Serializable private data object BaseRouteA @Serializable diff --git a/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt new file mode 100644 index 0000000..6cc2ba1 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt @@ -0,0 +1,191 @@ +package com.example.nav3recipes.migration.step4 + +import android.annotation.SuppressLint +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.navigation.NavBackStackEntry +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavHostController +import androidx.navigation.toRoute +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch + +/** + * Navigator that mirrors `NavController`'s back stack + */ +@SuppressLint("RestrictedApi") +class Navigator( + private val navController: NavHostController, + private val startRoute: Any = Unit, + private val canTopLevelRoutesExistTogether: Boolean = false +) { + + val backStack = mutableStateListOf(startRoute) + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Maintain a stack for each top level route + private lateinit var topLevelStacks : MutableMap> + + // Maintain a map of shared routes to their parent stacks + private var sharedRoutes: MutableMap = mutableMapOf() + + val coroutineScope = CoroutineScope(Job()) + + init { + inititalizeTopLevelStacks() + coroutineScope.launch { + navController.currentBackStack.collect { nav2BackStack -> + inititalizeTopLevelStacks() + println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + printTopLevelStacks() + + nav2BackStack.forEach { entry -> + // Convert migrated routes into instances + val destination = entry.destination + + if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ + val route = + if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else { + // Non migrated top level route + entry + } + add(route) + } else { + println("Ignoring $entry") + } + } + printTopLevelStacks() + updateBackStack() + } + } + } + + private fun updateBackStack() { + backStack.apply { + clear() + val entries = topLevelStacks.flatMap { it.value } + addAll(entries) + } + printBackStack() + } + + private fun printBackStack() { + println("Back stack: ") + backStack.print() + println("---") + } + + private fun printTopLevelStacks() { + + println("Top level stacks: ") + topLevelStacks.forEach { topLevelStack -> + print("${topLevelStack.key} => ") + topLevelStack.value.print() + } + println("---") + } + + private fun List.print() { + print("[") + forEach { entry -> + if (entry is NavBackStackEntry){ + print("Unmigrated route: ${entry.destination.route}, ") + } else { + print("Migrated route: $entry, ") + } + } + print("]\n") + } + + private fun addTopLevel(route: Any) { + if (route == startRoute) { + clearAllExceptStartStack() + } else { + + // Get the existing stack or create a new one. + val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) + + if (!canTopLevelRoutesExistTogether) { + clearAllExceptStartStack() + } + + topLevelStacks.put(route, topLevelStack) + println("Added top level route $route") + } + topLevelRoute = route + } + + private fun clearAllExceptStartStack() { + // Remove all other top level stacks, except the start stack + val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) + topLevelStacks.clear() + topLevelStacks.put(startRoute, startStack) + } + + private fun inititalizeTopLevelStacks() { + topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) + topLevelRoute = startRoute + } + + private fun add(route: Any) { + println("Attempting to add $route") + if (route is Route.TopLevel) { + println("$route is a top level route") + addTopLevel(route) + } else { + if (route is Route.Shared) { + println("$route is a shared route") + // If the key is already in a stack, remove it + val oldParent = sharedRoutes[route] + if (oldParent != null) { + topLevelStacks[oldParent]?.remove(route) + } + sharedRoutes[route] = topLevelRoute + } else { + println("$route is a normal route") + } + val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false + println("Added $route to $topLevelRoute stack: $hasBeenAdded") + } + } + + /** + * Navigate to the given route. + */ + fun navigate(route: Any) { + add(route) + updateBackStack() + } + + /** + * Go back to the previous route. + */ + fun goBack() { + if (backStack.size <= 1) { + return + } + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + } +} + +sealed interface Route { + interface TopLevel : Route + interface Dialog : Route + interface Shared : Route +} diff --git a/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt new file mode 100644 index 0000000..4ad5ac7 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt @@ -0,0 +1,269 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.migration.step4 + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.padding +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.filled.Camera +import androidx.compose.material.icons.filled.Face +import androidx.compose.material.icons.filled.Home +import androidx.compose.material3.Button +import androidx.compose.material3.Icon +import androidx.compose.material3.NavigationBar +import androidx.compose.material3.NavigationBarItem +import androidx.compose.material3.Scaffold +import androidx.compose.material3.Text +import androidx.compose.runtime.getValue +import androidx.compose.runtime.remember +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.graphics.vector.ImageVector +import androidx.navigation.NavDestination +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavDestination.Companion.hierarchy +import androidx.navigation.NavGraphBuilder +import androidx.navigation.compose.NavHost +import androidx.navigation.compose.composable +import androidx.navigation.compose.currentBackStackEntryAsState +import androidx.navigation.compose.dialog +import androidx.navigation.compose.navigation +import androidx.navigation.compose.rememberNavController +import androidx.navigation.navOptions +import androidx.navigation.toRoute +import androidx.navigation3.runtime.EntryProviderBuilder +import androidx.navigation3.runtime.NavEntry +import androidx.navigation3.runtime.entry +import androidx.navigation3.runtime.entryProvider +import androidx.navigation3.ui.NavDisplay +import com.example.nav3recipes.content.ContentBlue +import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.content.ContentMauve +import com.example.nav3recipes.content.ContentPink +import com.example.nav3recipes.content.ContentPurple +import com.example.nav3recipes.content.ContentRed +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable +import kotlin.reflect.KClass + + +@Serializable +data object BaseRouteA + +@Serializable +data object RouteA : Route.TopLevel + +@Serializable +data object RouteA1 + +@Serializable +data object BaseRouteB + +@Serializable +data object RouteB : Route.TopLevel + +@Serializable +data class RouteB1(val id: String) + +@Serializable +data object BaseRouteC + +@Serializable +data object RouteC : Route.TopLevel + +@Serializable +data object RouteD : Route.Dialog + +@Serializable +data object RouteE + +private val TOP_LEVEL_ROUTES = mapOf( + BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), + BaseRouteB to NavBarItem(icon = Icons.Default.Face, description = "Route B"), + BaseRouteC to NavBarItem(icon = Icons.Default.Camera, description = "Route C"), +) + +data class NavBarItem( + val icon: ImageVector, + val description: String +) + + +class Step4MigrationActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navController = rememberNavController() + val navigator = remember { Navigator(navController) } + val currentBackStackEntry by navController.currentBackStackEntryAsState() + + Scaffold(bottomBar = { + NavigationBar { + TOP_LEVEL_ROUTES.forEach { (key, value) -> + val isSelected = + currentBackStackEntry?.destination.isRouteInHierarchy(key::class) + NavigationBarItem( + selected = isSelected, + onClick = { + navController.navigate(key, navOptions { + popUpTo(route = RouteA) + }) + }, + icon = { + Icon( + imageVector = value.icon, + contentDescription = value.description + ) + }, + label = { Text(value.description) } + ) + } + } + }) + + { paddingValues -> + NavDisplay( + backStack = navigator.backStack, + onBack = { navController.popBackStack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) { + NavHost( + navController = navController, + startDestination = BaseRouteA, + modifier = Modifier.padding(paddingValues) + ) { + featureASection( + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + navigation(startDestination = RouteB) { + composable { } + composable { } + composable { } + } + featureCSection( + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + dialog { key -> + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } + } + } + } + ) { + featureBSection( + onDetailClick = { id -> navController.navigate(RouteB1(id)) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + } + ) + } + } + } +} + +private fun NavGraphBuilder.featureASection( + onSubRouteClick: () -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteA) { + composable { + ContentRed("Route A title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onSubRouteClick) { + Text("Go to A1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + composable { ContentPink("Route A1 title") } + composable { ContentBlue("Route E title") } + } +} + +private fun EntryProviderBuilder.featureBSection( + onDetailClick: (id: String) -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit +) { + entry { + ContentGreen("Route B title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { onDetailClick("ABC") }) { + Text("Go to B1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + entry { key -> + ContentPurple("Route B1 title. ID: ${key.id}") + } + entry { ContentBlue("Route E title") } +} + +private fun NavGraphBuilder.featureCSection( + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteC) { + composable { + ContentMauve("Route C title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + composable { ContentBlue("Route E title") } + } +} + +private fun NavDestination?.isRouteInHierarchy(route: KClass<*>) = + this?.hierarchy?.any { + it.hasRoute(route) + } ?: false \ No newline at end of file From 40482df360f5db6a54d8ed7e778646c2be59f8b8 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Tue, 12 Aug 2025 16:17:11 +0100 Subject: [PATCH 09/64] Add Step 5 of the migration --- app/src/main/AndroidManifest.xml | 4 + .../migration/start/StartMigrationActivity.kt | 1 - .../nav3recipes/migration/step3/Navigator.kt | 7 +- .../migration/step3/Step3MigrationActivity.kt | 5 - .../nav3recipes/migration/step4/Navigator.kt | 1 - .../migration/step4/Step4MigrationActivity.kt | 46 ++-- .../nav3recipes/migration/step5/Navigator.kt | 177 ++++++++++++ .../migration/step5/Step5MigrationActivity.kt | 260 ++++++++++++++++++ .../nav3recipes/navigator/basic/Navigator.kt | 2 +- .../navigator/basic/NavigatorActivity.kt | 14 +- .../navigator/basic/NavigatorV2.kt | 194 +++++++++++++ .../navigator/basic/NavigatorTest.kt | 40 +-- 12 files changed, 688 insertions(+), 63 deletions(-) create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt create mode 100644 app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorV2.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 2be8a4f..5c9d57c 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -111,6 +111,10 @@ android:name=".migration.step4.Step4MigrationActivity" android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> + diff --git a/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt index 7636b2f..f5bd47c 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt @@ -41,7 +41,6 @@ import androidx.navigation.NavDestination import androidx.navigation.NavDestination.Companion.hasRoute import androidx.navigation.NavDestination.Companion.hierarchy import androidx.navigation.NavGraphBuilder -import androidx.navigation.NavHostController import androidx.navigation.compose.NavHost import androidx.navigation.compose.composable import androidx.navigation.compose.currentBackStackEntryAsState diff --git a/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt index fdf60ae..92ea6fd 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt @@ -39,4 +39,9 @@ class Navigator( } val backStack = mutableStateListOf(Unit) -} \ No newline at end of file +} + +sealed interface Route { + interface TopLevel : Route + interface Dialog : Route +} diff --git a/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt index 1203dcb..5383a36 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt @@ -98,11 +98,6 @@ data class NavBarItem( val description: String ) -sealed interface Route { - interface TopLevel : Route - interface Dialog : Route -} - class Step3MigrationActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { diff --git a/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt index 6cc2ba1..e866aef 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt @@ -44,7 +44,6 @@ class Navigator( printTopLevelStacks() nav2BackStack.forEach { entry -> - // Convert migrated routes into instances val destination = entry.destination if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ diff --git a/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt index 4ad5ac7..c1391b0 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt @@ -65,34 +65,26 @@ import com.example.nav3recipes.ui.setEdgeToEdgeConfig import kotlinx.serialization.Serializable import kotlin.reflect.KClass - @Serializable data object BaseRouteA - @Serializable data object RouteA : Route.TopLevel - @Serializable data object RouteA1 @Serializable data object BaseRouteB - @Serializable data object RouteB : Route.TopLevel - @Serializable data class RouteB1(val id: String) @Serializable data object BaseRouteC - @Serializable data object RouteC : Route.TopLevel - @Serializable data object RouteD : Route.Dialog - @Serializable data object RouteE @@ -160,9 +152,9 @@ class Step4MigrationActivity : ComponentActivity() { onOtherClick = { navController.navigate(RouteE) } ) navigation(startDestination = RouteB) { - composable { } - composable { } - composable { } + composable {} + composable {} + composable {} } featureCSection( onDialogClick = { navController.navigate(RouteD) }, @@ -221,26 +213,26 @@ private fun EntryProviderBuilder.featureBSection( onDialogClick: () -> Unit, onOtherClick: () -> Unit ) { - entry { - ContentGreen("Route B title") { - Column(horizontalAlignment = Alignment.CenterHorizontally) { - Button(onClick = { onDetailClick("ABC") }) { - Text("Go to B1") - } - Button(onClick = onDialogClick) { - Text("Open dialog D") - } - Button(onClick = onOtherClick) { - Text("Go to E") + entry { + ContentGreen("Route B title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { onDetailClick("ABC") }) { + Text("Go to B1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } } } } + entry { key -> + ContentPurple("Route B1 title. ID: ${key.id}") + } + entry { ContentBlue("Route E title") } } - entry { key -> - ContentPurple("Route B1 title. ID: ${key.id}") - } - entry { ContentBlue("Route E title") } -} private fun NavGraphBuilder.featureCSection( onDialogClick: () -> Unit, diff --git a/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt new file mode 100644 index 0000000..3ec6024 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt @@ -0,0 +1,177 @@ +package com.example.nav3recipes.migration.step5 + +import android.annotation.SuppressLint +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.navigation.NavBackStackEntry +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavHostController +import androidx.navigation.NavOptions +import androidx.navigation.toRoute +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch + +/** + * Navigator that mirrors `NavController`'s back stack + */ +@SuppressLint("RestrictedApi") +class Navigator( + private val navController: NavHostController, + private val startRoute: Any = Unit, + private val canTopLevelRoutesExistTogether: Boolean = false +) { + + val backStack = mutableStateListOf(startRoute) + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Maintain a stack for each top level route + private lateinit var topLevelStacks : MutableMap> + + // Maintain a map of shared routes to their parent stacks + private var sharedRoutes: MutableMap = mutableMapOf() + + val coroutineScope = CoroutineScope(Job()) + + init { + inititalizeTopLevelStacks() + coroutineScope.launch { + navController.currentBackStack.collect { nav2BackStack -> + inititalizeTopLevelStacks() + println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + printTopLevelStacks() + + nav2BackStack.forEach { entry -> + val destination = entry.destination + + if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ + val route = + if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else { + // Non migrated top level route + entry + } + add(route) + } else { + println("Ignoring $entry") + } + } + printTopLevelStacks() + updateBackStack() + } + } + } + + private fun updateBackStack() { + backStack.apply { + clear() + val entries = topLevelStacks.flatMap { it.value } + addAll(entries) + } + printBackStack() + } + + private fun printBackStack() { + println("Back stack: ") + backStack.print() + println("---") + } + + private fun printTopLevelStacks() { + + println("Top level stacks: ") + topLevelStacks.forEach { topLevelStack -> + print("${topLevelStack.key} => ") + topLevelStack.value.print() + } + println("---") + } + + private fun List.print() { + print("[") + forEach { entry -> + if (entry is NavBackStackEntry){ + print("Unmigrated route: ${entry.destination.route}, ") + } else { + print("Migrated route: $entry, ") + } + } + print("]\n") + } + + private fun addTopLevel(route: Any) { + if (route == startRoute) { + clearAllExceptStartStack() + } else { + + // Get the existing stack or create a new one. + val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) + + if (!canTopLevelRoutesExistTogether) { + clearAllExceptStartStack() + } + + topLevelStacks.put(route, topLevelStack) + println("Added top level route $route") + } + topLevelRoute = route + } + + private fun clearAllExceptStartStack() { + // Remove all other top level stacks, except the start stack + val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) + topLevelStacks.clear() + topLevelStacks.put(startRoute, startStack) + } + + private fun inititalizeTopLevelStacks() { + topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) + topLevelRoute = startRoute + } + + private fun add(route: Any) { + println("Attempting to add $route") + if (route is Route.TopLevel) { + println("$route is a top level route") + addTopLevel(route) + } else { + if (route is Route.Shared) { + println("$route is a shared route") + // If the key is already in a stack, remove it + val oldParent = sharedRoutes[route] + if (oldParent != null) { + topLevelStacks[oldParent]?.remove(route) + } + sharedRoutes[route] = topLevelRoute + } else { + println("$route is a normal route") + } + val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false + println("Added $route to $topLevelRoute stack: $hasBeenAdded") + } + } + + fun navigate(route: Any, navOptions: NavOptions? = null) { + navController.navigate(route, navOptions) + } + + fun goBack() { + navController.popBackStack() + } +} + +sealed interface Route { + interface TopLevel : Route + interface Dialog : Route + interface Shared : Route +} diff --git a/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt new file mode 100644 index 0000000..95f6654 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt @@ -0,0 +1,260 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.migration.step5 + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.padding +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.filled.Camera +import androidx.compose.material.icons.filled.Face +import androidx.compose.material.icons.filled.Home +import androidx.compose.material3.Button +import androidx.compose.material3.Icon +import androidx.compose.material3.NavigationBar +import androidx.compose.material3.NavigationBarItem +import androidx.compose.material3.Scaffold +import androidx.compose.material3.Text +import androidx.compose.runtime.getValue +import androidx.compose.runtime.remember +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.graphics.vector.ImageVector +import androidx.navigation.NavDestination +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavDestination.Companion.hierarchy +import androidx.navigation.NavGraphBuilder +import androidx.navigation.compose.NavHost +import androidx.navigation.compose.composable +import androidx.navigation.compose.currentBackStackEntryAsState +import androidx.navigation.compose.dialog +import androidx.navigation.compose.navigation +import androidx.navigation.compose.rememberNavController +import androidx.navigation.navOptions +import androidx.navigation3.runtime.EntryProviderBuilder +import androidx.navigation3.runtime.NavEntry +import androidx.navigation3.runtime.entry +import androidx.navigation3.runtime.entryProvider +import androidx.navigation3.ui.NavDisplay +import com.example.nav3recipes.content.ContentBlue +import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.content.ContentMauve +import com.example.nav3recipes.content.ContentPink +import com.example.nav3recipes.content.ContentPurple +import com.example.nav3recipes.content.ContentRed +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable +import kotlin.reflect.KClass + +@Serializable +data object BaseRouteA +@Serializable +data object RouteA : Route.TopLevel +@Serializable +data object RouteA1 + +@Serializable +data object BaseRouteB +@Serializable +data object RouteB : Route.TopLevel +@Serializable +data class RouteB1(val id: String) + +@Serializable +data object BaseRouteC +@Serializable +data object RouteC : Route.TopLevel +@Serializable +data object RouteD : Route.Dialog +@Serializable +data object RouteE + +private val TOP_LEVEL_ROUTES = mapOf( + BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), + BaseRouteB to NavBarItem(icon = Icons.Default.Face, description = "Route B"), + BaseRouteC to NavBarItem(icon = Icons.Default.Camera, description = "Route C"), +) + +data class NavBarItem( + val icon: ImageVector, + val description: String +) + + +class Step5MigrationActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navController = rememberNavController() + val navigator = remember { Navigator(navController) } + val currentBackStackEntry by navController.currentBackStackEntryAsState() + + Scaffold(bottomBar = { + NavigationBar { + TOP_LEVEL_ROUTES.forEach { (key, value) -> + val isSelected = + currentBackStackEntry?.destination.isRouteInHierarchy(key::class) + NavigationBarItem( + selected = isSelected, + onClick = { + navigator.navigate(key, navOptions { + popUpTo(route = RouteA) + }) + }, + icon = { + Icon( + imageVector = value.icon, + contentDescription = value.description + ) + }, + label = { Text(value.description) } + ) + } + } + }) + + { paddingValues -> + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) { + NavHost( + navController = navController, + startDestination = BaseRouteA, + modifier = Modifier.padding(paddingValues) + ) { + featureASection( + onSubRouteClick = { navigator.navigate(RouteA1) }, + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + navigation(startDestination = RouteB) { + composable {} + composable {} + composable {} + } + featureCSection( + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + dialog { key -> + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } + } + } + } + ) { + featureBSection( + onDetailClick = { id -> navigator.navigate(RouteB1(id)) }, + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + } + ) + } + } + } +} + +private fun NavGraphBuilder.featureASection( + onSubRouteClick: () -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteA) { + composable { + ContentRed("Route A title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onSubRouteClick) { + Text("Go to A1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + composable { ContentPink("Route A1 title") } + composable { ContentBlue("Route E title") } + } +} + +private fun EntryProviderBuilder.featureBSection( + onDetailClick: (id: String) -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit +) { + entry { + ContentGreen("Route B title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { onDetailClick("ABC") }) { + Text("Go to B1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + entry { key -> + ContentPurple("Route B1 title. ID: ${key.id}") + } + entry { ContentBlue("Route E title") } + } + +private fun NavGraphBuilder.featureCSection( + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + navigation(startDestination = RouteC) { + composable { + ContentMauve("Route C title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + composable { ContentBlue("Route E title") } + } +} + +private fun NavDestination?.isRouteInHierarchy(route: KClass<*>) = + this?.hierarchy?.any { + it.hasRoute(route) + } ?: false \ No newline at end of file diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt index 17151df..43fca82 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt @@ -40,7 +40,7 @@ import kotlinx.serialization.Serializable * * @see `NavigatorTest`. */ -class Navigator( +class Navigator( private val startRoute: T, private val canTopLevelRoutesExistTogether: Boolean = false ) { diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt index 0c5d74e..4b902c1 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt @@ -55,18 +55,18 @@ import com.example.nav3recipes.ui.setEdgeToEdgeConfig import kotlinx.serialization.Serializable @Serializable -private data object Home : Route(isTopLevel = true) +private data object Home : RouteV2(isTopLevel = true) @Serializable -private data object ChatList : Route(isTopLevel = true) +private data object ChatList : RouteV2(isTopLevel = true) @Serializable -private data object ChatDetail : Route() +private data object ChatDetail : RouteV2() @Serializable -private data object Camera : Route(isTopLevel = true) +private data object Camera : RouteV2(isTopLevel = true) @Serializable -private data object Search : Route(isShared = true) +private data object Search : RouteV2(isShared = true) -private val TOP_LEVEL_ROUTES : List> = listOf( +private val TOP_LEVEL_ROUTES : List> = listOf( NavBarItem(Home, icon = Icons.Default.Home, description = "Home"), NavBarItem(ChatList, icon = Icons.Default.Face, description = "Chat list"), NavBarItem(Camera, icon = Icons.Default.PlayArrow, description = "Camera") @@ -77,7 +77,7 @@ class NavigatorActivity : ComponentActivity() { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) setContent { - val navigator = remember { Navigator(Home) } + val navigator = remember { Navigator(Home) } Scaffold( topBar = { diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorV2.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorV2.kt new file mode 100644 index 0000000..ea9d446 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorV2.kt @@ -0,0 +1,194 @@ +package com.example.nav3recipes.navigator.basic + +import android.annotation.SuppressLint +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.navigation.NavBackStackEntry +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavHostController +import androidx.navigation.toRoute +import com.example.nav3recipes.migration.step4.RouteB +import com.example.nav3recipes.migration.step4.RouteB1 +import com.example.nav3recipes.migration.step4.RouteD +import com.example.nav3recipes.migration.step4.RouteE +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch + +/** + * Navigator that mirrors `NavController`'s back stack + */ +@SuppressLint("RestrictedApi") +class NavigatorV2( + private val navController: NavHostController, + private val startRoute: Any = Unit, + private val canTopLevelRoutesExistTogether: Boolean = false +) { + + val backStack = mutableStateListOf(startRoute) + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Maintain a stack for each top level route + private lateinit var topLevelStacks : MutableMap> + + // Maintain a map of shared routes to their parent stacks + private var sharedRoutes: MutableMap = mutableMapOf() + + val coroutineScope = CoroutineScope(Job()) + + init { + inititalizeTopLevelStacks() + coroutineScope.launch { + navController.currentBackStack.collect { nav2BackStack -> + inititalizeTopLevelStacks() + println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + printTopLevelStacks() + + nav2BackStack.forEach { entry -> + val destination = entry.destination + + if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ + val route = + if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else { + // Non migrated top level route + entry + } + add(route) + } else { + println("Ignoring $entry") + } + } + printTopLevelStacks() + updateBackStack() + } + } + } + + private fun updateBackStack() { + backStack.apply { + clear() + val entries = topLevelStacks.flatMap { it.value } + addAll(entries) + } + printBackStack() + } + + private fun printBackStack() { + println("Back stack: ") + backStack.print() + println("---") + } + + private fun printTopLevelStacks() { + + println("Top level stacks: ") + topLevelStacks.forEach { topLevelStack -> + print("${topLevelStack.key} => ") + topLevelStack.value.print() + } + println("---") + } + + private fun List.print() { + print("[") + forEach { entry -> + if (entry is NavBackStackEntry){ + print("Unmigrated route: ${entry.destination.route}, ") + } else { + print("Migrated route: $entry, ") + } + } + print("]\n") + } + + private fun addTopLevel(route: Any) { + if (route == startRoute) { + clearAllExceptStartStack() + } else { + + // Get the existing stack or create a new one. + val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) + + if (!canTopLevelRoutesExistTogether) { + clearAllExceptStartStack() + } + + topLevelStacks.put(route, topLevelStack) + println("Added top level route $route") + } + topLevelRoute = route + } + + private fun clearAllExceptStartStack() { + // Remove all other top level stacks, except the start stack + val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) + topLevelStacks.clear() + topLevelStacks.put(startRoute, startStack) + } + + private fun inititalizeTopLevelStacks() { + topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) + topLevelRoute = startRoute + } + + private fun add(route: Any) { + println("Attempting to add $route") + if (route is RouteV2.TopLevel) { + println("$route is a top level route") + addTopLevel(route) + } else { + if (route is RouteV2.Shared) { + println("$route is a shared route") + // If the key is already in a stack, remove it + val oldParent = sharedRoutes[route] + if (oldParent != null) { + topLevelStacks[oldParent]?.remove(route) + } + sharedRoutes[route] = topLevelRoute + } else { + println("$route is a normal route") + } + val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false + println("Added $route to $topLevelRoute stack: $hasBeenAdded") + } + } + + /** + * Navigate to the given route. + */ + fun navigate(route: Any) { + add(route) + updateBackStack() + } + + /** + * Go back to the previous route. + */ + fun goBack() { + if (backStack.size <= 1) { + return + } + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + } +} + +sealed interface RouteV2 { + interface TopLevel : RouteV2 + interface Dialog : RouteV2 + interface Shared : RouteV2 +} diff --git a/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt index fabc88c..d24e832 100644 --- a/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt +++ b/app/src/test/java/com/example/nav3recipes/navigator/basic/NavigatorTest.kt @@ -5,30 +5,30 @@ import kotlin.test.assertEquals class NavigatorTest { - private data object A : Route(isTopLevel = true) + private data object A : RouteV2(isTopLevel = true) - private data object A1 : Route() - private data object B : Route(isTopLevel = true) - private data object B1 : Route() - private data object C : Route(isTopLevel = true) - private data object D : Route(isShared = true) + private data object A1 : RouteV2() + private data object B : RouteV2(isTopLevel = true) + private data object B1 : RouteV2() + private data object C : RouteV2(isTopLevel = true) + private data object D : RouteV2(isShared = true) @Test fun backStackContainsOnlyStartRoute(){ - val navigator = Navigator(startRoute = A) - assertEquals(listOf(A), navigator.backStack) + val navigator = Navigator(startRoute = A) + assertEquals(listOf(A), navigator.backStack) } @Test fun navigatingToTopLevelRoute_addsRouteToTopOfStack(){ - val navigator = Navigator(startRoute = A) + val navigator = Navigator(startRoute = A) navigator.navigate(B) assertEquals(listOf(A, B), navigator.backStack) } @Test fun navigatingToChildRoute_addsToCurrentTopLevelStack() { - val navigator = Navigator(startRoute = A) + val navigator = Navigator(startRoute = A) navigator.navigate(B) navigator.navigate(B1) assertEquals(listOf(A, B, B1), navigator.backStack) @@ -36,7 +36,7 @@ class NavigatorTest { @Test fun navigatingToNewTopLevelRoute_popsOtherStacksExceptStartStack() { - val navigator = Navigator(startRoute = A) + val navigator = Navigator(startRoute = A) navigator.navigate(A1) // [A, A1] navigator.navigate(C) // [A, A1, C] navigator.navigate(B) // [A, A1, B] @@ -46,7 +46,7 @@ class NavigatorTest { @Test fun navigatingToSharedRoute_whenItsAlreadyOnStack_movesItToNewStack() { - val navigator = Navigator(startRoute = A) + val navigator = Navigator(startRoute = A) navigator.navigate(D) // [A, D] navigator.navigate(C) // [A, D, C] navigator.navigate(D) // [A, C, D] @@ -56,27 +56,27 @@ class NavigatorTest { @Test fun navigatingToStartRoute_whenOtherRoutesAreOnStack_popsAllOtherRoutes() { - val navigator = Navigator(startRoute = A) + val navigator = Navigator(startRoute = A) navigator.navigate(B) // [A, B] navigator.navigate(C) // [A, B, C] navigator.navigate(A) // [A] - val expected : List = listOf(A) + val expected : List = listOf(A) assertEquals(expected, navigator.backStack) } @Test fun navigatingToStartRoute_whenItHasSubRoutes_retainsSubRoutes() { - val navigator = Navigator(startRoute = A) + val navigator = Navigator(startRoute = A) navigator.navigate(A1) // [A, A1] navigator.navigate(B) // [A, A1, B] navigator.navigate(A) // [A, A1] - val expected : List = listOf(A, A1) + val expected : List = listOf(A, A1) assertEquals(expected, navigator.backStack) } @Test fun repeatedlyNavigatingToTopLevelRoute_retainsSubRoutes(){ - val navigator = Navigator(startRoute = A) + val navigator = Navigator(startRoute = A) navigator.navigate(B) navigator.navigate(B1) navigator.navigate(B) @@ -87,7 +87,7 @@ class NavigatorTest { @Test fun navigatingToTopLevelRoute_whenTopLevelRoutesCanExistTogether_retainsSubRoutes(){ - val navigator = Navigator(startRoute = A, canTopLevelRoutesExistTogether = true) + val navigator = Navigator(startRoute = A, canTopLevelRoutesExistTogether = true) navigator.navigate(A) navigator.navigate(A1) navigator.navigate(B) @@ -101,7 +101,7 @@ class NavigatorTest { @Test fun navigatingBack_isChronological(){ - val navigator = Navigator(startRoute = A) + val navigator = Navigator(startRoute = A) navigator.navigate(A1) navigator.navigate(B) navigator.navigate(B1) @@ -111,7 +111,7 @@ class NavigatorTest { navigator.goBack() assertEquals(listOf(A, A1), navigator.backStack) navigator.goBack() - assertEquals(listOf(A), navigator.backStack) + assertEquals(listOf(A), navigator.backStack) } } \ No newline at end of file From 0110faa038915d5cda0210e7475035c00e188b34 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Wed, 13 Aug 2025 17:29:58 +0100 Subject: [PATCH 10/64] Part way through step 6 of migration --- app/src/main/AndroidManifest.xml | 4 + .../nav3recipes/migration/step6/Navigator.kt | 177 ++++++++++++ .../migration/step6/Step6MigrationActivity.kt | 267 ++++++++++++++++++ .../nav3recipes/navigator/basic/Navigator.kt | 2 +- .../navigator/basic/NavigatorActivity.kt | 14 +- 5 files changed, 456 insertions(+), 8 deletions(-) create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 5c9d57c..a56103a 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -115,6 +115,10 @@ android:name=".migration.step5.Step5MigrationActivity" android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> + diff --git a/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt new file mode 100644 index 0000000..d314fb8 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt @@ -0,0 +1,177 @@ +package com.example.nav3recipes.migration.step6 + +import android.annotation.SuppressLint +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.navigation.NavBackStackEntry +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavHostController +import androidx.navigation.NavOptions +import androidx.navigation.toRoute +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch + +/** + * Navigator that mirrors `NavController`'s back stack + */ +@SuppressLint("RestrictedApi") +class Navigator( + private val navController: NavHostController, + private val startRoute: Any = Unit, + private val canTopLevelRoutesExistTogether: Boolean = false +) { + + val backStack = mutableStateListOf(startRoute) + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Maintain a stack for each top level route + private lateinit var topLevelStacks : MutableMap> + + // Maintain a map of shared routes to their parent stacks + private var sharedRoutes: MutableMap = mutableMapOf() + + val coroutineScope = CoroutineScope(Job()) + + init { + inititalizeTopLevelStacks() + coroutineScope.launch { + navController.currentBackStack.collect { nav2BackStack -> + inititalizeTopLevelStacks() + println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + printTopLevelStacks() + + nav2BackStack.forEach { entry -> + val destination = entry.destination + + if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ + val route = + if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else { + // Non migrated top level route + entry + } + add(route) + } else { + println("Ignoring $entry") + } + } + printTopLevelStacks() + updateBackStack() + } + } + } + + private fun updateBackStack() { + backStack.apply { + clear() + val entries = topLevelStacks.flatMap { it.value } + addAll(entries) + } + printBackStack() + } + + private fun printBackStack() { + println("Back stack: ") + backStack.print() + println("---") + } + + private fun printTopLevelStacks() { + + println("Top level stacks: ") + topLevelStacks.forEach { topLevelStack -> + print("${topLevelStack.key} => ") + topLevelStack.value.print() + } + println("---") + } + + private fun List.print() { + print("[") + forEach { entry -> + if (entry is NavBackStackEntry){ + print("Unmigrated route: ${entry.destination.route}, ") + } else { + print("Migrated route: $entry, ") + } + } + print("]\n") + } + + private fun addTopLevel(route: Any) { + if (route == startRoute) { + clearAllExceptStartStack() + } else { + + // Get the existing stack or create a new one. + val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) + + if (!canTopLevelRoutesExistTogether) { + clearAllExceptStartStack() + } + + topLevelStacks.put(route, topLevelStack) + println("Added top level route $route") + } + topLevelRoute = route + } + + private fun clearAllExceptStartStack() { + // Remove all other top level stacks, except the start stack + val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) + topLevelStacks.clear() + topLevelStacks.put(startRoute, startStack) + } + + private fun inititalizeTopLevelStacks() { + topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) + topLevelRoute = startRoute + } + + private fun add(route: Any) { + println("Attempting to add $route") + if (route is Route.TopLevel) { + println("$route is a top level route") + addTopLevel(route) + } else { + if (route is Route.Shared) { + println("$route is a shared route") + // If the key is already in a stack, remove it + val oldParent = sharedRoutes[route] + if (oldParent != null) { + topLevelStacks[oldParent]?.remove(route) + } + sharedRoutes[route] = topLevelRoute + } else { + println("$route is a normal route") + } + val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false + println("Added $route to $topLevelRoute stack: $hasBeenAdded") + } + } + + fun navigate(route: Any, navOptions: NavOptions? = null) { + navController.navigate(route, navOptions) + } + + fun goBack() { + navController.popBackStack() + } +} + +sealed interface Route { + interface TopLevel : Route + interface Dialog : Route + interface Shared : Route +} diff --git a/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt new file mode 100644 index 0000000..483b63a --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt @@ -0,0 +1,267 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.migration.step6 + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.padding +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.filled.Camera +import androidx.compose.material.icons.filled.Face +import androidx.compose.material.icons.filled.Home +import androidx.compose.material3.Button +import androidx.compose.material3.Icon +import androidx.compose.material3.NavigationBar +import androidx.compose.material3.NavigationBarItem +import androidx.compose.material3.Scaffold +import androidx.compose.material3.Text +import androidx.compose.runtime.getValue +import androidx.compose.runtime.remember +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.graphics.vector.ImageVector +import androidx.navigation.NavDestination +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavDestination.Companion.hierarchy +import androidx.navigation.NavGraphBuilder +import androidx.navigation.compose.NavHost +import androidx.navigation.compose.composable +import androidx.navigation.compose.currentBackStackEntryAsState +import androidx.navigation.compose.dialog +import androidx.navigation.compose.navigation +import androidx.navigation.compose.rememberNavController +import androidx.navigation.navOptions +import androidx.navigation3.runtime.EntryProviderBuilder +import androidx.navigation3.runtime.NavEntry +import androidx.navigation3.runtime.entry +import androidx.navigation3.runtime.entryProvider +import androidx.navigation3.ui.DialogSceneStrategy +import androidx.navigation3.ui.NavDisplay +import com.example.nav3recipes.content.ContentBlue +import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.content.ContentMauve +import com.example.nav3recipes.content.ContentPink +import com.example.nav3recipes.content.ContentPurple +import com.example.nav3recipes.content.ContentRed +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable +import kotlin.reflect.KClass + +@Serializable +data object BaseRouteA +@Serializable +data object RouteA : Route.TopLevel +@Serializable +data object RouteA1 + +@Serializable +data object BaseRouteB +@Serializable +data object RouteB : Route.TopLevel +@Serializable +data class RouteB1(val id: String) + +@Serializable +data object BaseRouteC +@Serializable +data object RouteC : Route.TopLevel +@Serializable +data object RouteD : Route.Dialog +@Serializable +data object RouteE + +private val TOP_LEVEL_ROUTES = mapOf( + BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), + BaseRouteB to NavBarItem(icon = Icons.Default.Face, description = "Route B"), + BaseRouteC to NavBarItem(icon = Icons.Default.Camera, description = "Route C"), +) + +data class NavBarItem( + val icon: ImageVector, + val description: String +) + + +class Step6MigrationActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navController = rememberNavController() + val navigator = remember { Navigator(navController) } + val currentBackStackEntry by navController.currentBackStackEntryAsState() + + Scaffold(bottomBar = { + NavigationBar { + TOP_LEVEL_ROUTES.forEach { (key, value) -> + val isSelected = + currentBackStackEntry?.destination.isRouteInHierarchy(key::class) + NavigationBarItem( + selected = isSelected, + onClick = { + navigator.navigate(key, navOptions { + popUpTo(route = RouteA) + }) + }, + icon = { + Icon( + imageVector = value.icon, + contentDescription = value.description + ) + }, + label = { Text(value.description) } + ) + } + } + }) + + { paddingValues -> + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) { + NavHost( + navController = navController, + startDestination = BaseRouteA, + modifier = Modifier.padding(paddingValues) + ) { + navigation(startDestination = RouteA) { + composable {} + composable {} + composable {} + } + navigation(startDestination = RouteB) { + composable {} + composable {} + composable {} + } + navigation(startDestination = RouteC) { + composable {} + composable {} + } + dialog {} + } + } + } + ) { + featureASection( + onSubRouteClick = { navigator.navigate(RouteA1) }, + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + featureBSection( + onDetailClick = { id -> navigator.navigate(RouteB1(id)) }, + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + featureCSection( + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + entry(metadata = DialogSceneStrategy.dialog()) { + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } + } + ) + } + } + } +} + +private fun EntryProviderBuilder.featureASection( + onSubRouteClick: () -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + entry { + ContentRed("Route A title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onSubRouteClick) { + Text("Go to A1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + entry { ContentPink("Route A1 title") } + entry { ContentBlue("Route E title") } +} + +private fun EntryProviderBuilder.featureBSection( + onDetailClick: (id: String) -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit +) { + entry { + ContentGreen("Route B title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { onDetailClick("ABC") }) { + Text("Go to B1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + entry { key -> + ContentPurple("Route B1 title. ID: ${key.id}") + } + entry { ContentBlue("Route E title") } +} + +private fun EntryProviderBuilder.featureCSection( + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + entry { + ContentMauve("Route C title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + entry { ContentBlue("Route E title") } +} + +private fun NavDestination?.isRouteInHierarchy(route: KClass<*>) = + this?.hierarchy?.any { + it.hasRoute(route) + } ?: false \ No newline at end of file diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt index 43fca82..17151df 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt @@ -40,7 +40,7 @@ import kotlinx.serialization.Serializable * * @see `NavigatorTest`. */ -class Navigator( +class Navigator( private val startRoute: T, private val canTopLevelRoutesExistTogether: Boolean = false ) { diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt index 4b902c1..0c5d74e 100644 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt @@ -55,18 +55,18 @@ import com.example.nav3recipes.ui.setEdgeToEdgeConfig import kotlinx.serialization.Serializable @Serializable -private data object Home : RouteV2(isTopLevel = true) +private data object Home : Route(isTopLevel = true) @Serializable -private data object ChatList : RouteV2(isTopLevel = true) +private data object ChatList : Route(isTopLevel = true) @Serializable -private data object ChatDetail : RouteV2() +private data object ChatDetail : Route() @Serializable -private data object Camera : RouteV2(isTopLevel = true) +private data object Camera : Route(isTopLevel = true) @Serializable -private data object Search : RouteV2(isShared = true) +private data object Search : Route(isShared = true) -private val TOP_LEVEL_ROUTES : List> = listOf( +private val TOP_LEVEL_ROUTES : List> = listOf( NavBarItem(Home, icon = Icons.Default.Home, description = "Home"), NavBarItem(ChatList, icon = Icons.Default.Face, description = "Chat list"), NavBarItem(Camera, icon = Icons.Default.PlayArrow, description = "Camera") @@ -77,7 +77,7 @@ class NavigatorActivity : ComponentActivity() { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) setContent { - val navigator = remember { Navigator(Home) } + val navigator = remember { Navigator(Home) } Scaffold( topBar = { From 309f9124f5397f4c6c368703d15160cb222f1f64 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 14 Aug 2025 12:09:05 +0100 Subject: [PATCH 11/64] Updating all steps --- .../MigrationActivityNavigationTest.kt | 34 ++- .../migration/NavigatorWithDebug.kt | 191 +++++++++++++++++ .../nav3recipes/migration/step2/Navigator.kt | 201 ++++++++++++++++++ .../migration/step2/Step2MigrationActivity.kt | 103 +++++---- .../nav3recipes/migration/step3/Navigator.kt | 186 ++++++++++++++-- .../migration/step3/Step3MigrationActivity.kt | 10 +- .../nav3recipes/migration/step4/Navigator.kt | 65 +++--- .../migration/step4/Step4MigrationActivity.kt | 11 +- .../nav3recipes/migration/step5/Navigator.kt | 76 ++++--- .../migration/step5/Step5MigrationActivity.kt | 20 +- .../nav3recipes/migration/step6/Navigator.kt | 87 +++++--- .../migration/step6/Step6MigrationActivity.kt | 7 +- 12 files changed, 830 insertions(+), 161 deletions(-) create mode 100644 app/src/main/java/com/example/nav3recipes/migration/NavigatorWithDebug.kt create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt diff --git a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt index 6e86616..d42c04a 100644 --- a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +++ b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt @@ -1,5 +1,7 @@ package com.example.nav3recipes +import android.app.Activity +import androidx.activity.ComponentActivity import androidx.compose.ui.test.assertIsSelected import androidx.compose.ui.test.hasText import androidx.compose.ui.test.isSelectable @@ -11,15 +13,37 @@ import com.example.nav3recipes.migration.start.StartMigrationActivity import com.example.nav3recipes.migration.step2.Step2MigrationActivity import com.example.nav3recipes.migration.step3.Step3MigrationActivity import com.example.nav3recipes.migration.step4.Step4MigrationActivity +import com.example.nav3recipes.migration.step5.Step5MigrationActivity +import com.example.nav3recipes.migration.step6.Step6MigrationActivity import org.junit.Rule import org.junit.Test +import org.junit.runner.RunWith +import org.junit.runners.Parameterized +import org.junit.runners.Parameterized.Parameters +/** + * Instrumented navigation tests for each of the migration steps. + */ +@RunWith(Parameterized::class) +class MigrationActivityNavigationTest(activityClass: Class) { -class MigrationActivityNavigationTest { - - // To test each step in the migration plan, change the Activity name below. @get:Rule(order = 0) - val composeTestRule = createAndroidComposeRule() + val composeTestRule = createAndroidComposeRule(activityClass) + + companion object { + @JvmStatic + @Parameters(name = "{0}") + fun data(): Collection> { + return listOf( + /*arrayOf(StartMigrationActivity::class.java), + arrayOf(Step2MigrationActivity::class.java), + arrayOf(Step3MigrationActivity::class.java), + arrayOf(Step4MigrationActivity::class.java),*/ + arrayOf(Step5MigrationActivity::class.java), + /*arrayOf(Step6MigrationActivity::class.java)*/ + ) + } + } @Test fun firstScreen_isA() { @@ -121,7 +145,7 @@ class MigrationActivityNavigationTest { } /** - * These 2 tests fail and they shouldn't + * TODO: Investigate why these 2 dialog tests sometimes fail. */ @Test fun navigateToDialogD_onB_showsDialogContentAndDismisses() { diff --git a/app/src/main/java/com/example/nav3recipes/migration/NavigatorWithDebug.kt b/app/src/main/java/com/example/nav3recipes/migration/NavigatorWithDebug.kt new file mode 100644 index 0000000..3ef99a6 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/NavigatorWithDebug.kt @@ -0,0 +1,191 @@ +package com.example.nav3recipes.migration + +import android.annotation.SuppressLint +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.navigation.NavBackStackEntry +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavHostController +import androidx.navigation.toRoute +import com.example.nav3recipes.migration.step4.RouteB +import com.example.nav3recipes.migration.step4.RouteB1 +import com.example.nav3recipes.migration.step4.RouteD +import com.example.nav3recipes.migration.step4.RouteE +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch + +/** + * Navigator that mirrors `NavController`'s back stack + */ +@SuppressLint("RestrictedApi") +class Navigator( + private val navController: NavHostController, + private val startRoute: Any = Unit, + private val canTopLevelRoutesExistTogether: Boolean = false +) { + + val backStack = mutableStateListOf(startRoute) + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Maintain a stack for each top level route + private lateinit var topLevelStacks : MutableMap> + + // Maintain a map of shared routes to their parent stacks + private var sharedRoutes: MutableMap = mutableMapOf() + + val coroutineScope = CoroutineScope(Job()) + + init { + inititalizeTopLevelStacks() + coroutineScope.launch { + navController.currentBackStack.collect { nav2BackStack -> + inititalizeTopLevelStacks() + println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + printTopLevelStacks() + + nav2BackStack.forEach { entry -> + val destination = entry.destination + + if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ + val route = + if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else { + // Non migrated top level route + entry + } + add(route) + } else { + println("Ignoring $entry") + } + } + printTopLevelStacks() + updateBackStack() + } + } + } + + private fun updateBackStack() { + backStack.apply { + clear() + val entries = topLevelStacks.flatMap { it.value } + addAll(entries) + } + printBackStack() + } + + private fun printBackStack() { + println("Back stack: ") + backStack.print() + println("---") + } + + private fun printTopLevelStacks() { + + println("Top level stacks: ") + topLevelStacks.forEach { topLevelStack -> + print("${topLevelStack.key} => ") + topLevelStack.value.print() + } + println("---") + } + + private fun List.print() { + print("[") + forEach { entry -> + if (entry is NavBackStackEntry){ + print("Unmigrated route: ${entry.destination.route}, ") + } else { + print("Migrated route: $entry, ") + } + } + print("]\n") + } + + private fun addTopLevel(route: Any) { + if (route == startRoute) { + clearAllExceptStartStack() + } else { + + // Get the existing stack or create a new one. + val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) + + if (!canTopLevelRoutesExistTogether) { + clearAllExceptStartStack() + } + + topLevelStacks.put(route, topLevelStack) + println("Added top level route $route") + } + topLevelRoute = route + } + + private fun clearAllExceptStartStack() { + // Remove all other top level stacks, except the start stack + val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) + topLevelStacks.clear() + topLevelStacks.put(startRoute, startStack) + } + + private fun inititalizeTopLevelStacks() { + topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) + topLevelRoute = startRoute + } + + private fun add(route: Any) { + println("Attempting to add $route") + if (route is Route.TopLevel) { + println("$route is a top level route") + addTopLevel(route) + } else { + if (route is Route.Shared) { + println("$route is a shared route") + // If the key is already in a stack, remove it + val oldParent = sharedRoutes[route] + if (oldParent != null) { + topLevelStacks[oldParent]?.remove(route) + } + sharedRoutes[route] = topLevelRoute + } else { + println("$route is a normal route") + } + val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false + println("Added $route to $topLevelRoute stack: $hasBeenAdded") + } + } + + /** + * Navigate to the given route. + */ + fun navigate(route: Any) { + add(route) + updateBackStack() + } + + /** + * Go back to the previous route. + */ + fun goBack() { + if (backStack.size <= 1) { + return + } + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + } +} + +sealed interface Route { + interface TopLevel : Route + interface Shared : Route +} diff --git a/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt new file mode 100644 index 0000000..124e452 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt @@ -0,0 +1,201 @@ +package com.example.nav3recipes.migration.step2 + +import android.annotation.SuppressLint +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.navigation.NavBackStackEntry +import androidx.navigation.NavDestination.Companion.hasRoute +import androidx.navigation.NavHostController +import androidx.navigation.NavOptions +import androidx.navigation.toRoute +import com.example.nav3recipes.migration.step4.RouteB +import com.example.nav3recipes.migration.step4.RouteB1 +import com.example.nav3recipes.migration.step4.RouteE +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Job +import kotlinx.coroutines.launch + +/** + * Navigator that mirrors `NavController`'s back stack + */ +@SuppressLint("RestrictedApi") +internal class Navigator( + private val navController: NavHostController, + private val startRoute: Any = Unit, + private val canTopLevelRoutesExistTogether: Boolean = false, + private val shouldPrintDebugInfo: Boolean = false +) { + + val backStack = mutableStateListOf(startRoute) + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Maintain a stack for each top level route + private lateinit var topLevelStacks : MutableMap> + + // Maintain a map of shared routes to their parent stacks + private var sharedRoutes: MutableMap = mutableMapOf() + + val coroutineScope = CoroutineScope(Job()) + + init { + inititalizeTopLevelStacks() + coroutineScope.launch { + navController.currentBackStack.collect { nav2BackStack -> + inititalizeTopLevelStacks() + navlog("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + printTopLevelStacks() + + nav2BackStack.forEach { entry -> + val destination = entry.destination + + if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ + val route = + // Add migrated routes here + if (false) { + } else { + // Non migrated top level route + entry + } + add(route) + } else { + navlog("Ignoring $entry") + } + } + printTopLevelStacks() + updateBackStack() + } + } + } + + private fun updateBackStack() { + backStack.apply { + clear() + val entries = topLevelStacks.flatMap { it.value } + addAll(entries) + } + printBackStack() + } + + fun navlog(message: String){ + if (shouldPrintDebugInfo){ + println(message) + } + } + + private fun printBackStack() { + navlog("Back stack: ${backStack.getDebugString()}") + } + + private fun printTopLevelStacks() { + + navlog("Top level stacks: ") + topLevelStacks.forEach { topLevelStack -> + navlog(" ${topLevelStack.key} => ${topLevelStack.value.getDebugString()}") + } + } + + private fun List.getDebugString() : String { + val message = StringBuilder("[") + forEach { entry -> + if (entry is NavBackStackEntry){ + message.append("Unmigrated route: ${entry.destination.route}, ") + } else { + message.append("Migrated route: $entry, ") + } + } + message.append("]\n") + return message.toString() + } + + private fun addTopLevel(route: Any) { + if (route == startRoute) { + clearAllExceptStartStack() + } else { + + // Get the existing stack or create a new one. + val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) + + if (!canTopLevelRoutesExistTogether) { + clearAllExceptStartStack() + } + + topLevelStacks.put(route, topLevelStack) + navlog("Added top level route $route") + } + topLevelRoute = route + } + + private fun clearAllExceptStartStack() { + // Remove all other top level stacks, except the start stack + val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) + topLevelStacks.clear() + topLevelStacks.put(startRoute, startStack) + } + + private fun inititalizeTopLevelStacks() { + topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) + topLevelRoute = startRoute + } + + private fun add(route: Any) { + navlog("Attempting to add $route") + if (route is Route.TopLevel) { + navlog("$route is a top level route") + addTopLevel(route) + } else { + if (route is Route.Shared) { + navlog("$route is a shared route") + // If the key is already in a stack, remove it + val oldParent = sharedRoutes[route] + if (oldParent != null) { + topLevelStacks[oldParent]?.remove(route) + } + sharedRoutes[route] = topLevelRoute + } else { + navlog("$route is a normal route") + } + val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false + navlog("Added $route to $topLevelRoute stack: $hasBeenAdded") + } + } + + /** + * Navigate to the given route. + */ + fun navigate(route: Any, navOptions: NavOptions? = null) { + navController.navigate(route, navOptions) + + // TODO: add instruction on when to uncomment this and remove the line above + /* + add(route) + updateBackStack() + */ + } + + /** + * Go back to the previous route. + */ + fun goBack() { + navController.popBackStack() + + // TODO: add instruction on when to uncomment this and remove the line above + /* + if (backStack.size <= 1) { + return + } + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + */ + } +} + +sealed interface Route { + interface TopLevel : Route + interface Shared : Route +} diff --git a/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt index b46eb5a..98c2047 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt @@ -33,6 +33,7 @@ import androidx.compose.material3.NavigationBarItem import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.runtime.getValue +import androidx.compose.runtime.remember import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color @@ -41,7 +42,6 @@ import androidx.navigation.NavDestination import androidx.navigation.NavDestination.Companion.hasRoute import androidx.navigation.NavDestination.Companion.hierarchy import androidx.navigation.NavGraphBuilder -import androidx.navigation.NavHostController import androidx.navigation.compose.NavHost import androidx.navigation.compose.composable import androidx.navigation.compose.currentBackStackEntryAsState @@ -50,6 +50,9 @@ import androidx.navigation.compose.navigation import androidx.navigation.compose.rememberNavController import androidx.navigation.navOptions import androidx.navigation.toRoute +import androidx.navigation3.runtime.NavEntry +import androidx.navigation3.runtime.entryProvider +import androidx.navigation3.ui.NavDisplay import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen import com.example.nav3recipes.content.ContentMauve @@ -60,18 +63,28 @@ import com.example.nav3recipes.ui.setEdgeToEdgeConfig import kotlinx.serialization.Serializable import kotlin.reflect.KClass -@Serializable private data object BaseRouteA -@Serializable private data object RouteA : Route.TopLevel -@Serializable private data object RouteA1 +@Serializable +private data object BaseRouteA +@Serializable +private data object RouteA +@Serializable +private data object RouteA1 -@Serializable private data object BaseRouteB -@Serializable private data object RouteB : Route.TopLevel -@Serializable private data class RouteB1(val id: String) +@Serializable +private data object BaseRouteB +@Serializable +private data object RouteB +@Serializable +private data class RouteB1(val id: String) -@Serializable private data object BaseRouteC -@Serializable private data object RouteC : Route.TopLevel -@Serializable private data object RouteD : Route.Dialog -@Serializable private data object RouteE +@Serializable +private data object BaseRouteC +@Serializable +private data object RouteC +@Serializable +private data object RouteD +@Serializable +private data object RouteE private val TOP_LEVEL_ROUTES = mapOf( BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), @@ -84,11 +97,6 @@ data class NavBarItem( val description: String ) -sealed interface Route { - interface TopLevel : Route - interface Dialog : Route -} - class Step2MigrationActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { @@ -96,12 +104,14 @@ class Step2MigrationActivity : ComponentActivity() { super.onCreate(savedInstanceState) setContent { val navController = rememberNavController() + val navigator = remember { Navigator(navController) } val currentBackStackEntry by navController.currentBackStackEntryAsState() Scaffold(bottomBar = { NavigationBar { TOP_LEVEL_ROUTES.forEach { (key, value) -> - val isSelected = currentBackStackEntry?.destination.isRouteInHierarchy(key::class) + val isSelected = + currentBackStackEntry?.destination.isRouteInHierarchy(key::class) NavigationBarItem( selected = isSelected, onClick = { @@ -122,29 +132,44 @@ class Step2MigrationActivity : ComponentActivity() { }) { paddingValues -> - NavHost( - navController = navController, - startDestination = BaseRouteA, - modifier = Modifier.padding(paddingValues) - ) { - featureASection( - onSubRouteClick = { navController.navigate(RouteA1) }, - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - featureBSection( - onDetailClick = { id -> navController.navigate(RouteB1(id)) }, - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - featureCSection( - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - dialog { key -> - Text(modifier = Modifier.background(Color.White), text = "Route D title (dialog)") + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) { + NavHost( + navController = navController, + startDestination = BaseRouteA, + modifier = Modifier.padding(paddingValues) + ) { + featureASection( + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureBSection( + onDetailClick = { id -> navController.navigate(RouteB1(id)) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureCSection( + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + dialog { key -> + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } + } + } + } + ) { + // No nav entries added yet. } - } + ) } } } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt index 92ea6fd..392d153 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt @@ -1,8 +1,18 @@ package com.example.nav3recipes.migration.step3 import android.annotation.SuppressLint +import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.navigation.NavBackStackEntry +import androidx.navigation.NavDestination.Companion.hasRoute import androidx.navigation.NavHostController +import androidx.navigation.NavOptions +import androidx.navigation.toRoute +import com.example.nav3recipes.migration.step4.RouteB +import com.example.nav3recipes.migration.step4.RouteB1 +import com.example.nav3recipes.migration.step4.RouteE import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Job import kotlinx.coroutines.launch @@ -11,37 +21,181 @@ import kotlinx.coroutines.launch * Navigator that mirrors `NavController`'s back stack */ @SuppressLint("RestrictedApi") -class Navigator( - private val navController: NavHostController +internal class Navigator( + private val navController: NavHostController, + private val startRoute: Any = Unit, + private val canTopLevelRoutesExistTogether: Boolean = false, + private val shouldPrintDebugInfo: Boolean = false ) { + val backStack = mutableStateListOf(startRoute) + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Maintain a stack for each top level route + private lateinit var topLevelStacks : MutableMap> + + // Maintain a map of shared routes to their parent stacks + private var sharedRoutes: MutableMap = mutableMapOf() + val coroutineScope = CoroutineScope(Job()) init { + inititalizeTopLevelStacks() coroutineScope.launch { navController.currentBackStack.collect { nav2BackStack -> - if (nav2BackStack.isNotEmpty()){ - backStack.clear() - val entriesToAdd = nav2BackStack.mapNotNull { entry -> - // We only care about navigable destinations - val navigatorName = entry.destination.navigatorName - if (navigatorName == "composable" || navigatorName == "dialog"){ - entry - } else { - null - } + inititalizeTopLevelStacks() + navlog("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + printTopLevelStacks() + + nav2BackStack.forEach { entry -> + val destination = entry.destination + + if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ + val route = + // Add migrated routes here + if (false) { + } else { + // Non migrated top level route + entry + } + add(route) + } else { + navlog("Ignoring $entry") } - println("Back stack: $entriesToAdd") - backStack.addAll(entriesToAdd) } + printTopLevelStacks() + updateBackStack() + } + } + } + + private fun updateBackStack() { + backStack.apply { + clear() + val entries = topLevelStacks.flatMap { it.value } + addAll(entries) + } + printBackStack() + } + + fun navlog(message: String){ + if (shouldPrintDebugInfo){ + println(message) + } + } + + private fun printBackStack() { + navlog("Back stack: ${backStack.getDebugString()}") + } + + private fun printTopLevelStacks() { + + navlog("Top level stacks: ") + topLevelStacks.forEach { topLevelStack -> + navlog(" ${topLevelStack.key} => ${topLevelStack.value.getDebugString()}") + } + } + + private fun List.getDebugString() : String { + val message = StringBuilder("[") + forEach { entry -> + if (entry is NavBackStackEntry){ + message.append("Unmigrated route: ${entry.destination.route}, ") + } else { + message.append("Migrated route: $entry, ") + } + } + message.append("]\n") + return message.toString() + } + + private fun addTopLevel(route: Any) { + if (route == startRoute) { + clearAllExceptStartStack() + } else { + + // Get the existing stack or create a new one. + val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) + + if (!canTopLevelRoutesExistTogether) { + clearAllExceptStartStack() + } + + topLevelStacks.put(route, topLevelStack) + navlog("Added top level route $route") + } + topLevelRoute = route + } + + private fun clearAllExceptStartStack() { + // Remove all other top level stacks, except the start stack + val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) + topLevelStacks.clear() + topLevelStacks.put(startRoute, startStack) + } + + private fun inititalizeTopLevelStacks() { + topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) + topLevelRoute = startRoute + } + + private fun add(route: Any) { + navlog("Attempting to add $route") + if (route is Route.TopLevel) { + navlog("$route is a top level route") + addTopLevel(route) + } else { + if (route is Route.Shared) { + navlog("$route is a shared route") + // If the key is already in a stack, remove it + val oldParent = sharedRoutes[route] + if (oldParent != null) { + topLevelStacks[oldParent]?.remove(route) + } + sharedRoutes[route] = topLevelRoute + } else { + navlog("$route is a normal route") } + val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false + navlog("Added $route to $topLevelRoute stack: $hasBeenAdded") } } - val backStack = mutableStateListOf(Unit) + /** + * Navigate to the given route. + */ + fun navigate(route: Any, navOptions: NavOptions? = null) { + navController.navigate(route, navOptions) + + // TODO: add instruction on when to uncomment this and remove the line above + /* + add(route) + updateBackStack() + */ + } + + /** + * Go back to the previous route. + */ + fun goBack() { + navController.popBackStack() + + // TODO: add instruction on when to uncomment this and remove the line above + /* + if (backStack.size <= 1) { + return + } + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + */ + } } sealed interface Route { interface TopLevel : Route - interface Dialog : Route + interface Shared : Route } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt index 5383a36..86118c8 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt @@ -42,7 +42,6 @@ import androidx.navigation.NavDestination import androidx.navigation.NavDestination.Companion.hasRoute import androidx.navigation.NavDestination.Companion.hierarchy import androidx.navigation.NavGraphBuilder -import androidx.navigation.NavHostController import androidx.navigation.compose.NavHost import androidx.navigation.compose.composable import androidx.navigation.compose.currentBackStackEntryAsState @@ -67,7 +66,7 @@ import kotlin.reflect.KClass @Serializable private data object BaseRouteA @Serializable -private data object RouteA : Route.TopLevel +private data object RouteA @Serializable private data object RouteA1 @@ -81,11 +80,11 @@ private data class RouteB1(val id: String) @Serializable private data object BaseRouteC @Serializable -private data object RouteC : Route.TopLevel +private data object RouteC @Serializable -private data object RouteD : Route.Dialog +private data object RouteD @Serializable -private data object RouteE +private data object RouteE : Route.Shared private val TOP_LEVEL_ROUTES = mapOf( BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), @@ -135,6 +134,7 @@ class Step3MigrationActivity : ComponentActivity() { { paddingValues -> NavDisplay( backStack = navigator.backStack, + onBack = { navigator.goBack() }, entryProvider = entryProvider( fallback = { key -> NavEntry(key = key) { diff --git a/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt index e866aef..8eae6ad 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt @@ -8,6 +8,7 @@ import androidx.compose.runtime.setValue import androidx.navigation.NavBackStackEntry import androidx.navigation.NavDestination.Companion.hasRoute import androidx.navigation.NavHostController +import androidx.navigation.NavOptions import androidx.navigation.toRoute import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Job @@ -17,10 +18,11 @@ import kotlinx.coroutines.launch * Navigator that mirrors `NavController`'s back stack */ @SuppressLint("RestrictedApi") -class Navigator( +internal class Navigator( private val navController: NavHostController, private val startRoute: Any = Unit, - private val canTopLevelRoutesExistTogether: Boolean = false + private val canTopLevelRoutesExistTogether: Boolean = false, + private val shouldPrintDebugInfo: Boolean = false ) { val backStack = mutableStateListOf(startRoute) @@ -40,7 +42,7 @@ class Navigator( coroutineScope.launch { navController.currentBackStack.collect { nav2BackStack -> inititalizeTopLevelStacks() - println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + navlog("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") printTopLevelStacks() nav2BackStack.forEach { entry -> @@ -52,8 +54,6 @@ class Navigator( entry.toRoute() } else if (destination.hasRoute()) { entry.toRoute() - } else if (destination.hasRoute()) { - entry.toRoute() } else if (destination.hasRoute()) { entry.toRoute() } else { @@ -62,7 +62,7 @@ class Navigator( } add(route) } else { - println("Ignoring $entry") + navlog("Ignoring $entry") } } printTopLevelStacks() @@ -79,33 +79,36 @@ class Navigator( } printBackStack() } + + fun navlog(message: String){ + if (shouldPrintDebugInfo){ + println(message) + } + } private fun printBackStack() { - println("Back stack: ") - backStack.print() - println("---") + navlog("Back stack: ${backStack.getDebugString()}") } private fun printTopLevelStacks() { - println("Top level stacks: ") + navlog("Top level stacks: ") topLevelStacks.forEach { topLevelStack -> - print("${topLevelStack.key} => ") - topLevelStack.value.print() + navlog(" ${topLevelStack.key} => ${topLevelStack.value.getDebugString()}") } - println("---") } - private fun List.print() { - print("[") + private fun List.getDebugString() : String { + val message = StringBuilder("[") forEach { entry -> if (entry is NavBackStackEntry){ - print("Unmigrated route: ${entry.destination.route}, ") + message.append("Unmigrated route: ${entry.destination.route}, ") } else { - print("Migrated route: $entry, ") + message.append("Migrated route: $entry, ") } } - print("]\n") + message.append("]\n") + return message.toString() } private fun addTopLevel(route: Any) { @@ -121,7 +124,7 @@ class Navigator( } topLevelStacks.put(route, topLevelStack) - println("Added top level route $route") + navlog("Added top level route $route") } topLevelRoute = route } @@ -139,13 +142,13 @@ class Navigator( } private fun add(route: Any) { - println("Attempting to add $route") + navlog("Attempting to add $route") if (route is Route.TopLevel) { - println("$route is a top level route") + navlog("$route is a top level route") addTopLevel(route) } else { if (route is Route.Shared) { - println("$route is a shared route") + navlog("$route is a shared route") // If the key is already in a stack, remove it val oldParent = sharedRoutes[route] if (oldParent != null) { @@ -153,25 +156,34 @@ class Navigator( } sharedRoutes[route] = topLevelRoute } else { - println("$route is a normal route") + navlog("$route is a normal route") } val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false - println("Added $route to $topLevelRoute stack: $hasBeenAdded") + navlog("Added $route to $topLevelRoute stack: $hasBeenAdded") } } /** * Navigate to the given route. */ - fun navigate(route: Any) { + fun navigate(route: Any, navOptions: NavOptions? = null) { + navController.navigate(route, navOptions) + + // TODO: add instruction on when to uncomment this and remove the line above + /* add(route) updateBackStack() + */ } /** * Go back to the previous route. */ fun goBack() { + navController.popBackStack() + + // TODO: add instruction on when to uncomment this and remove the line above + /* if (backStack.size <= 1) { return } @@ -180,11 +192,12 @@ class Navigator( topLevelStacks.remove(removedKey) topLevelRoute = topLevelStacks.keys.last() updateBackStack() + */ } + } sealed interface Route { interface TopLevel : Route - interface Dialog : Route interface Shared : Route } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt index c1391b0..522b3c5 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt @@ -49,7 +49,6 @@ import androidx.navigation.compose.dialog import androidx.navigation.compose.navigation import androidx.navigation.compose.rememberNavController import androidx.navigation.navOptions -import androidx.navigation.toRoute import androidx.navigation3.runtime.EntryProviderBuilder import androidx.navigation3.runtime.NavEntry import androidx.navigation3.runtime.entry @@ -68,7 +67,7 @@ import kotlin.reflect.KClass @Serializable data object BaseRouteA @Serializable -data object RouteA : Route.TopLevel +data object RouteA @Serializable data object RouteA1 @@ -82,9 +81,9 @@ data class RouteB1(val id: String) @Serializable data object BaseRouteC @Serializable -data object RouteC : Route.TopLevel +data object RouteC @Serializable -data object RouteD : Route.Dialog +data object RouteD @Serializable data object RouteE @@ -107,7 +106,7 @@ class Step4MigrationActivity : ComponentActivity() { super.onCreate(savedInstanceState) setContent { val navController = rememberNavController() - val navigator = remember { Navigator(navController) } + val navigator = remember { Navigator(navController, shouldPrintDebugInfo = true) } val currentBackStackEntry by navController.currentBackStackEntryAsState() Scaffold(bottomBar = { @@ -137,7 +136,7 @@ class Step4MigrationActivity : ComponentActivity() { { paddingValues -> NavDisplay( backStack = navigator.backStack, - onBack = { navController.popBackStack() }, + onBack = { navigator.goBack() }, entryProvider = entryProvider( fallback = { key -> NavEntry(key = key) { diff --git a/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt index 3ec6024..c351a19 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt @@ -18,10 +18,11 @@ import kotlinx.coroutines.launch * Navigator that mirrors `NavController`'s back stack */ @SuppressLint("RestrictedApi") -class Navigator( +internal class Navigator( private val navController: NavHostController, private val startRoute: Any = Unit, - private val canTopLevelRoutesExistTogether: Boolean = false + private val canTopLevelRoutesExistTogether: Boolean = false, + private val shouldPrintDebugInfo: Boolean = false ) { val backStack = mutableStateListOf(startRoute) @@ -41,7 +42,7 @@ class Navigator( coroutineScope.launch { navController.currentBackStack.collect { nav2BackStack -> inititalizeTopLevelStacks() - println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + navlog("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") printTopLevelStacks() nav2BackStack.forEach { entry -> @@ -53,8 +54,6 @@ class Navigator( entry.toRoute() } else if (destination.hasRoute()) { entry.toRoute() - } else if (destination.hasRoute()) { - entry.toRoute() } else if (destination.hasRoute()) { entry.toRoute() } else { @@ -63,7 +62,7 @@ class Navigator( } add(route) } else { - println("Ignoring $entry") + navlog("Ignoring $entry") } } printTopLevelStacks() @@ -80,33 +79,36 @@ class Navigator( } printBackStack() } + + fun navlog(message: String){ + if (shouldPrintDebugInfo){ + println(message) + } + } private fun printBackStack() { - println("Back stack: ") - backStack.print() - println("---") + navlog("Back stack: ${backStack.getDebugString()}") } private fun printTopLevelStacks() { - println("Top level stacks: ") + navlog("Top level stacks: ") topLevelStacks.forEach { topLevelStack -> - print("${topLevelStack.key} => ") - topLevelStack.value.print() + navlog(" ${topLevelStack.key} => ${topLevelStack.value.getDebugString()}") } - println("---") } - private fun List.print() { - print("[") + private fun List.getDebugString() : String { + val message = StringBuilder("[") forEach { entry -> if (entry is NavBackStackEntry){ - print("Unmigrated route: ${entry.destination.route}, ") + message.append("Unmigrated route: ${entry.destination.route}, ") } else { - print("Migrated route: $entry, ") + message.append("Migrated route: $entry, ") } } - print("]\n") + message.append("]\n") + return message.toString() } private fun addTopLevel(route: Any) { @@ -122,7 +124,7 @@ class Navigator( } topLevelStacks.put(route, topLevelStack) - println("Added top level route $route") + navlog("Added top level route $route") } topLevelRoute = route } @@ -140,13 +142,13 @@ class Navigator( } private fun add(route: Any) { - println("Attempting to add $route") + navlog("Attempting to add $route") if (route is Route.TopLevel) { - println("$route is a top level route") + navlog("$route is a top level route") addTopLevel(route) } else { if (route is Route.Shared) { - println("$route is a shared route") + navlog("$route is a shared route") // If the key is already in a stack, remove it val oldParent = sharedRoutes[route] if (oldParent != null) { @@ -154,24 +156,48 @@ class Navigator( } sharedRoutes[route] = topLevelRoute } else { - println("$route is a normal route") + navlog("$route is a normal route") } val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false - println("Added $route to $topLevelRoute stack: $hasBeenAdded") + navlog("Added $route to $topLevelRoute stack: $hasBeenAdded") } } + /** + * Navigate to the given route. + */ fun navigate(route: Any, navOptions: NavOptions? = null) { navController.navigate(route, navOptions) + + // TODO: add instruction on when to uncomment this and remove the line above + /* + add(route) + updateBackStack() + */ } + /** + * Go back to the previous route. + */ fun goBack() { navController.popBackStack() + + // TODO: add instruction on when to uncomment this and remove the line above + /* + if (backStack.size <= 1) { + return + } + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + */ } + } sealed interface Route { interface TopLevel : Route - interface Dialog : Route interface Shared : Route } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt index 95f6654..cbe3cf1 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt @@ -67,7 +67,7 @@ import kotlin.reflect.KClass @Serializable data object BaseRouteA @Serializable -data object RouteA : Route.TopLevel +data object RouteA @Serializable data object RouteA1 @@ -81,9 +81,9 @@ data class RouteB1(val id: String) @Serializable data object BaseRouteC @Serializable -data object RouteC : Route.TopLevel +data object RouteC @Serializable -data object RouteD : Route.Dialog +data object RouteD @Serializable data object RouteE @@ -106,7 +106,7 @@ class Step5MigrationActivity : ComponentActivity() { super.onCreate(savedInstanceState) setContent { val navController = rememberNavController() - val navigator = remember { Navigator(navController) } + val navigator = remember { Navigator(navController, shouldPrintDebugInfo = true) } val currentBackStackEntry by navController.currentBackStackEntryAsState() Scaffold(bottomBar = { @@ -117,7 +117,7 @@ class Step5MigrationActivity : ComponentActivity() { NavigationBarItem( selected = isSelected, onClick = { - navigator.navigate(key, navOptions { + navController.navigate(key, navOptions { popUpTo(route = RouteA) }) }, @@ -146,9 +146,9 @@ class Step5MigrationActivity : ComponentActivity() { modifier = Modifier.padding(paddingValues) ) { featureASection( - onSubRouteClick = { navigator.navigate(RouteA1) }, - onDialogClick = { navigator.navigate(RouteD) }, - onOtherClick = { navigator.navigate(RouteE) } + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } ) navigation(startDestination = RouteB) { composable {} @@ -156,8 +156,8 @@ class Step5MigrationActivity : ComponentActivity() { composable {} } featureCSection( - onDialogClick = { navigator.navigate(RouteD) }, - onOtherClick = { navigator.navigate(RouteE) } + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } ) dialog { key -> Text( diff --git a/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt index d314fb8..6b3cd1d 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt @@ -10,6 +10,9 @@ import androidx.navigation.NavDestination.Companion.hasRoute import androidx.navigation.NavHostController import androidx.navigation.NavOptions import androidx.navigation.toRoute +import com.example.nav3recipes.migration.step4.RouteB +import com.example.nav3recipes.migration.step4.RouteB1 +import com.example.nav3recipes.migration.step4.RouteE import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Job import kotlinx.coroutines.launch @@ -18,10 +21,11 @@ import kotlinx.coroutines.launch * Navigator that mirrors `NavController`'s back stack */ @SuppressLint("RestrictedApi") -class Navigator( +internal class Navigator( private val navController: NavHostController, private val startRoute: Any = Unit, - private val canTopLevelRoutesExistTogether: Boolean = false + private val canTopLevelRoutesExistTogether: Boolean = false, + private val shouldPrintDebugInfo: Boolean = false ) { val backStack = mutableStateListOf(startRoute) @@ -41,7 +45,7 @@ class Navigator( coroutineScope.launch { navController.currentBackStack.collect { nav2BackStack -> inititalizeTopLevelStacks() - println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") + navlog("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") printTopLevelStacks() nav2BackStack.forEach { entry -> @@ -53,17 +57,23 @@ class Navigator( entry.toRoute() } else if (destination.hasRoute()) { entry.toRoute() - } else if (destination.hasRoute()) { - entry.toRoute() } else if (destination.hasRoute()) { entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() } else { // Non migrated top level route entry } add(route) } else { - println("Ignoring $entry") + navlog("Ignoring $entry") } } printTopLevelStacks() @@ -80,33 +90,36 @@ class Navigator( } printBackStack() } + + fun navlog(message: String){ + if (shouldPrintDebugInfo){ + println(message) + } + } private fun printBackStack() { - println("Back stack: ") - backStack.print() - println("---") + navlog("Back stack: ${backStack.getDebugString()}") } private fun printTopLevelStacks() { - println("Top level stacks: ") + navlog("Top level stacks: ") topLevelStacks.forEach { topLevelStack -> - print("${topLevelStack.key} => ") - topLevelStack.value.print() + navlog(" ${topLevelStack.key} => ${topLevelStack.value.getDebugString()}") } - println("---") } - private fun List.print() { - print("[") + private fun List.getDebugString() : String { + val message = StringBuilder("[") forEach { entry -> if (entry is NavBackStackEntry){ - print("Unmigrated route: ${entry.destination.route}, ") + message.append("Unmigrated route: ${entry.destination.route}, ") } else { - print("Migrated route: $entry, ") + message.append("Migrated route: $entry, ") } } - print("]\n") + message.append("]\n") + return message.toString() } private fun addTopLevel(route: Any) { @@ -122,7 +135,7 @@ class Navigator( } topLevelStacks.put(route, topLevelStack) - println("Added top level route $route") + navlog("Added top level route $route") } topLevelRoute = route } @@ -140,13 +153,13 @@ class Navigator( } private fun add(route: Any) { - println("Attempting to add $route") + navlog("Attempting to add $route") if (route is Route.TopLevel) { - println("$route is a top level route") + navlog("$route is a top level route") addTopLevel(route) } else { if (route is Route.Shared) { - println("$route is a shared route") + navlog("$route is a shared route") // If the key is already in a stack, remove it val oldParent = sharedRoutes[route] if (oldParent != null) { @@ -154,24 +167,48 @@ class Navigator( } sharedRoutes[route] = topLevelRoute } else { - println("$route is a normal route") + navlog("$route is a normal route") } val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false - println("Added $route to $topLevelRoute stack: $hasBeenAdded") + navlog("Added $route to $topLevelRoute stack: $hasBeenAdded") } } + /** + * Navigate to the given route. + */ fun navigate(route: Any, navOptions: NavOptions? = null) { navController.navigate(route, navOptions) + + // TODO: add instruction on when to uncomment this and remove the line above + /* + add(route) + updateBackStack() + */ } + /** + * Go back to the previous route. + */ fun goBack() { navController.popBackStack() + + // TODO: add instruction on when to uncomment this and remove the line above + /* + if (backStack.size <= 1) { + return + } + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + */ } + } sealed interface Route { interface TopLevel : Route - interface Dialog : Route interface Shared : Route } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt index 483b63a..92dc989 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt @@ -84,9 +84,9 @@ data object BaseRouteC @Serializable data object RouteC : Route.TopLevel @Serializable -data object RouteD : Route.Dialog +data object RouteD @Serializable -data object RouteE +data object RouteE : Route.Shared private val TOP_LEVEL_ROUTES = mapOf( BaseRouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), @@ -138,6 +138,7 @@ class Step6MigrationActivity : ComponentActivity() { NavDisplay( backStack = navigator.backStack, onBack = { navigator.goBack() }, + sceneStrategy = remember { DialogSceneStrategy() }, entryProvider = entryProvider( fallback = { key -> NavEntry(key = key) { @@ -239,7 +240,6 @@ private fun EntryProviderBuilder.featureBSection( entry { key -> ContentPurple("Route B1 title. ID: ${key.id}") } - entry { ContentBlue("Route E title") } } private fun EntryProviderBuilder.featureCSection( @@ -258,7 +258,6 @@ private fun EntryProviderBuilder.featureCSection( } } } - entry { ContentBlue("Route E title") } } private fun NavDestination?.isRouteInHierarchy(route: KClass<*>) = From 5019ac2f2a69dee7450c39534eb653c3c4603008 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 14 Aug 2025 13:34:48 +0100 Subject: [PATCH 12/64] Add final step 7. --- .../MigrationActivityNavigationTest.kt | 8 +- app/src/main/AndroidManifest.xml | 4 + .../migration/step6/Step6MigrationActivity.kt | 2 +- .../nav3recipes/migration/step7/Navigator.kt | 145 ++++++++++++ .../migration/step7/Step7MigrationActivity.kt | 212 ++++++++++++++++++ 5 files changed, 367 insertions(+), 4 deletions(-) create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt create mode 100644 app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt diff --git a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt index d42c04a..aeac9cc 100644 --- a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +++ b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt @@ -15,6 +15,7 @@ import com.example.nav3recipes.migration.step3.Step3MigrationActivity import com.example.nav3recipes.migration.step4.Step4MigrationActivity import com.example.nav3recipes.migration.step5.Step5MigrationActivity import com.example.nav3recipes.migration.step6.Step6MigrationActivity +import com.example.nav3recipes.migration.step7.Step7MigrationActivity import org.junit.Rule import org.junit.Test import org.junit.runner.RunWith @@ -35,12 +36,13 @@ class MigrationActivityNavigationTest(activityClass: Class> { return listOf( - /*arrayOf(StartMigrationActivity::class.java), + arrayOf(StartMigrationActivity::class.java), arrayOf(Step2MigrationActivity::class.java), arrayOf(Step3MigrationActivity::class.java), - arrayOf(Step4MigrationActivity::class.java),*/ + arrayOf(Step4MigrationActivity::class.java), arrayOf(Step5MigrationActivity::class.java), - /*arrayOf(Step6MigrationActivity::class.java)*/ + arrayOf(Step6MigrationActivity::class.java), + arrayOf(Step7MigrationActivity::class.java) ) } } diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index a56103a..252cf1c 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -119,6 +119,10 @@ android:name=".migration.step6.Step6MigrationActivity" android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> + diff --git a/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt index 92dc989..d792894 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt @@ -118,7 +118,7 @@ class Step6MigrationActivity : ComponentActivity() { NavigationBarItem( selected = isSelected, onClick = { - navigator.navigate(key, navOptions { + navController.navigate(key, navOptions { popUpTo(route = RouteA) }) }, diff --git a/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt new file mode 100644 index 0000000..ad41123 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt @@ -0,0 +1,145 @@ +package com.example.nav3recipes.migration.step7 + +import android.annotation.SuppressLint +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.navigation.NavBackStackEntry +import androidx.navigation.NavOptions + +/** + * Navigator that mirrors `NavController`'s back stack + */ +@SuppressLint("RestrictedApi") +internal class Navigator( + private val startRoute: Any = Unit, + private val canTopLevelRoutesExistTogether: Boolean = false, + private val shouldPrintDebugInfo: Boolean = false +) { + + val backStack = mutableStateListOf(startRoute) + var topLevelRoute by mutableStateOf(startRoute) + private set + + // Maintain a stack for each top level route + private val topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) + + // Maintain a map of shared routes to their parent stacks + private var sharedRoutes: MutableMap = mutableMapOf() + + private fun updateBackStack() { + backStack.apply { + clear() + val entries = topLevelStacks.flatMap { it.value } + addAll(entries) + } + printBackStack() + } + + fun navlog(message: String){ + if (shouldPrintDebugInfo){ + println(message) + } + } + + private fun printBackStack() { + navlog("Back stack: ${backStack.getDebugString()}") + } + + private fun printTopLevelStacks() { + + navlog("Top level stacks: ") + topLevelStacks.forEach { topLevelStack -> + navlog(" ${topLevelStack.key} => ${topLevelStack.value.getDebugString()}") + } + } + + private fun List.getDebugString() : String { + val message = StringBuilder("[") + forEach { entry -> + if (entry is NavBackStackEntry){ + message.append("Unmigrated route: ${entry.destination.route}, ") + } else { + message.append("Migrated route: $entry, ") + } + } + message.append("]\n") + return message.toString() + } + + private fun addTopLevel(route: Any) { + if (route == startRoute) { + clearAllExceptStartStack() + } else { + + // Get the existing stack or create a new one. + val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) + + if (!canTopLevelRoutesExistTogether) { + clearAllExceptStartStack() + } + + topLevelStacks.put(route, topLevelStack) + navlog("Added top level route $route") + } + topLevelRoute = route + } + + private fun clearAllExceptStartStack() { + // Remove all other top level stacks, except the start stack + val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) + topLevelStacks.clear() + topLevelStacks.put(startRoute, startStack) + } + + private fun add(route: Any) { + navlog("Attempting to add $route") + if (route is Route.TopLevel) { + navlog("$route is a top level route") + addTopLevel(route) + } else { + if (route is Route.Shared) { + navlog("$route is a shared route") + // If the key is already in a stack, remove it + val oldParent = sharedRoutes[route] + if (oldParent != null) { + topLevelStacks[oldParent]?.remove(route) + } + sharedRoutes[route] = topLevelRoute + } else { + navlog("$route is a normal route") + } + val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false + navlog("Added $route to $topLevelRoute stack: $hasBeenAdded") + } + } + + /** + * Navigate to the given route. + */ + fun navigate(route: Any, navOptions: NavOptions? = null) { + add(route) + updateBackStack() + } + + /** + * Go back to the previous route. + */ + fun goBack() { + if (backStack.size <= 1) { + return + } + val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() + // If the removed key was a top level key, remove the associated top level stack + topLevelStacks.remove(removedKey) + topLevelRoute = topLevelStacks.keys.last() + updateBackStack() + } + +} + +sealed interface Route { + interface TopLevel : Route + interface Shared : Route +} diff --git a/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt new file mode 100644 index 0000000..438ce3b --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt @@ -0,0 +1,212 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.migration.step7 + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Column +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.filled.Camera +import androidx.compose.material.icons.filled.Face +import androidx.compose.material.icons.filled.Home +import androidx.compose.material3.Button +import androidx.compose.material3.Icon +import androidx.compose.material3.NavigationBar +import androidx.compose.material3.NavigationBarItem +import androidx.compose.material3.Scaffold +import androidx.compose.material3.Text +import androidx.compose.runtime.remember +import androidx.compose.ui.Alignment +import androidx.compose.ui.Modifier +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.graphics.vector.ImageVector +import androidx.navigation.navOptions +import androidx.navigation3.runtime.EntryProviderBuilder +import androidx.navigation3.runtime.entry +import androidx.navigation3.runtime.entryProvider +import androidx.navigation3.ui.DialogSceneStrategy +import androidx.navigation3.ui.NavDisplay +import com.example.nav3recipes.content.ContentBlue +import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.content.ContentMauve +import com.example.nav3recipes.content.ContentPink +import com.example.nav3recipes.content.ContentPurple +import com.example.nav3recipes.content.ContentRed +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable + +@Serializable +data object RouteA : Route.TopLevel +@Serializable +data object RouteA1 + +@Serializable +data object RouteB : Route.TopLevel +@Serializable +data class RouteB1(val id: String) + +@Serializable +data object RouteC : Route.TopLevel +@Serializable +data object RouteD +@Serializable +data object RouteE : Route.Shared + +private val TOP_LEVEL_ROUTES = mapOf( + RouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), + RouteB to NavBarItem(icon = Icons.Default.Face, description = "Route B"), + RouteC to NavBarItem(icon = Icons.Default.Camera, description = "Route C"), +) + +data class NavBarItem( + val icon: ImageVector, + val description: String +) + + +class Step7MigrationActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val navigator = remember { Navigator(startRoute = RouteA, shouldPrintDebugInfo = true) } + + Scaffold(bottomBar = { + NavigationBar { + TOP_LEVEL_ROUTES.forEach { (key, value) -> + val isSelected = key == navigator.topLevelRoute + NavigationBarItem( + selected = isSelected, + onClick = { + navigator.navigate(key, navOptions { + popUpTo(route = RouteA) + }) + }, + icon = { + Icon( + imageVector = value.icon, + contentDescription = value.description + ) + }, + label = { Text(value.description) } + ) + } + } + }) + + { paddingValues -> + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + sceneStrategy = remember { DialogSceneStrategy() }, + entryProvider = entryProvider { + featureASection( + onSubRouteClick = { navigator.navigate(RouteA1) }, + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + featureBSection( + onDetailClick = { id -> navigator.navigate(RouteB1(id)) }, + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + featureCSection( + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + entry(metadata = DialogSceneStrategy.dialog()) { + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } + } + ) + } + } + } +} + +private fun EntryProviderBuilder.featureASection( + onSubRouteClick: () -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + entry { + ContentRed("Route A title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onSubRouteClick) { + Text("Go to A1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + entry { ContentPink("Route A1 title") } + entry { ContentBlue("Route E title") } +} + +private fun EntryProviderBuilder.featureBSection( + onDetailClick: (id: String) -> Unit, + onDialogClick: () -> Unit, + onOtherClick: () -> Unit +) { + entry { + ContentGreen("Route B title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { onDetailClick("ABC") }) { + Text("Go to B1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } + entry { key -> + ContentPurple("Route B1 title. ID: ${key.id}") + } +} + +private fun EntryProviderBuilder.featureCSection( + onDialogClick: () -> Unit, + onOtherClick: () -> Unit, +) { + entry { + ContentMauve("Route C title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") + } + } + } + } +} From 3e9bc6325a65dd37a75e7358d8b7b69aa159b601 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 15 Aug 2025 11:19:48 +0100 Subject: [PATCH 13/64] Tidy up imports --- .../migration/NavigatorWithDebug.kt | 191 ------------------ .../nav3recipes/migration/step2/Navigator.kt | 11 +- .../nav3recipes/migration/step6/Navigator.kt | 7 +- 3 files changed, 7 insertions(+), 202 deletions(-) delete mode 100644 app/src/main/java/com/example/nav3recipes/migration/NavigatorWithDebug.kt diff --git a/app/src/main/java/com/example/nav3recipes/migration/NavigatorWithDebug.kt b/app/src/main/java/com/example/nav3recipes/migration/NavigatorWithDebug.kt deleted file mode 100644 index 3ef99a6..0000000 --- a/app/src/main/java/com/example/nav3recipes/migration/NavigatorWithDebug.kt +++ /dev/null @@ -1,191 +0,0 @@ -package com.example.nav3recipes.migration - -import android.annotation.SuppressLint -import androidx.compose.runtime.getValue -import androidx.compose.runtime.mutableStateListOf -import androidx.compose.runtime.mutableStateOf -import androidx.compose.runtime.setValue -import androidx.navigation.NavBackStackEntry -import androidx.navigation.NavDestination.Companion.hasRoute -import androidx.navigation.NavHostController -import androidx.navigation.toRoute -import com.example.nav3recipes.migration.step4.RouteB -import com.example.nav3recipes.migration.step4.RouteB1 -import com.example.nav3recipes.migration.step4.RouteD -import com.example.nav3recipes.migration.step4.RouteE -import kotlinx.coroutines.CoroutineScope -import kotlinx.coroutines.Job -import kotlinx.coroutines.launch - -/** - * Navigator that mirrors `NavController`'s back stack - */ -@SuppressLint("RestrictedApi") -class Navigator( - private val navController: NavHostController, - private val startRoute: Any = Unit, - private val canTopLevelRoutesExistTogether: Boolean = false -) { - - val backStack = mutableStateListOf(startRoute) - var topLevelRoute by mutableStateOf(startRoute) - private set - - // Maintain a stack for each top level route - private lateinit var topLevelStacks : MutableMap> - - // Maintain a map of shared routes to their parent stacks - private var sharedRoutes: MutableMap = mutableMapOf() - - val coroutineScope = CoroutineScope(Job()) - - init { - inititalizeTopLevelStacks() - coroutineScope.launch { - navController.currentBackStack.collect { nav2BackStack -> - inititalizeTopLevelStacks() - println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") - printTopLevelStacks() - - nav2BackStack.forEach { entry -> - val destination = entry.destination - - if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ - val route = - if (destination.hasRoute()) { - entry.toRoute() - } else if (destination.hasRoute()) { - entry.toRoute() - } else if (destination.hasRoute()) { - entry.toRoute() - } else { - // Non migrated top level route - entry - } - add(route) - } else { - println("Ignoring $entry") - } - } - printTopLevelStacks() - updateBackStack() - } - } - } - - private fun updateBackStack() { - backStack.apply { - clear() - val entries = topLevelStacks.flatMap { it.value } - addAll(entries) - } - printBackStack() - } - - private fun printBackStack() { - println("Back stack: ") - backStack.print() - println("---") - } - - private fun printTopLevelStacks() { - - println("Top level stacks: ") - topLevelStacks.forEach { topLevelStack -> - print("${topLevelStack.key} => ") - topLevelStack.value.print() - } - println("---") - } - - private fun List.print() { - print("[") - forEach { entry -> - if (entry is NavBackStackEntry){ - print("Unmigrated route: ${entry.destination.route}, ") - } else { - print("Migrated route: $entry, ") - } - } - print("]\n") - } - - private fun addTopLevel(route: Any) { - if (route == startRoute) { - clearAllExceptStartStack() - } else { - - // Get the existing stack or create a new one. - val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) - - if (!canTopLevelRoutesExistTogether) { - clearAllExceptStartStack() - } - - topLevelStacks.put(route, topLevelStack) - println("Added top level route $route") - } - topLevelRoute = route - } - - private fun clearAllExceptStartStack() { - // Remove all other top level stacks, except the start stack - val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) - topLevelStacks.clear() - topLevelStacks.put(startRoute, startStack) - } - - private fun inititalizeTopLevelStacks() { - topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) - topLevelRoute = startRoute - } - - private fun add(route: Any) { - println("Attempting to add $route") - if (route is Route.TopLevel) { - println("$route is a top level route") - addTopLevel(route) - } else { - if (route is Route.Shared) { - println("$route is a shared route") - // If the key is already in a stack, remove it - val oldParent = sharedRoutes[route] - if (oldParent != null) { - topLevelStacks[oldParent]?.remove(route) - } - sharedRoutes[route] = topLevelRoute - } else { - println("$route is a normal route") - } - val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false - println("Added $route to $topLevelRoute stack: $hasBeenAdded") - } - } - - /** - * Navigate to the given route. - */ - fun navigate(route: Any) { - add(route) - updateBackStack() - } - - /** - * Go back to the previous route. - */ - fun goBack() { - if (backStack.size <= 1) { - return - } - val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() - // If the removed key was a top level key, remove the associated top level stack - topLevelStacks.remove(removedKey) - topLevelRoute = topLevelStacks.keys.last() - updateBackStack() - } -} - -sealed interface Route { - interface TopLevel : Route - interface Shared : Route -} diff --git a/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt index 124e452..d6133c6 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt @@ -4,15 +4,14 @@ import android.annotation.SuppressLint import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateListOf import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.saveable.Saver import androidx.compose.runtime.setValue import androidx.navigation.NavBackStackEntry +import androidx.navigation.NavController import androidx.navigation.NavDestination.Companion.hasRoute import androidx.navigation.NavHostController import androidx.navigation.NavOptions import androidx.navigation.toRoute -import com.example.nav3recipes.migration.step4.RouteB -import com.example.nav3recipes.migration.step4.RouteB1 -import com.example.nav3recipes.migration.step4.RouteE import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Job import kotlinx.coroutines.launch @@ -21,7 +20,7 @@ import kotlinx.coroutines.launch * Navigator that mirrors `NavController`'s back stack */ @SuppressLint("RestrictedApi") -internal class Navigator( +class Navigator( private val navController: NavHostController, private val startRoute: Any = Unit, private val canTopLevelRoutesExistTogether: Boolean = false, @@ -168,7 +167,7 @@ internal class Navigator( fun navigate(route: Any, navOptions: NavOptions? = null) { navController.navigate(route, navOptions) - // TODO: add instruction on when to uncomment this and remove the line above + // Uncomment the code below and delete the line as per migration guide /* add(route) updateBackStack() @@ -181,7 +180,7 @@ internal class Navigator( fun goBack() { navController.popBackStack() - // TODO: add instruction on when to uncomment this and remove the line above + // Uncomment the code below and delete the line as per migration guide /* if (backStack.size <= 1) { return diff --git a/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt index 6b3cd1d..90c5db7 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt @@ -10,9 +10,6 @@ import androidx.navigation.NavDestination.Companion.hasRoute import androidx.navigation.NavHostController import androidx.navigation.NavOptions import androidx.navigation.toRoute -import com.example.nav3recipes.migration.step4.RouteB -import com.example.nav3recipes.migration.step4.RouteB1 -import com.example.nav3recipes.migration.step4.RouteE import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Job import kotlinx.coroutines.launch @@ -180,7 +177,7 @@ internal class Navigator( fun navigate(route: Any, navOptions: NavOptions? = null) { navController.navigate(route, navOptions) - // TODO: add instruction on when to uncomment this and remove the line above + // Uncomment the code below and delete the line as per migration guide /* add(route) updateBackStack() @@ -193,7 +190,7 @@ internal class Navigator( fun goBack() { navController.popBackStack() - // TODO: add instruction on when to uncomment this and remove the line above + // Uncomment the code below and delete the line as per migration guide /* if (backStack.size <= 1) { return From 17b4015606a0a3f54d6f1905987cb1801bb4d4b4 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Mon, 18 Aug 2025 16:43:38 +0100 Subject: [PATCH 14/64] Navigator uses SavedState APIs and KotlinX Serialization to persist state through config changes --- .../migration/start/StartMigrationActivity.kt | 8 ++ .../nav3recipes/migration/step7/Navigator.kt | 119 +++++++++++++++--- .../migration/step7/Step7MigrationActivity.kt | 40 +++--- 3 files changed, 137 insertions(+), 30 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt index f5bd47c..7043ae5 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/start/StartMigrationActivity.kt @@ -80,16 +80,21 @@ import kotlin.reflect.KClass * @see `MigrationActivityNavigationTest` for instrumented tests that verify this behavior. */ +// Feature module A @Serializable private data object BaseRouteA @Serializable private data object RouteA @Serializable private data object RouteA1 +// Feature module B @Serializable private data object BaseRouteB @Serializable private data object RouteB @Serializable private data class RouteB1(val id: String) +// Feature module C @Serializable private data object BaseRouteC @Serializable private data object RouteC + +// Common UI modules @Serializable private data object RouteD @Serializable private data object RouteE @@ -165,6 +170,7 @@ class StartMigrationActivity : ComponentActivity() { } } +// Feature module A private fun NavGraphBuilder.featureASection( onSubRouteClick: () -> Unit, onDialogClick: () -> Unit, @@ -191,6 +197,7 @@ private fun NavGraphBuilder.featureASection( } } +// Feature module B private fun NavGraphBuilder.featureBSection( onDetailClick: (id: String) -> Unit, onDialogClick: () -> Unit, @@ -219,6 +226,7 @@ private fun NavGraphBuilder.featureBSection( } } +// Feature module C private fun NavGraphBuilder.featureCSection( onDialogClick: () -> Unit, onOtherClick: () -> Unit, diff --git a/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt index ad41123..0d35b6c 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt @@ -1,22 +1,33 @@ package com.example.nav3recipes.migration.step7 import android.annotation.SuppressLint +import androidx.collection.mutableIntListOf import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateListOf import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.saveable.Saver import androidx.compose.runtime.setValue import androidx.navigation.NavBackStackEntry import androidx.navigation.NavOptions +import androidx.navigation3.runtime.NavKey +import androidx.savedstate.SavedState +import androidx.savedstate.SavedStateRegistry +import androidx.savedstate.read +import androidx.savedstate.serialization.decodeFromSavedState +import androidx.savedstate.serialization.encodeToSavedState +import androidx.savedstate.write +import kotlinx.serialization.Serializable +import kotlin.collections.MutableMap +import kotlin.collections.component1 +import kotlin.collections.component2 +import kotlin.collections.iterator -/** - * Navigator that mirrors `NavController`'s back stack - */ @SuppressLint("RestrictedApi") -internal class Navigator( - private val startRoute: Any = Unit, - private val canTopLevelRoutesExistTogether: Boolean = false, - private val shouldPrintDebugInfo: Boolean = false -) { +internal class Navigator ( + private var startRoute: Route, + private var canTopLevelRoutesExistTogether: Boolean = false, + private var shouldPrintDebugInfo: Boolean = false, +) : SavedStateRegistry.SavedStateProvider { val backStack = mutableStateListOf(startRoute) var topLevelRoute by mutableStateOf(startRoute) @@ -26,7 +37,7 @@ internal class Navigator( private val topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) // Maintain a map of shared routes to their parent stacks - private var sharedRoutes: MutableMap = mutableMapOf() + private var sharedRoutes : MutableMap = mutableMapOf() private fun updateBackStack() { backStack.apply { @@ -36,7 +47,7 @@ internal class Navigator( } printBackStack() } - + fun navlog(message: String){ if (shouldPrintDebugInfo){ println(message) @@ -68,7 +79,7 @@ internal class Navigator( return message.toString() } - private fun addTopLevel(route: Any) { + private fun addTopLevel(route: Route) { if (route == startRoute) { clearAllExceptStartStack() } else { @@ -93,7 +104,7 @@ internal class Navigator( topLevelStacks.put(startRoute, startStack) } - private fun add(route: Any) { + private fun add(route: Route) { navlog("Attempting to add $route") if (route is Route.TopLevel) { navlog("$route is a top level route") @@ -118,7 +129,7 @@ internal class Navigator( /** * Navigate to the given route. */ - fun navigate(route: Any, navOptions: NavOptions? = null) { + fun navigate(route: Route, navOptions: NavOptions? = null) { add(route) updateBackStack() } @@ -137,9 +148,85 @@ internal class Navigator( updateBackStack() } + override fun saveState() : SavedState { + val savedState = SavedState() + savedState.write { + + putSavedState(KEY_START_ROUTE, encodeToSavedState(startRoute)) + putBoolean(KEY_CAN_TOP_LEVEL_ROUTES_EXIST_TOGETHER, canTopLevelRoutesExistTogether) + putBoolean(KEY_SHOULD_PRINT_DEBUG_INFO, shouldPrintDebugInfo) + putSavedState(KEY_TOP_LEVEL_ROUTE, encodeToSavedState(topLevelRoute)) + + // Create lists for each top level stack. Example: + // top_level_stack_ids = [1, 2, 3] + // top_level_stack_key_1 = [encodedStateA] + // top_level_stack_values_1 = [encodedStateA, encodedStateA1] + // top_level_stack_key_2 = ... + + var id = 0 + val ids = mutableListOf() + + for ((key, stackValues) in topLevelStacks){ + putSavedState("$KEY_TOP_LEVEL_STACK_KEY_PREFIX$id", encodeToSavedState(key)) + putSavedStateList("$KEY_TOP_LEVEL_STACK_VALUES_PREFIX$id", stackValues.map { encodeToSavedState(it) }) + ids.add(id) + id++ + } + + putIntList(KEY_TOP_LEVEL_STACK_IDS, ids) + + // TODO + // putSavedStateList(KEY_SHARED_ROUTES, sharedRoutes.map { encodeToSavedState(it) }) + } + return savedState + } + + fun restore(savedState: SavedState) { + + savedState.read { + startRoute = decodeFromSavedState(getSavedState(KEY_START_ROUTE)) + canTopLevelRoutesExistTogether = getBoolean(KEY_CAN_TOP_LEVEL_ROUTES_EXIST_TOGETHER) + topLevelRoute = decodeFromSavedState(getSavedState(KEY_TOP_LEVEL_ROUTE)) + + val ids = getIntList(KEY_TOP_LEVEL_STACK_IDS) + for (id in ids){ + // get the key and the value list + val key : Route = decodeFromSavedState(getSavedState("$KEY_TOP_LEVEL_STACK_KEY_PREFIX$id")) + val stackValues = getSavedStateList("$KEY_TOP_LEVEL_STACK_VALUES_PREFIX$id") + .map { decodeFromSavedState(it)} + topLevelStacks[key] = stackValues.toMutableList() + + } + + // TODO implement saving and restoring of shared routes (job for AI surely) + //sharedRoutes = getSavedStateList(KEY_SHARED_ROUTES).map { decodeFromSavedState(it) } + + updateBackStack() + } + } + + + companion object { + + const val KEY_PROVIDER = "navigator_saved_state_provider" + private const val KEY_START_ROUTE = "start_route" + private const val KEY_CAN_TOP_LEVEL_ROUTES_EXIST_TOGETHER = "can_top_level_routes_exist_together" + private const val KEY_SHOULD_PRINT_DEBUG_INFO = "should_print_debug_info" + private const val KEY_TOP_LEVEL_ROUTE = "top_level_route" + private const val KEY_TOP_LEVEL_STACK_IDS = "top_level_stack_ids" + private const val KEY_TOP_LEVEL_STACK_KEY_PREFIX = "top_level_stack_key_" + private const val KEY_TOP_LEVEL_STACK_VALUES_PREFIX = "top_level_stack_values_" + private const val KEY_SHARED_ROUTES = "shared_routes" + + } + } -sealed interface Route { - interface TopLevel : Route - interface Shared : Route +@Serializable +sealed class Route { + sealed class TopLevel : Route() + sealed class Shared : Route() } + + + diff --git a/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt index 438ce3b..b535595 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt @@ -21,6 +21,7 @@ import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.background import androidx.compose.foundation.layout.Column +import androidx.compose.foundation.layout.padding import androidx.compose.material.icons.Icons import androidx.compose.material.icons.filled.Camera import androidx.compose.material.icons.filled.Face @@ -32,12 +33,14 @@ import androidx.compose.material3.NavigationBarItem import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.runtime.remember +import androidx.compose.runtime.saveable.rememberSaveable import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color import androidx.compose.ui.graphics.vector.ImageVector import androidx.navigation.navOptions import androidx.navigation3.runtime.EntryProviderBuilder +import androidx.navigation3.runtime.NavKey import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.ui.DialogSceneStrategy @@ -51,24 +54,25 @@ import com.example.nav3recipes.content.ContentRed import com.example.nav3recipes.ui.setEdgeToEdgeConfig import kotlinx.serialization.Serializable + @Serializable -data object RouteA : Route.TopLevel +data object RouteA : Route.TopLevel() @Serializable -data object RouteA1 +data object RouteA1 : Route() @Serializable -data object RouteB : Route.TopLevel +data object RouteB : Route.TopLevel() @Serializable -data class RouteB1(val id: String) +data class RouteB1(val id: String) : Route() @Serializable -data object RouteC : Route.TopLevel +data object RouteC : Route.TopLevel() @Serializable -data object RouteD +data object RouteD : Route() @Serializable -data object RouteE : Route.Shared +data object RouteE : Route.Shared() -private val TOP_LEVEL_ROUTES = mapOf( +private val TOP_LEVEL_ROUTES = mapOf( RouteA to NavBarItem(icon = Icons.Default.Home, description = "Route A"), RouteB to NavBarItem(icon = Icons.Default.Face, description = "Route B"), RouteC to NavBarItem(icon = Icons.Default.Camera, description = "Route C"), @@ -82,12 +86,19 @@ data class NavBarItem( class Step7MigrationActivity : ComponentActivity() { + private val navigator = Navigator(startRoute = RouteA, shouldPrintDebugInfo = true) + override fun onCreate(savedInstanceState: Bundle?) { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) - setContent { - val navigator = remember { Navigator(startRoute = RouteA, shouldPrintDebugInfo = true) } + savedStateRegistry.registerSavedStateProvider(Navigator.KEY_PROVIDER, navigator) + val restoredState = savedStateRegistry.consumeRestoredStateForKey(Navigator.KEY_PROVIDER) + if (restoredState != null) { + navigator.restore(restoredState) + } + + setContent { Scaffold(bottomBar = { NavigationBar { TOP_LEVEL_ROUTES.forEach { (key, value) -> @@ -137,14 +148,15 @@ class Step7MigrationActivity : ComponentActivity() { text = "Route D title (dialog)" ) } - } + }, + modifier = Modifier.padding(paddingValues) ) } } } } -private fun EntryProviderBuilder.featureASection( +private fun EntryProviderBuilder.featureASection( onSubRouteClick: () -> Unit, onDialogClick: () -> Unit, onOtherClick: () -> Unit, @@ -168,7 +180,7 @@ private fun EntryProviderBuilder.featureASection( entry { ContentBlue("Route E title") } } -private fun EntryProviderBuilder.featureBSection( +private fun EntryProviderBuilder.featureBSection( onDetailClick: (id: String) -> Unit, onDialogClick: () -> Unit, onOtherClick: () -> Unit @@ -193,7 +205,7 @@ private fun EntryProviderBuilder.featureBSection( } } -private fun EntryProviderBuilder.featureCSection( +private fun EntryProviderBuilder.featureCSection( onDialogClick: () -> Unit, onOtherClick: () -> Unit, ) { From de6bdf4ef65526c040747877dd39e0e1f07fb0bc Mon Sep 17 00:00:00 2001 From: Don Turner Date: Mon, 18 Aug 2025 17:11:58 +0100 Subject: [PATCH 15/64] Remove remaining Nav2 references from step 7 --- .../nav3recipes/migration/step7/Navigator.kt | 19 +++---------------- .../migration/step7/Step7MigrationActivity.kt | 4 +--- 2 files changed, 4 insertions(+), 19 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt index 0d35b6c..671bc53 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt @@ -1,15 +1,10 @@ package com.example.nav3recipes.migration.step7 import android.annotation.SuppressLint -import androidx.collection.mutableIntListOf import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateListOf import androidx.compose.runtime.mutableStateOf -import androidx.compose.runtime.saveable.Saver import androidx.compose.runtime.setValue -import androidx.navigation.NavBackStackEntry -import androidx.navigation.NavOptions -import androidx.navigation3.runtime.NavKey import androidx.savedstate.SavedState import androidx.savedstate.SavedStateRegistry import androidx.savedstate.read @@ -17,10 +12,6 @@ import androidx.savedstate.serialization.decodeFromSavedState import androidx.savedstate.serialization.encodeToSavedState import androidx.savedstate.write import kotlinx.serialization.Serializable -import kotlin.collections.MutableMap -import kotlin.collections.component1 -import kotlin.collections.component2 -import kotlin.collections.iterator @SuppressLint("RestrictedApi") internal class Navigator ( @@ -66,14 +57,10 @@ internal class Navigator ( } } - private fun List.getDebugString() : String { + private fun List.getDebugString() : String { val message = StringBuilder("[") forEach { entry -> - if (entry is NavBackStackEntry){ - message.append("Unmigrated route: ${entry.destination.route}, ") - } else { - message.append("Migrated route: $entry, ") - } + message.append("Route: $entry, ") } message.append("]\n") return message.toString() @@ -129,7 +116,7 @@ internal class Navigator ( /** * Navigate to the given route. */ - fun navigate(route: Route, navOptions: NavOptions? = null) { + fun navigate(route: Route) { add(route) updateBackStack() } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt index b535595..eed572d 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt @@ -106,9 +106,7 @@ class Step7MigrationActivity : ComponentActivity() { NavigationBarItem( selected = isSelected, onClick = { - navigator.navigate(key, navOptions { - popUpTo(route = RouteA) - }) + navigator.navigate(key) }, icon = { Icon( From 466b3a124360c3bc78b1386bc5d2bd44bbeb1f5f Mon Sep 17 00:00:00 2001 From: Don Turner Date: Mon, 18 Aug 2025 17:17:54 +0100 Subject: [PATCH 16/64] Handle shared routes --- .../nav3recipes/migration/step7/Navigator.kt | 30 +++++++++++++------ 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt index 671bc53..9108935 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt @@ -62,7 +62,7 @@ internal class Navigator ( forEach { entry -> message.append("Route: $entry, ") } - message.append("]\n") + message.append("]") return message.toString() } @@ -162,8 +162,10 @@ internal class Navigator ( putIntList(KEY_TOP_LEVEL_STACK_IDS, ids) - // TODO - // putSavedStateList(KEY_SHARED_ROUTES, sharedRoutes.map { encodeToSavedState(it) }) + val sharedRouteKeys = sharedRoutes.keys.toList() + val sharedRouteValues = sharedRoutes.values.toList() + putSavedStateList(KEY_SHARED_ROUTES_KEYS, sharedRouteKeys.map { encodeToSavedState(it) }) + putSavedStateList(KEY_SHARED_ROUTES_VALUES, sharedRouteValues.map { encodeToSavedState(it) }) } return savedState } @@ -185,8 +187,19 @@ internal class Navigator ( } - // TODO implement saving and restoring of shared routes (job for AI surely) - //sharedRoutes = getSavedStateList(KEY_SHARED_ROUTES).map { decodeFromSavedState(it) } + val encodedSharedRouteKeys = getSavedStateListOrNull(KEY_SHARED_ROUTES_KEYS) + val encodedSharedRouteValues = getSavedStateListOrNull(KEY_SHARED_ROUTES_VALUES) + + if (encodedSharedRouteKeys != null && + encodedSharedRouteValues != null && + encodedSharedRouteKeys.size == encodedSharedRouteValues.size) { + val restoredKeys = encodedSharedRouteKeys.map { decodeFromSavedState(it) } + val restoredValues = encodedSharedRouteValues.map { decodeFromSavedState(it) } + sharedRoutes.clear() + for (i in restoredKeys.indices) { + sharedRoutes[restoredKeys[i]] = restoredValues[i] + } + } updateBackStack() } @@ -203,7 +216,9 @@ internal class Navigator ( private const val KEY_TOP_LEVEL_STACK_IDS = "top_level_stack_ids" private const val KEY_TOP_LEVEL_STACK_KEY_PREFIX = "top_level_stack_key_" private const val KEY_TOP_LEVEL_STACK_VALUES_PREFIX = "top_level_stack_values_" - private const val KEY_SHARED_ROUTES = "shared_routes" + private const val KEY_SHARED_ROUTES = "shared_routes" // This was the old, unused key + private const val KEY_SHARED_ROUTES_KEYS = "shared_routes_keys" + private const val KEY_SHARED_ROUTES_VALUES = "shared_routes_values" } @@ -214,6 +229,3 @@ sealed class Route { sealed class TopLevel : Route() sealed class Shared : Route() } - - - From 201f488d3cc482df911715427eebedc490be96e9 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Mon, 18 Aug 2025 21:51:26 +0100 Subject: [PATCH 17/64] Switch to using Saver --- .../MigrationActivityNavigationTest.kt | 9 +- .../nav3recipes/migration/step7/Navigator.kt | 173 ++++++++++-------- .../migration/step7/Step7MigrationActivity.kt | 14 +- 3 files changed, 102 insertions(+), 94 deletions(-) diff --git a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt index aeac9cc..ce57b61 100644 --- a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +++ b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt @@ -1,6 +1,5 @@ package com.example.nav3recipes -import android.app.Activity import androidx.activity.ComponentActivity import androidx.compose.ui.test.assertIsSelected import androidx.compose.ui.test.hasText @@ -135,6 +134,9 @@ class MigrationActivityNavigationTest(activityClass: Class() - - for ((key, stackValues) in topLevelStacks){ - putSavedState("$KEY_TOP_LEVEL_STACK_KEY_PREFIX$id", encodeToSavedState(key)) - putSavedStateList("$KEY_TOP_LEVEL_STACK_VALUES_PREFIX$id", stackValues.map { encodeToSavedState(it) }) - ids.add(id) - id++ - } - - putIntList(KEY_TOP_LEVEL_STACK_IDS, ids) - - val sharedRouteKeys = sharedRoutes.keys.toList() - val sharedRouteValues = sharedRoutes.values.toList() - putSavedStateList(KEY_SHARED_ROUTES_KEYS, sharedRouteKeys.map { encodeToSavedState(it) }) - putSavedStateList(KEY_SHARED_ROUTES_VALUES, sharedRouteValues.map { encodeToSavedState(it) }) - } - return savedState - } - - fun restore(savedState: SavedState) { - - savedState.read { - startRoute = decodeFromSavedState(getSavedState(KEY_START_ROUTE)) - canTopLevelRoutesExistTogether = getBoolean(KEY_CAN_TOP_LEVEL_ROUTES_EXIST_TOGETHER) - topLevelRoute = decodeFromSavedState(getSavedState(KEY_TOP_LEVEL_ROUTE)) - - val ids = getIntList(KEY_TOP_LEVEL_STACK_IDS) - for (id in ids){ - // get the key and the value list - val key : Route = decodeFromSavedState(getSavedState("$KEY_TOP_LEVEL_STACK_KEY_PREFIX$id")) - val stackValues = getSavedStateList("$KEY_TOP_LEVEL_STACK_VALUES_PREFIX$id") - .map { decodeFromSavedState(it)} - topLevelStacks[key] = stackValues.toMutableList() - - } - - val encodedSharedRouteKeys = getSavedStateListOrNull(KEY_SHARED_ROUTES_KEYS) - val encodedSharedRouteValues = getSavedStateListOrNull(KEY_SHARED_ROUTES_VALUES) - - if (encodedSharedRouteKeys != null && - encodedSharedRouteValues != null && - encodedSharedRouteKeys.size == encodedSharedRouteValues.size) { - val restoredKeys = encodedSharedRouteKeys.map { decodeFromSavedState(it) } - val restoredValues = encodedSharedRouteValues.map { decodeFromSavedState(it) } - sharedRoutes.clear() - for (i in restoredKeys.indices) { - sharedRoutes[restoredKeys[i]] = restoredValues[i] - } - } - - updateBackStack() - } - } - - companion object { - - const val KEY_PROVIDER = "navigator_saved_state_provider" private const val KEY_START_ROUTE = "start_route" private const val KEY_CAN_TOP_LEVEL_ROUTES_EXIST_TOGETHER = "can_top_level_routes_exist_together" private const val KEY_SHOULD_PRINT_DEBUG_INFO = "should_print_debug_info" @@ -216,12 +148,99 @@ internal class Navigator ( private const val KEY_TOP_LEVEL_STACK_IDS = "top_level_stack_ids" private const val KEY_TOP_LEVEL_STACK_KEY_PREFIX = "top_level_stack_key_" private const val KEY_TOP_LEVEL_STACK_VALUES_PREFIX = "top_level_stack_values_" - private const val KEY_SHARED_ROUTES = "shared_routes" // This was the old, unused key private const val KEY_SHARED_ROUTES_KEYS = "shared_routes_keys" private const val KEY_SHARED_ROUTES_VALUES = "shared_routes_values" + val Saver = Saver( + save = { navigator -> + val savedState = SavedState() + savedState.write { + + putSavedState(KEY_START_ROUTE, encodeToSavedState(navigator.startRoute)) + putBoolean(KEY_CAN_TOP_LEVEL_ROUTES_EXIST_TOGETHER, navigator.canTopLevelRoutesExistTogether) + putBoolean(KEY_SHOULD_PRINT_DEBUG_INFO, navigator.shouldPrintDebugInfo) + putSavedState(KEY_TOP_LEVEL_ROUTE, encodeToSavedState(navigator.topLevelRoute)) + + // Create lists for each top level stack. Example: + // top_level_stack_ids = [1, 2, 3] + // top_level_stack_key_1 = [encodedStateA] + // top_level_stack_values_1 = [encodedStateA, encodedStateA1] + // top_level_stack_key_2 = ... + + var id = 0 + val ids = mutableListOf() + + for ((key, stackValues) in navigator.topLevelStacks){ + putSavedState("$KEY_TOP_LEVEL_STACK_KEY_PREFIX$id", encodeToSavedState(key)) + putSavedStateList("$KEY_TOP_LEVEL_STACK_VALUES_PREFIX$id", stackValues.map { encodeToSavedState(it) }) + ids.add(id) + id++ + } + + putIntList(KEY_TOP_LEVEL_STACK_IDS, ids) + + val sharedRouteKeys = navigator.sharedRoutes.keys.toList() + val sharedRouteValues = navigator.sharedRoutes.values.toList() + putSavedStateList(KEY_SHARED_ROUTES_KEYS, sharedRouteKeys.map { encodeToSavedState(it) }) + putSavedStateList(KEY_SHARED_ROUTES_VALUES, sharedRouteValues.map { encodeToSavedState(it) }) + } + savedState + }, + restore = { savedState -> + savedState.read { + val restoredStartRoute = decodeFromSavedState(getSavedState(KEY_START_ROUTE)) + val restoredCanTopLevelRoutesExistTogether = getBoolean(KEY_CAN_TOP_LEVEL_ROUTES_EXIST_TOGETHER) + val restoredShouldPrintDebugInfo = getBoolean(KEY_SHOULD_PRINT_DEBUG_INFO) + + val navigator = Navigator( + startRoute = restoredStartRoute, + canTopLevelRoutesExistTogether = restoredCanTopLevelRoutesExistTogether, + shouldPrintDebugInfo = restoredShouldPrintDebugInfo + ) + + navigator.topLevelRoute = decodeFromSavedState(getSavedState(KEY_TOP_LEVEL_ROUTE)) + + val ids = getIntList(KEY_TOP_LEVEL_STACK_IDS) + for (id in ids){ + // get the key and the value list + val key : Route = decodeFromSavedState(getSavedState("$KEY_TOP_LEVEL_STACK_KEY_PREFIX$id")) + val stackValues = getSavedStateList("$KEY_TOP_LEVEL_STACK_VALUES_PREFIX$id") + .map { decodeFromSavedState(it)} + navigator.topLevelStacks[key] = stackValues.toMutableList() + } + + val encodedSharedRouteKeys = getSavedStateListOrNull(KEY_SHARED_ROUTES_KEYS) + val encodedSharedRouteValues = getSavedStateListOrNull(KEY_SHARED_ROUTES_VALUES) + + if (encodedSharedRouteKeys != null && + encodedSharedRouteValues != null && + encodedSharedRouteKeys.size == encodedSharedRouteValues.size) { + val restoredKeys = encodedSharedRouteKeys.map { decodeFromSavedState(it) } + val restoredValues = encodedSharedRouteValues.map { decodeFromSavedState(it) } + navigator.sharedRoutes.clear() + for (i in restoredKeys.indices) { + navigator.sharedRoutes[restoredKeys[i]] = restoredValues[i] + } + } + navigator.updateBackStack() + navigator + } + } + ) } +} +@Composable +fun rememberNavigator( + startRoute: Route, + canTopLevelRoutesExistTogether: Boolean = false, + shouldPrintDebugInfo: Boolean = false +) = rememberSaveable(saver = Navigator.Saver){ + Navigator( + startRoute = startRoute, + canTopLevelRoutesExistTogether = canTopLevelRoutesExistTogether, + shouldPrintDebugInfo = shouldPrintDebugInfo + ) } @Serializable diff --git a/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt index eed572d..e1ee813 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt @@ -33,14 +33,11 @@ import androidx.compose.material3.NavigationBarItem import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.runtime.remember -import androidx.compose.runtime.saveable.rememberSaveable import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color import androidx.compose.ui.graphics.vector.ImageVector -import androidx.navigation.navOptions import androidx.navigation3.runtime.EntryProviderBuilder -import androidx.navigation3.runtime.NavKey import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.ui.DialogSceneStrategy @@ -86,19 +83,14 @@ data class NavBarItem( class Step7MigrationActivity : ComponentActivity() { - private val navigator = Navigator(startRoute = RouteA, shouldPrintDebugInfo = true) - override fun onCreate(savedInstanceState: Bundle?) { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) - savedStateRegistry.registerSavedStateProvider(Navigator.KEY_PROVIDER, navigator) - val restoredState = savedStateRegistry.consumeRestoredStateForKey(Navigator.KEY_PROVIDER) - if (restoredState != null) { - navigator.restore(restoredState) - } - setContent { + + val navigator = rememberNavigator(startRoute = RouteA, shouldPrintDebugInfo = true) + Scaffold(bottomBar = { NavigationBar { TOP_LEVEL_ROUTES.forEach { (key, value) -> From 9caf04f97c43aedf88d1cf2e94253bd5160519a7 Mon Sep 17 00:00:00 2001 From: jbw0033 Date: Tue, 19 Aug 2025 03:32:11 +0000 Subject: [PATCH 18/64] Add bottom sheet recipe This commit adds a recipe that demonstrates how to display a navigation destination within a Material `ModalBottomSheet`. It introduces `BottomSheetSceneStrategy`, a `SceneStrategy` that can be added to a `NavDisplay`. This strategy checks for specific metadata on a `NavEntry` to determine if it should be rendered as a bottom sheet. A new `BottomSheetActivity` is added to showcase how to use this strategy. --- app/src/main/AndroidManifest.xml | 4 + .../bottomsheet/BottomSheetActivity.kt | 94 +++++++++++++++++++ .../bottomsheet/BottomSheetSceneStrategy.kt | 79 ++++++++++++++++ 3 files changed, 177 insertions(+) create mode 100644 app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt create mode 100644 app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 4040165..d6afe26 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -65,6 +65,10 @@ android:name=".dialog.DialogActivity" android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> + () } + + NavDisplay( + backStack = backStack, + onBack = { backStack.removeLastOrNull() }, + sceneStrategy = bottomSheetStrategy, + entryProvider = entryProvider { + entry { + ContentGreen("Welcome to Nav3") { + Button(onClick = { + backStack.add(RouteB("123")) + }) { + Text("Click to open bottom sheet") + } + } + } + entry( + metadata = BottomSheetSceneStrategy.bottomSheet() + ) { key -> + ContentBlue( + title = "Route id: ${key.id}", + modifier = Modifier.clip( + shape = RoundedCornerShape(16.dp) + ) + ) + } + } + ) + } + } +} diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt new file mode 100644 index 0000000..0939ddb --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt @@ -0,0 +1,79 @@ +package com.example.nav3recipes.bottomsheet + +import androidx.compose.material3.ExperimentalMaterial3Api +import androidx.compose.material3.ModalBottomSheet +import androidx.compose.material3.ModalBottomSheetProperties +import androidx.compose.runtime.Composable +import androidx.navigation3.runtime.NavEntry +import androidx.navigation3.ui.OverlayScene +import androidx.navigation3.ui.Scene +import androidx.navigation3.ui.SceneStrategy + +/** An [OverlayScene] that renders an [entry] within a [ModalBottomSheet]. */ +@OptIn(ExperimentalMaterial3Api::class) +internal class BottomSheetScene( + override val key: T, + override val previousEntries: List>, + override val overlaidEntries: List>, + private val entry: NavEntry, + private val modalBottomSheetProperties: ModalBottomSheetProperties, + private val onBack: (count: Int) -> Unit, +) : OverlayScene { + + override val entries: List> = listOf(entry) + + override val content: @Composable (() -> Unit) = { + ModalBottomSheet( + onDismissRequest = { onBack(1) }, + properties = modalBottomSheetProperties, + ) { + entry.Content() + } + } +} + +/** + * A [SceneStrategy] that displays entries that have added [bottomSheet] to their [NavEntry.metadata] + * within a [ModalBottomSheet] instance. + * + * This strategy should always be added before any non-overlay scene strategies. + */ +@OptIn(ExperimentalMaterial3Api::class) +class BottomSheetSceneStrategy() : SceneStrategy { + + @Composable + override fun calculateScene( + entries: List>, + onBack: (Int) -> Unit + ): Scene? { + val lastEntry = entries.lastOrNull() + val bottomSheetProperties = lastEntry?.metadata?.get(BOTTOM_SHEET_KEY) as? ModalBottomSheetProperties + return bottomSheetProperties?.let { properties -> + @Suppress("UNCHECKED_CAST") + BottomSheetScene( + key = lastEntry.contentKey as T, + previousEntries = entries.dropLast(1), + overlaidEntries = entries.dropLast(1), + entry = lastEntry, + modalBottomSheetProperties = properties, + onBack = onBack + ) + } + } + + companion object { + /** + * Function to be called on the [NavEntry.metadata] to mark this entry as something that + * should be displayed within a [ModalBottomSheet]. + * + * @param modalBottomSheetProperties properties that should be passed to the containing + * [ModalBottomSheet]. + */ + @OptIn(ExperimentalMaterial3Api::class) + fun bottomSheet( + modalBottomSheetProperties: ModalBottomSheetProperties = ModalBottomSheetProperties() + ): Map = mapOf(BOTTOM_SHEET_KEY to modalBottomSheetProperties) + + internal const val BOTTOM_SHEET_KEY = "bottomsheet" + } +} \ No newline at end of file From bd08782d608b784c5f7b499da0f30b3af968bb72 Mon Sep 17 00:00:00 2001 From: jbw0033 Date: Tue, 19 Aug 2025 18:07:39 +0000 Subject: [PATCH 19/64] Remove parenthesis from BottomSheetSceneStrategy Doing this for Kotlin code syntax --- .../example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt index 0939ddb..1a79615 100644 --- a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt @@ -39,7 +39,7 @@ internal class BottomSheetScene( * This strategy should always be added before any non-overlay scene strategies. */ @OptIn(ExperimentalMaterial3Api::class) -class BottomSheetSceneStrategy() : SceneStrategy { +class BottomSheetSceneStrategy : SceneStrategy { @Composable override fun calculateScene( From bde7f7476ccfce67c9d52c7a03cd52bae5958a37 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 21 Aug 2025 17:26:34 +0100 Subject: [PATCH 20/64] Minor edits --- .../main/java/com/example/nav3recipes/RecipePickerActivity.kt | 4 +++- .../example/nav3recipes/bottomsheet/BottomSheetActivity.kt | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt b/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt index 127ad53..6437799 100644 --- a/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt @@ -29,6 +29,7 @@ import com.example.nav3recipes.animations.AnimatedActivity import com.example.nav3recipes.basic.BasicActivity import com.example.nav3recipes.basicdsl.BasicDslActivity import com.example.nav3recipes.basicsaveable.BasicSaveableActivity +import com.example.nav3recipes.bottomsheet.BottomSheetActivity import com.example.nav3recipes.commonui.CommonUiActivity import com.example.nav3recipes.conditional.ConditionalActivity import com.example.nav3recipes.dialog.DialogActivity @@ -56,8 +57,9 @@ private val recipes = listOf( Recipe("Basic Saveable", BasicSaveableActivity::class.java), Heading("Layouts and animations"), - Recipe("Material list-detail layout", MaterialListDetailActivity::class.java), + Recipe("Bottom Sheet", BottomSheetActivity::class.java), Recipe("Dialog", DialogActivity::class.java), + Recipe("Material list-detail layout", MaterialListDetailActivity::class.java), Recipe("Two pane layout (custom scene)", TwoPaneActivity::class.java), Recipe("Animations", AnimatedActivity::class.java), diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt index 29b3935..57b43b7 100644 --- a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt @@ -41,7 +41,7 @@ import kotlinx.serialization.Serializable * This recipe demonstrates how to create a bottom sheet. It does this by: * * - Adding the `BottomSheetSceneStrategy` to the list of strategies used by `NavDisplay`. - * - Adding `BottomSheetSceneStrategy.bottomsheet` to a `NavEntry`'s metadata to indicate that it + * - Adding `BottomSheetSceneStrategy.bottomSheet()` to a `NavEntry`'s metadata to indicate that it * is a bottom sheet. In this case it is applied to the `NavEntry` for `RouteB`. * * See also https://developer.android.com/guide/navigation/navigation-3/custom-layouts From 6bb1fe40e539386ad67dff5d730f2061f3ea6c08 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Tue, 2 Sep 2025 15:44:29 +0100 Subject: [PATCH 21/64] Update headings in README for better structure --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 71222c2..c65b9f0 100644 --- a/README.md +++ b/README.md @@ -5,29 +5,29 @@ use its APIs to implement common navigation use cases. ## Recipes These are the recipes and what they demonstrate. -**Basic API examples** +### Basic API examples - **[Basic](app/src/main/java/com/example/nav3recipes/basic)**: Shows most basic API usage. - **[Saveable back stack](app/src/main/java/com/example/nav3recipes/basicsaveable)**: As above, with a persistent back stack. - **[Entry provider DSL](app/src/main/java/com/example/nav3recipes/basicdsl)**: As above, using the entryProvider DSL. -**Layouts and animations** +### Layouts and animations - **[Material adaptive](app/src/main/java/com/example/nav3recipes/scenes/materiallistdetail)**: Shows how to use a Material list-detail layout. - **[Dialog](app/src/main/java/com/example/nav3recipes/dialog)**: Shows how to create a Dialog destination. - **[Custom Scene](app/src/main/java/com/example/nav3recipes/scenes/twopane)**: Shows how to create a custom layout using a `Scene` and `SceneStrategy` (see video of UI behavior below). - **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Override the default animations for all destinations and a single destination. -**Common use cases** +### Common use cases - **[Common navigation UI](app/src/main/java/com/example/nav3recipes/commonui)**: A common navigation toolbar where each item in the toolbar navigates to a top level destination. - **[Conditional navigation](app/src/main/java/com/example/nav3recipes/conditional)**: Switch to a different navigation flow when a condition is met. For example, for authentication or first-time user onboarding. -**Architecture** +### Architecture - **[Modularized navigation code](app/src/main/java/com/example/nav3recipes/modular/hilt)**: Demonstrates how to decouple navigation code into separate modules (uses Dagger/Hilt for DI). -**Passing navigation arguments to ViewModels** +### Passing navigation arguments to ViewModels - **[Basic ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/basicviewmodels)**: Navigation arguments are passed to a ViewModel constructed using `viewModel()` - **[Hilt injected ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/injectedviewmodels)**: Navigation arguments are passed to a ViewModel constructed using `hiltViewModel()` -**Planned** +### Planned - **Deeplinks**: Create and handle deeplinks to specific destinations - **Android XR**: Custom navigation and layout behavior for Android XR - **Returning a result from a destination**: Return a result to a previous destination From ba8221f3867f552ce9a9303d8c02c311f002ddc9 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 11 Sep 2025 10:10:37 +0100 Subject: [PATCH 22/64] Update to latest library versions and disable snapshot artifact repo --- gradle/libs.versions.toml | 20 ++++++++++---------- settings.gradle.kts | 12 ++++++++---- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 8e4edca..462be0f 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -16,21 +16,21 @@ agp = "8.10.1" kotlin = "2.2.0" kotlinSerialization = "2.2.0" -coreKtx = "1.16.0" +coreKtx = "1.17.0" junit = "4.13.2" junitVersion = "1.3.0" espressoCore = "3.7.0" kotlinxSerializationCore = "1.9.0" -lifecycleRuntimeKtx = "2.9.2" -lifecycleViewmodel = "1.0.0-SNAPSHOT" -activityCompose = "1.12.0-alpha05" -composeBom = "2025.07.01" -navigation3 = "1.0.0-alpha07" -material3 = "1.4.0-beta01" -nav3Material = "1.0.0-SNAPSHOT" +lifecycleRuntimeKtx = "2.9.3" +lifecycleViewmodel = "1.0.0-alpha04" +activityCompose = "1.12.0-alpha08" +composeBom = "2025.08.01" +navigation3 = "1.0.0-alpha09" +material3 = "1.4.0-beta03" +nav3Material = "1.0.0-alpha02" ksp = "2.2.0-2.0.2" -hilt = "2.57" -hiltNavigationCompose = "1.2.0" +hilt = "2.57.1" +hiltNavigationCompose = "1.3.0" [libraries] androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" } diff --git a/settings.gradle.kts b/settings.gradle.kts index 4eaed7d..223971d 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -25,9 +25,11 @@ pluginManagement { } mavenCentral() gradlePluginPortal() - maven { + // Uncomment and change the build ID if you need to use snapshot artifacts. + // See androidx.dev for full instructions. + /*maven { url = uri("https://androidx.dev/snapshots/builds/13617490/artifacts/repository") - } + }*/ } } dependencyResolutionManagement { @@ -35,9 +37,11 @@ dependencyResolutionManagement { repositories { google() mavenCentral() - maven { + // Uncomment and change the build ID if you need to use snapshot artifacts. + // See androidx.dev for full instructions. + /*maven { url = uri("https://androidx.dev/snapshots/builds/13617490/artifacts/repository") - } + }*/ } } From 4141b464973999113efa763c8978724c8da3baf3 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 11 Sep 2025 10:15:12 +0100 Subject: [PATCH 23/64] Replace SnapshotStateList with NavBackStack --- .../com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt b/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt index c29ae00..6273c89 100644 --- a/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt @@ -31,9 +31,9 @@ import androidx.compose.runtime.CompositionLocalProvider import androidx.compose.runtime.ProvidableCompositionLocal import androidx.compose.runtime.compositionLocalOf import androidx.compose.runtime.remember -import androidx.compose.runtime.snapshots.SnapshotStateList import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier +import androidx.navigation3.runtime.NavBackStack import androidx.navigation3.runtime.NavKey import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider @@ -159,7 +159,7 @@ class TwoPaneActivity : ComponentActivity() { } } - private fun SnapshotStateList.addProductRoute(productId: Int) { + private fun NavBackStack.addProductRoute(productId: Int) { val productRoute = Product(productId) // Avoid adding the same product route to the back stack twice. From fd7be631b1060b536a8f01898ddbcf729a82b5e9 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 11 Sep 2025 10:17:41 +0100 Subject: [PATCH 24/64] Address Gemini feedback --- settings.gradle.kts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/settings.gradle.kts b/settings.gradle.kts index 223971d..9adc0a3 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -28,7 +28,7 @@ pluginManagement { // Uncomment and change the build ID if you need to use snapshot artifacts. // See androidx.dev for full instructions. /*maven { - url = uri("https://androidx.dev/snapshots/builds/13617490/artifacts/repository") + url = uri("https://androidx.dev/snapshots/builds//artifacts/repository") }*/ } } @@ -40,7 +40,7 @@ dependencyResolutionManagement { // Uncomment and change the build ID if you need to use snapshot artifacts. // See androidx.dev for full instructions. /*maven { - url = uri("https://androidx.dev/snapshots/builds/13617490/artifacts/repository") + url = uri("https://androidx.dev/snapshots/builds//artifacts/repository") }*/ } } From d23149d3ec43d59c16f2787278b72de579395a97 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 11 Sep 2025 10:58:14 +0100 Subject: [PATCH 25/64] Add link to bug --- .../scenes/materiallistdetail/MaterialListDetailActivity.kt | 1 + 1 file changed, 1 insertion(+) diff --git a/app/src/main/java/com/example/nav3recipes/scenes/materiallistdetail/MaterialListDetailActivity.kt b/app/src/main/java/com/example/nav3recipes/scenes/materiallistdetail/MaterialListDetailActivity.kt index 7b6e2ff..762caf7 100644 --- a/app/src/main/java/com/example/nav3recipes/scenes/materiallistdetail/MaterialListDetailActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/scenes/materiallistdetail/MaterialListDetailActivity.kt @@ -68,6 +68,7 @@ class MaterialListDetailActivity : ComponentActivity() { val backStack = rememberNavBackStack(ConversationList) // Override the defaults so that there isn't a horizontal space between the panes. + // See b/418201867 val windowAdaptiveInfo = currentWindowAdaptiveInfo() val directive = remember(windowAdaptiveInfo) { calculatePaneScaffoldDirective(windowAdaptiveInfo) From 93f97300381e60480444a5346a80c61d1460aa1c Mon Sep 17 00:00:00 2001 From: Rob Orgiu Date: Thu, 11 Sep 2025 17:56:36 +0200 Subject: [PATCH 26/64] Create Supporting Pane Recipe --- app/src/main/AndroidManifest.xml | 4 + .../nav3recipes/RecipePickerActivity.kt | 2 + .../MaterialSupportingPaneActivity.kt | 121 ++++++++++++++++++ .../scenes/twopane/TwoPaneActivity.kt | 4 +- gradle/libs.versions.toml | 20 +-- 5 files changed, 139 insertions(+), 12 deletions(-) create mode 100644 app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 4040165..e9fd064 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -69,6 +69,10 @@ android:name=".scenes.materiallistdetail.MaterialListDetailActivity" android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> + ( + backNavigationBehavior = BackNavigationBehavior.PopUntilCurrentDestinationChange, + directive = directive + ) + + NavDisplay( + backStack = backStack, + onBack = { keysToRemove -> repeat(keysToRemove) { backStack.removeLastOrNull() } }, + sceneStrategy = supportingPaneStrategy, + entryProvider = entryProvider { + entry( + metadata = SupportingPaneSceneStrategy.mainPane() + ) { + ContentRed("Welcome to Nav3") { + Button(onClick = { + backStack.add(SupportingPane) + }) { + Text("View Supporting Pane") + } + } + } + entry( + metadata = SupportingPaneSceneStrategy.supportingPane() + ) { + ContentBlue("Supporting Pane") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { + backStack.add(Profile) + }) { + Text("View profile") + } + } + } + } + entry( + metadata = SupportingPaneSceneStrategy.extraPane() + ) { + ContentGreen("Profile") + } + } + ) + } + } +} diff --git a/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt b/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt index c29ae00..6273c89 100644 --- a/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt @@ -31,9 +31,9 @@ import androidx.compose.runtime.CompositionLocalProvider import androidx.compose.runtime.ProvidableCompositionLocal import androidx.compose.runtime.compositionLocalOf import androidx.compose.runtime.remember -import androidx.compose.runtime.snapshots.SnapshotStateList import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier +import androidx.navigation3.runtime.NavBackStack import androidx.navigation3.runtime.NavKey import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider @@ -159,7 +159,7 @@ class TwoPaneActivity : ComponentActivity() { } } - private fun SnapshotStateList.addProductRoute(productId: Int) { + private fun NavBackStack.addProductRoute(productId: Int) { val productRoute = Product(productId) // Avoid adding the same product route to the back stack twice. diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 8e4edca..5b2f3bf 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -13,24 +13,24 @@ # limitations under the License. [versions] -agp = "8.10.1" +agp = "8.11.2" kotlin = "2.2.0" kotlinSerialization = "2.2.0" -coreKtx = "1.16.0" +coreKtx = "1.17.0" junit = "4.13.2" junitVersion = "1.3.0" espressoCore = "3.7.0" kotlinxSerializationCore = "1.9.0" -lifecycleRuntimeKtx = "2.9.2" +lifecycleRuntimeKtx = "2.9.3" lifecycleViewmodel = "1.0.0-SNAPSHOT" -activityCompose = "1.12.0-alpha05" -composeBom = "2025.07.01" -navigation3 = "1.0.0-alpha07" -material3 = "1.4.0-beta01" -nav3Material = "1.0.0-SNAPSHOT" +activityCompose = "1.12.0-alpha08" +composeBom = "2025.09.00" +navigation3 = "1.0.0-alpha09" +material3 = "1.4.0-rc01" +nav3Material = "1.0.0-alpha02" ksp = "2.2.0-2.0.2" -hilt = "2.57" -hiltNavigationCompose = "1.2.0" +hilt = "2.57.1" +hiltNavigationCompose = "1.3.0" [libraries] androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" } From efee1c1d4dc7d5ac399b47df22be7b97f4ab993e Mon Sep 17 00:00:00 2001 From: Rob Orgiu Date: Thu, 11 Sep 2025 18:02:55 +0200 Subject: [PATCH 27/64] Create Supporting Pane Recipe --- gradle/libs.versions.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 5b2f3bf..bac2126 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -14,8 +14,8 @@ [versions] agp = "8.11.2" -kotlin = "2.2.0" -kotlinSerialization = "2.2.0" +kotlin = "2.2.10" +kotlinSerialization = "2.2.10" coreKtx = "1.17.0" junit = "4.13.2" junitVersion = "1.3.0" From 17a045db935d48cf0ec9477c710348ee85f3cebf Mon Sep 17 00:00:00 2001 From: Rob Orgiu Date: Fri, 12 Sep 2025 15:54:52 +0200 Subject: [PATCH 28/64] Update dependencies to sync with Supporting Pane PR --- gradle/libs.versions.toml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 462be0f..086bb37 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -13,9 +13,9 @@ # limitations under the License. [versions] -agp = "8.10.1" -kotlin = "2.2.0" -kotlinSerialization = "2.2.0" +agp = "8.11.2" +kotlin = "2.2.20" +kotlinSerialization = "2.2.20" coreKtx = "1.17.0" junit = "4.13.2" junitVersion = "1.3.0" @@ -24,9 +24,9 @@ kotlinxSerializationCore = "1.9.0" lifecycleRuntimeKtx = "2.9.3" lifecycleViewmodel = "1.0.0-alpha04" activityCompose = "1.12.0-alpha08" -composeBom = "2025.08.01" +composeBom = "2025.09.00" navigation3 = "1.0.0-alpha09" -material3 = "1.4.0-beta03" +material3 = "1.4.0-rc01" nav3Material = "1.0.0-alpha02" ksp = "2.2.0-2.0.2" hilt = "2.57.1" From c324bab526b244b55f58f317b144ace7c04bdd99 Mon Sep 17 00:00:00 2001 From: Rob Orgiu Date: Thu, 18 Sep 2025 09:05:50 +0200 Subject: [PATCH 29/64] Fix comments --- .../MaterialSupportingPaneActivity.kt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt b/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt index f850a5d..59531e2 100644 --- a/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt @@ -43,8 +43,8 @@ import com.example.nav3recipes.ui.setEdgeToEdgeConfig import kotlinx.serialization.Serializable /** - * This example uses the Material ListDetailSceneStrategy to create an adaptive scene. It has three - * destinations: ConversationList, ConversationDetail and Profile. When the window width allows it, + * This example uses the Material SupportingPaneSceneStrategy to create an adaptive scene. It has three + * destinations: MainPane, SupportingPane and Profile. When the window width allows it, * the content for these destinations will be shown in a two pane layout. */ @Serializable @@ -75,6 +75,8 @@ class MaterialSupportingPaneActivity : ComponentActivity() { .copy(horizontalPartitionSpacerSize = 0.dp, verticalPartitionSpacerSize = 0.dp) } + // Override the defaults so that the supporting pane can be dismissed by pressing back. + // See b/445826749 val supportingPaneStrategy = rememberSupportingPaneSceneStrategy( backNavigationBehavior = BackNavigationBehavior.PopUntilCurrentDestinationChange, directive = directive @@ -82,7 +84,7 @@ class MaterialSupportingPaneActivity : ComponentActivity() { NavDisplay( backStack = backStack, - onBack = { keysToRemove -> repeat(keysToRemove) { backStack.removeLastOrNull() } }, + onBack = { numKeysToRemove -> repeat(numKeysToRemove) { backStack.removeLastOrNull() } }, sceneStrategy = supportingPaneStrategy, entryProvider = entryProvider { entry( From 2f164b9eeeee7c07b624afa216bb3b2eeab3db45 Mon Sep 17 00:00:00 2001 From: Rob Orgiu Date: Thu, 18 Sep 2025 11:46:54 +0200 Subject: [PATCH 30/64] Fix comments --- .../MaterialSupportingPaneActivity.kt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt b/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt index 59531e2..8edc79f 100644 --- a/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt @@ -44,14 +44,14 @@ import kotlinx.serialization.Serializable /** * This example uses the Material SupportingPaneSceneStrategy to create an adaptive scene. It has three - * destinations: MainPane, SupportingPane and Profile. When the window width allows it, + * destinations: Content, RelatedContent and Profile. When the window width allows it, * the content for these destinations will be shown in a two pane layout. */ @Serializable -private object MainPane : NavKey +private object Content : NavKey @Serializable -private data object SupportingPane : NavKey +private data object RelatedContent : NavKey @Serializable private data object Profile : NavKey @@ -65,7 +65,7 @@ class MaterialSupportingPaneActivity : ComponentActivity() { setContent { - val backStack = rememberNavBackStack(MainPane) + val backStack = rememberNavBackStack(Content) // Override the defaults so that there isn't a horizontal or vertical space between the panes. // See b/444438086 @@ -87,21 +87,21 @@ class MaterialSupportingPaneActivity : ComponentActivity() { onBack = { numKeysToRemove -> repeat(numKeysToRemove) { backStack.removeLastOrNull() } }, sceneStrategy = supportingPaneStrategy, entryProvider = entryProvider { - entry( + entry( metadata = SupportingPaneSceneStrategy.mainPane() ) { ContentRed("Welcome to Nav3") { Button(onClick = { - backStack.add(SupportingPane) + backStack.add(RelatedContent) }) { - Text("View Supporting Pane") + Text("View related content") } } } - entry( + entry( metadata = SupportingPaneSceneStrategy.supportingPane() ) { - ContentBlue("Supporting Pane") { + ContentBlue("Related content") { Column(horizontalAlignment = Alignment.CenterHorizontally) { Button(onClick = { backStack.add(Profile) From f496dbc6d4b95e3dc11487a5a91f44fa74c7e8a1 Mon Sep 17 00:00:00 2001 From: Rob Orgiu Date: Thu, 18 Sep 2025 12:06:05 +0200 Subject: [PATCH 31/64] Update README file --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c65b9f0..9a8234f 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,8 @@ These are the recipes and what they demonstrate. - **[Entry provider DSL](app/src/main/java/com/example/nav3recipes/basicdsl)**: As above, using the entryProvider DSL. ### Layouts and animations -- **[Material adaptive](app/src/main/java/com/example/nav3recipes/scenes/materiallistdetail)**: Shows how to use a Material list-detail layout. +- **[Material adaptive List-Detail](app/src/main/java/com/example/nav3recipes/scenes/materiallistdetail)**: Shows how to use a Material list-detail layout. +- **[Material adaptive Supporting Pane](app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane)**: Shows how to use a Material supporting pane layout. - **[Dialog](app/src/main/java/com/example/nav3recipes/dialog)**: Shows how to create a Dialog destination. - **[Custom Scene](app/src/main/java/com/example/nav3recipes/scenes/twopane)**: Shows how to create a custom layout using a `Scene` and `SceneStrategy` (see video of UI behavior below). - **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Override the default animations for all destinations and a single destination. From d4db6e1ab6993147b6839de201797b0772697daa Mon Sep 17 00:00:00 2001 From: Rob Orgiu Date: Thu, 18 Sep 2025 18:06:46 +0200 Subject: [PATCH 32/64] Fix naming --- .../MaterialSupportingPaneActivity.kt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt b/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt index 8edc79f..ccae974 100644 --- a/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane/MaterialSupportingPaneActivity.kt @@ -48,10 +48,10 @@ import kotlinx.serialization.Serializable * the content for these destinations will be shown in a two pane layout. */ @Serializable -private object Content : NavKey +private object MainVideo : NavKey @Serializable -private data object RelatedContent : NavKey +private data object RelatedVideos : NavKey @Serializable private data object Profile : NavKey @@ -65,7 +65,7 @@ class MaterialSupportingPaneActivity : ComponentActivity() { setContent { - val backStack = rememberNavBackStack(Content) + val backStack = rememberNavBackStack(MainVideo) // Override the defaults so that there isn't a horizontal or vertical space between the panes. // See b/444438086 @@ -87,21 +87,21 @@ class MaterialSupportingPaneActivity : ComponentActivity() { onBack = { numKeysToRemove -> repeat(numKeysToRemove) { backStack.removeLastOrNull() } }, sceneStrategy = supportingPaneStrategy, entryProvider = entryProvider { - entry( + entry( metadata = SupportingPaneSceneStrategy.mainPane() ) { - ContentRed("Welcome to Nav3") { + ContentRed("Video content") { Button(onClick = { - backStack.add(RelatedContent) + backStack.add(RelatedVideos) }) { - Text("View related content") + Text("View related videos") } } } - entry( + entry( metadata = SupportingPaneSceneStrategy.supportingPane() ) { - ContentBlue("Related content") { + ContentBlue("Related videos") { Column(horizontalAlignment = Alignment.CenterHorizontally) { Button(onClick = { backStack.add(Profile) From c054009afe7a39a4c0c3268ca5946526764dc4e9 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 25 Sep 2025 17:11:46 +0200 Subject: [PATCH 33/64] Add koin injected ViewModel recipe --- README.md | 1 + app/build.gradle.kts | 2 + app/src/main/AndroidManifest.xml | 9 +- .../nav3recipes/RecipePickerActivity.kt | 12 ++- .../basic}/BasicViewModelsActivity.kt | 2 +- .../hilt/HiltViewModelsActivity.kt} | 6 +- .../viewmodels/koin/KoinViewModelsActivity.kt | 102 ++++++++++++++++++ gradle/libs.versions.toml | 2 + 8 files changed, 125 insertions(+), 11 deletions(-) rename app/src/main/java/com/example/nav3recipes/passingarguments/{basicviewmodels => viewmodels/basic}/BasicViewModelsActivity.kt (98%) rename app/src/main/java/com/example/nav3recipes/passingarguments/{injectedviewmodels/InjectedViewModelsActivity.kt => viewmodels/hilt/HiltViewModelsActivity.kt} (96%) create mode 100644 app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt diff --git a/README.md b/README.md index 9a8234f..25333a3 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ These are the recipes and what they demonstrate. ### Passing navigation arguments to ViewModels - **[Basic ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/basicviewmodels)**: Navigation arguments are passed to a ViewModel constructed using `viewModel()` - **[Hilt injected ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/injectedviewmodels)**: Navigation arguments are passed to a ViewModel constructed using `hiltViewModel()` +- **[Koin injected ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/injectedviewmodels)**: Navigation arguments are passed to a ViewModel constructed using `koinViewModel()` ### Planned - **Deeplinks**: Create and handle deeplinks to specific destinations diff --git a/app/build.gradle.kts b/app/build.gradle.kts index f1b2051..f76c34b 100644 --- a/app/build.gradle.kts +++ b/app/build.gradle.kts @@ -84,6 +84,8 @@ dependencies { implementation(libs.hilt.android) ksp(libs.hilt.compiler) + + implementation(libs.koin.compose.viewmodel) testImplementation(libs.junit) androidTestImplementation(libs.androidx.junit) androidTestImplementation(libs.androidx.espresso.core) diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index e9fd064..3097691 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -86,11 +86,11 @@ android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> + diff --git a/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt b/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt index 838467c..14cee74 100644 --- a/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt @@ -33,8 +33,9 @@ import com.example.nav3recipes.commonui.CommonUiActivity import com.example.nav3recipes.conditional.ConditionalActivity import com.example.nav3recipes.dialog.DialogActivity import com.example.nav3recipes.modular.hilt.ModularActivity -import com.example.nav3recipes.passingarguments.basicviewmodels.BasicViewModelsActivity -import com.example.nav3recipes.passingarguments.injectedviewmodels.InjectedViewModelsActivity +import com.example.nav3recipes.passingarguments.viewmodels.basic.BasicViewModelsActivity +import com.example.nav3recipes.passingarguments.viewmodels.hilt.HiltViewModelsActivity +import com.example.nav3recipes.passingarguments.viewmodels.koin.KoinViewModelsActivity import com.example.nav3recipes.scenes.materiallistdetail.MaterialListDetailActivity import com.example.nav3recipes.scenes.materialsupportingpane.MaterialSupportingPaneActivity import com.example.nav3recipes.scenes.twopane.TwoPaneActivity @@ -70,9 +71,10 @@ private val recipes = listOf( Heading("Architecture"), Recipe("Modular Navigation", ModularActivity::class.java), - Heading("Passing navigation arguments"), - Recipe("Argument passing to basic ViewModel", BasicViewModelsActivity::class.java), - Recipe("Argument passing to injected ViewModel", InjectedViewModelsActivity::class.java), + Heading("Passing navigation arguments using ViewModels"), + Recipe("Basic", BasicViewModelsActivity::class.java), + Recipe("Using Hilt", HiltViewModelsActivity::class.java), + Recipe("Using Koin", KoinViewModelsActivity::class.java), ) class RecipePickerActivity : ComponentActivity() { diff --git a/app/src/main/java/com/example/nav3recipes/passingarguments/basicviewmodels/BasicViewModelsActivity.kt b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/basic/BasicViewModelsActivity.kt similarity index 98% rename from app/src/main/java/com/example/nav3recipes/passingarguments/basicviewmodels/BasicViewModelsActivity.kt rename to app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/basic/BasicViewModelsActivity.kt index adf29bb..9017a39 100644 --- a/app/src/main/java/com/example/nav3recipes/passingarguments/basicviewmodels/BasicViewModelsActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/basic/BasicViewModelsActivity.kt @@ -14,7 +14,7 @@ * limitations under the License. */ -package com.example.nav3recipes.passingarguments.basicviewmodels +package com.example.nav3recipes.passingarguments.viewmodels.basic import android.os.Bundle import androidx.activity.ComponentActivity diff --git a/app/src/main/java/com/example/nav3recipes/passingarguments/injectedviewmodels/InjectedViewModelsActivity.kt b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/hilt/HiltViewModelsActivity.kt similarity index 96% rename from app/src/main/java/com/example/nav3recipes/passingarguments/injectedviewmodels/InjectedViewModelsActivity.kt rename to app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/hilt/HiltViewModelsActivity.kt index a3f959d..e812755 100644 --- a/app/src/main/java/com/example/nav3recipes/passingarguments/injectedviewmodels/InjectedViewModelsActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/hilt/HiltViewModelsActivity.kt @@ -14,7 +14,7 @@ * limitations under the License. */ -package com.example.nav3recipes.passingarguments.injectedviewmodels +package com.example.nav3recipes.passingarguments.viewmodels.hilt import android.os.Bundle import androidx.activity.ComponentActivity @@ -35,7 +35,7 @@ import androidx.navigation3.ui.NavDisplay import androidx.navigation3.ui.rememberSceneSetupNavEntryDecorator import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen -import com.example.nav3recipes.passingarguments.basicviewmodels.RouteB +import com.example.nav3recipes.passingarguments.viewmodels.basic.RouteB import com.example.nav3recipes.ui.setEdgeToEdgeConfig import dagger.assisted.Assisted import dagger.assisted.AssistedFactory @@ -54,7 +54,7 @@ data object RouteA data class RouteB(val id: String) @AndroidEntryPoint -class InjectedViewModelsActivity : ComponentActivity() { +class HiltViewModelsActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { setEdgeToEdgeConfig() diff --git a/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt new file mode 100644 index 0000000..8602043 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt @@ -0,0 +1,102 @@ +package com.example.nav3recipes.passingarguments.viewmodels.koin + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.lazy.LazyColumn +import androidx.compose.material3.Button +import androidx.compose.material3.Text +import androidx.compose.runtime.Composable +import androidx.compose.runtime.mutableStateListOf +import androidx.compose.runtime.remember +import androidx.lifecycle.ViewModel +import androidx.lifecycle.viewmodel.navigation3.rememberViewModelStoreNavEntryDecorator +import androidx.navigation3.runtime.entry +import androidx.navigation3.runtime.entryProvider +import androidx.navigation3.runtime.rememberSavedStateNavEntryDecorator +import androidx.navigation3.ui.NavDisplay +import androidx.navigation3.ui.rememberSceneSetupNavEntryDecorator +import com.example.nav3recipes.content.ContentBlue +import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.passingarguments.viewmodels.basic.RouteB +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import org.koin.android.ext.koin.androidContext +import org.koin.compose.viewmodel.koinViewModel +import org.koin.core.context.GlobalContext +import org.koin.core.module.dsl.viewModelOf +import org.koin.core.parameter.parametersOf +import org.koin.dsl.module + +/** + * Passing navigation arguments to a Koin injected ViewModel + * + * - ViewModelStoreNavEntryDecorator ensures that ViewModels are scoped to the NavEntry + */ + +data object RouteA +data class RouteB(val id: String) + +class KoinViewModelsActivity : ComponentActivity() { + + override fun onCreate(savedInstanceState: Bundle?) { + + // The startKoin block should be placed in Application.onCreate. + GlobalContext.startKoin { + androidContext(this@KoinViewModelsActivity) + modules( + module { + viewModelOf(::RouteBViewModel) + } + ) + } + + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val backStack = remember { mutableStateListOf(RouteA) } + + NavDisplay( + backStack = backStack, + onBack = { backStack.removeLastOrNull() }, + + // In order to add the `ViewModelStoreNavEntryDecorator` (see comment below for why) + // we also need to add the default `NavEntryDecorator`s as well. These provide + // extra information to the entry's content to enable it to display correctly + // and save its state. + entryDecorators = listOf( + rememberSceneSetupNavEntryDecorator(), + rememberSavedStateNavEntryDecorator(), + rememberViewModelStoreNavEntryDecorator() + ), + entryProvider = entryProvider { + entry { + ContentGreen("Welcome to Nav3") { + LazyColumn { + items(10) { i -> + Button(onClick = { + backStack.add(RouteB("$i")) + }) { + Text("$i") + } + } + } + } + } + entry { key -> + val viewModel = koinViewModel { + parametersOf(key) + } + ScreenB(viewModel = viewModel) + } + } + ) + } + } +} + +@Composable +fun ScreenB(viewModel: RouteBViewModel) { + ContentBlue("Route id: ${viewModel.navKey.id} ") +} + +class RouteBViewModel(val navKey: RouteB) : ViewModel() \ No newline at end of file diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 086bb37..6056372 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -31,6 +31,7 @@ nav3Material = "1.0.0-alpha02" ksp = "2.2.0-2.0.2" hilt = "2.57.1" hiltNavigationCompose = "1.3.0" +koin = "4.1.1" [libraries] androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" } @@ -59,6 +60,7 @@ kotlinx-serialization-core = { module = "org.jetbrains.kotlinx:kotlinx-serializa kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerializationCore" } androidx-material-icons-extended = { group = "androidx.compose.material", name = "material-icons-extended" } androidx-material3-navigation3 = { group = "androidx.compose.material3.adaptive", name = "adaptive-navigation3", version.ref = "nav3Material" } +koin-compose-viewmodel = {group = "io.insert-koin", name = "koin-compose-viewmodel", version.ref = "koin"} [plugins] android-application = { id = "com.android.application", version.ref = "agp" } From 3f5fe095ecd2896df365488109622a6d835e3989 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 25 Sep 2025 17:15:20 +0200 Subject: [PATCH 34/64] Slight formatting change --- app/build.gradle.kts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/app/build.gradle.kts b/app/build.gradle.kts index f76c34b..68e275e 100644 --- a/app/build.gradle.kts +++ b/app/build.gradle.kts @@ -83,9 +83,8 @@ dependencies { implementation(libs.hilt.android) ksp(libs.hilt.compiler) - - implementation(libs.koin.compose.viewmodel) + testImplementation(libs.junit) androidTestImplementation(libs.androidx.junit) androidTestImplementation(libs.androidx.espresso.core) From a8e577e8b402a66f2fb0a11945bb4ba15108fb07 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 25 Sep 2025 17:29:21 +0200 Subject: [PATCH 35/64] Addressing AI code review --- README.md | 6 +++--- .../viewmodels/koin/KoinViewModelsActivity.kt | 17 +++++++++-------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 25333a3..36d4407 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,9 @@ These are the recipes and what they demonstrate. - **[Modularized navigation code](app/src/main/java/com/example/nav3recipes/modular/hilt)**: Demonstrates how to decouple navigation code into separate modules (uses Dagger/Hilt for DI). ### Passing navigation arguments to ViewModels -- **[Basic ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/basicviewmodels)**: Navigation arguments are passed to a ViewModel constructed using `viewModel()` -- **[Hilt injected ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/injectedviewmodels)**: Navigation arguments are passed to a ViewModel constructed using `hiltViewModel()` -- **[Koin injected ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/injectedviewmodels)**: Navigation arguments are passed to a ViewModel constructed using `koinViewModel()` +- **[Basic ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/basic)**: Navigation arguments are passed to a ViewModel constructed using `viewModel()` +- **[Hilt injected ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/hilt)**: Navigation arguments are passed to a ViewModel constructed using `hiltViewModel()` +- **[Koin injected ViewModel](app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin)**: Navigation arguments are passed to a ViewModel constructed using `koinViewModel()` ### Planned - **Deeplinks**: Create and handle deeplinks to specific destinations diff --git a/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt index 8602043..52235da 100644 --- a/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt @@ -18,7 +18,6 @@ import androidx.navigation3.ui.NavDisplay import androidx.navigation3.ui.rememberSceneSetupNavEntryDecorator import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen -import com.example.nav3recipes.passingarguments.viewmodels.basic.RouteB import com.example.nav3recipes.ui.setEdgeToEdgeConfig import org.koin.android.ext.koin.androidContext import org.koin.compose.viewmodel.koinViewModel @@ -41,13 +40,15 @@ class KoinViewModelsActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { // The startKoin block should be placed in Application.onCreate. - GlobalContext.startKoin { - androidContext(this@KoinViewModelsActivity) - modules( - module { - viewModelOf(::RouteBViewModel) - } - ) + if (GlobalContext.getOrNull() == null) { + GlobalContext.startKoin { + androidContext(this@KoinViewModelsActivity) + modules( + module { + viewModelOf(::RouteBViewModel) + } + ) + } } setEdgeToEdgeConfig() From bce2b1b22735f74c86a6d6385990c37ce45d146c Mon Sep 17 00:00:00 2001 From: Rob Orgiu Date: Mon, 29 Sep 2025 10:07:19 +0200 Subject: [PATCH 36/64] Move Material recipes to their specific package --- README.md | 6 ++++-- app/src/main/AndroidManifest.xml | 4 ++-- .../java/com/example/nav3recipes/RecipePickerActivity.kt | 4 ++-- .../listdetail}/MaterialListDetailActivity.kt | 2 +- .../supportingpane}/MaterialSupportingPaneActivity.kt | 2 +- 5 files changed, 10 insertions(+), 8 deletions(-) rename app/src/main/java/com/example/nav3recipes/{scenes/materiallistdetail => material/listdetail}/MaterialListDetailActivity.kt (98%) rename app/src/main/java/com/example/nav3recipes/{scenes/materialsupportingpane => material/supportingpane}/MaterialSupportingPaneActivity.kt (98%) diff --git a/README.md b/README.md index 36d4407..bdd327d 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,14 @@ These are the recipes and what they demonstrate. - **[Entry provider DSL](app/src/main/java/com/example/nav3recipes/basicdsl)**: As above, using the entryProvider DSL. ### Layouts and animations -- **[Material adaptive List-Detail](app/src/main/java/com/example/nav3recipes/scenes/materiallistdetail)**: Shows how to use a Material list-detail layout. -- **[Material adaptive Supporting Pane](app/src/main/java/com/example/nav3recipes/scenes/materialsupportingpane)**: Shows how to use a Material supporting pane layout. - **[Dialog](app/src/main/java/com/example/nav3recipes/dialog)**: Shows how to create a Dialog destination. - **[Custom Scene](app/src/main/java/com/example/nav3recipes/scenes/twopane)**: Shows how to create a custom layout using a `Scene` and `SceneStrategy` (see video of UI behavior below). - **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Override the default animations for all destinations and a single destination. +### Material +- **[List-Detail](app/src/main/java/com/example/nav3recipes/material/listdetail)**: Shows how to use a Material list-detail layout. +- **[Supporting Pane](app/src/main/java/com/example/nav3recipes/material/supportingpane)**: Shows how to use a Material supporting pane layout. + ### Common use cases - **[Common navigation UI](app/src/main/java/com/example/nav3recipes/commonui)**: A common navigation toolbar where each item in the toolbar navigates to a top level destination. - **[Conditional navigation](app/src/main/java/com/example/nav3recipes/conditional)**: Switch to a different navigation flow when a condition is met. For example, for authentication or first-time user onboarding. diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 3097691..dec698f 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -66,11 +66,11 @@ android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> Date: Mon, 29 Sep 2025 10:45:41 +0200 Subject: [PATCH 37/64] Update README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bdd327d..52f3fa3 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,8 @@ These are the recipes and what they demonstrate. - **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Override the default animations for all destinations and a single destination. ### Material -- **[List-Detail](app/src/main/java/com/example/nav3recipes/material/listdetail)**: Shows how to use a Material list-detail layout. -- **[Supporting Pane](app/src/main/java/com/example/nav3recipes/material/supportingpane)**: Shows how to use a Material supporting pane layout. +- **[List-Detail](app/src/main/java/com/example/nav3recipes/material/listdetail)**: Shows how to use a Material adaptive list-detail layout. +- **[Supporting Pane](app/src/main/java/com/example/nav3recipes/material/supportingpane)**: Shows how to use a Material adaptive supporting pane layout. ### Common use cases - **[Common navigation UI](app/src/main/java/com/example/nav3recipes/commonui)**: A common navigation toolbar where each item in the toolbar navigates to a top level destination. From 1f0c2eedb22e2e55ef64ddcbbc803e677f732614 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Mon, 29 Sep 2025 11:25:31 +0100 Subject: [PATCH 38/64] Update README.md --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 52f3fa3..ebdd2cc 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,9 @@ These are the recipes and what they demonstrate. - **[Custom Scene](app/src/main/java/com/example/nav3recipes/scenes/twopane)**: Shows how to create a custom layout using a `Scene` and `SceneStrategy` (see video of UI behavior below). - **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Override the default animations for all destinations and a single destination. -### Material +### Material adaptive layouts +Examples usage of the layouts provided by the [Compose Material3 Adaptive Navigation3 + library](https://developer.android.com/jetpack/androidx/releases/compose-material3-adaptive#compose_material3_adaptive_navigation3_version_10_2)``` - **[List-Detail](app/src/main/java/com/example/nav3recipes/material/listdetail)**: Shows how to use a Material adaptive list-detail layout. - **[Supporting Pane](app/src/main/java/com/example/nav3recipes/material/supportingpane)**: Shows how to use a Material adaptive supporting pane layout. From 496be6a7c9560e0cb05da6773db88d417c64680b Mon Sep 17 00:00:00 2001 From: Don Turner Date: Mon, 29 Sep 2025 11:26:09 +0100 Subject: [PATCH 39/64] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ebdd2cc..e164450 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ These are the recipes and what they demonstrate. - **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Override the default animations for all destinations and a single destination. ### Material adaptive layouts -Examples usage of the layouts provided by the [Compose Material3 Adaptive Navigation3 +Examples showing how to use the layouts provided by the [Compose Material3 Adaptive Navigation3 library](https://developer.android.com/jetpack/androidx/releases/compose-material3-adaptive#compose_material3_adaptive_navigation3_version_10_2)``` - **[List-Detail](app/src/main/java/com/example/nav3recipes/material/listdetail)**: Shows how to use a Material adaptive list-detail layout. - **[Supporting Pane](app/src/main/java/com/example/nav3recipes/material/supportingpane)**: Shows how to use a Material adaptive supporting pane layout. From 8def1d6f3ea6216386b9531b2d8f7129bcdd7640 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Mon, 29 Sep 2025 11:27:40 +0100 Subject: [PATCH 40/64] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e164450..8914844 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ These are the recipes and what they demonstrate. - **[Animations](app/src/main/java/com/example/nav3recipes/animations)**: Override the default animations for all destinations and a single destination. ### Material adaptive layouts -Examples showing how to use the layouts provided by the [Compose Material3 Adaptive Navigation3 +Examples showing how to use the layouts provided by the [Compose Material3 Adaptive Navigation3 library](https://developer.android.com/jetpack/androidx/releases/compose-material3-adaptive#compose_material3_adaptive_navigation3_version_10_2) library](https://developer.android.com/jetpack/androidx/releases/compose-material3-adaptive#compose_material3_adaptive_navigation3_version_10_2)``` - **[List-Detail](app/src/main/java/com/example/nav3recipes/material/listdetail)**: Shows how to use a Material adaptive list-detail layout. - **[Supporting Pane](app/src/main/java/com/example/nav3recipes/material/supportingpane)**: Shows how to use a Material adaptive supporting pane layout. From 804f57295d1e78e73a054c41b863be8bdf427cbd Mon Sep 17 00:00:00 2001 From: Don Turner Date: Mon, 29 Sep 2025 11:27:58 +0100 Subject: [PATCH 41/64] Update README.md --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 8914844..3c1a5eb 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,6 @@ These are the recipes and what they demonstrate. ### Material adaptive layouts Examples showing how to use the layouts provided by the [Compose Material3 Adaptive Navigation3 library](https://developer.android.com/jetpack/androidx/releases/compose-material3-adaptive#compose_material3_adaptive_navigation3_version_10_2) - library](https://developer.android.com/jetpack/androidx/releases/compose-material3-adaptive#compose_material3_adaptive_navigation3_version_10_2)``` - **[List-Detail](app/src/main/java/com/example/nav3recipes/material/listdetail)**: Shows how to use a Material adaptive list-detail layout. - **[Supporting Pane](app/src/main/java/com/example/nav3recipes/material/supportingpane)**: Shows how to use a Material adaptive supporting pane layout. From 0e5efe33af33c2c98a1b5b66869d745fb380e0ce Mon Sep 17 00:00:00 2001 From: jbw0033 Date: Tue, 19 Aug 2025 03:32:11 +0000 Subject: [PATCH 42/64] Add bottom sheet recipe This commit adds a recipe that demonstrates how to display a navigation destination within a Material `ModalBottomSheet`. It introduces `BottomSheetSceneStrategy`, a `SceneStrategy` that can be added to a `NavDisplay`. This strategy checks for specific metadata on a `NavEntry` to determine if it should be rendered as a bottom sheet. A new `BottomSheetActivity` is added to showcase how to use this strategy. --- app/src/main/AndroidManifest.xml | 4 + .../bottomsheet/BottomSheetActivity.kt | 94 +++++++++++++++++++ .../bottomsheet/BottomSheetSceneStrategy.kt | 79 ++++++++++++++++ 3 files changed, 177 insertions(+) create mode 100644 app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt create mode 100644 app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 4040165..d6afe26 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -65,6 +65,10 @@ android:name=".dialog.DialogActivity" android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> + () } + + NavDisplay( + backStack = backStack, + onBack = { backStack.removeLastOrNull() }, + sceneStrategy = bottomSheetStrategy, + entryProvider = entryProvider { + entry { + ContentGreen("Welcome to Nav3") { + Button(onClick = { + backStack.add(RouteB("123")) + }) { + Text("Click to open bottom sheet") + } + } + } + entry( + metadata = BottomSheetSceneStrategy.bottomSheet() + ) { key -> + ContentBlue( + title = "Route id: ${key.id}", + modifier = Modifier.clip( + shape = RoundedCornerShape(16.dp) + ) + ) + } + } + ) + } + } +} diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt new file mode 100644 index 0000000..0939ddb --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt @@ -0,0 +1,79 @@ +package com.example.nav3recipes.bottomsheet + +import androidx.compose.material3.ExperimentalMaterial3Api +import androidx.compose.material3.ModalBottomSheet +import androidx.compose.material3.ModalBottomSheetProperties +import androidx.compose.runtime.Composable +import androidx.navigation3.runtime.NavEntry +import androidx.navigation3.ui.OverlayScene +import androidx.navigation3.ui.Scene +import androidx.navigation3.ui.SceneStrategy + +/** An [OverlayScene] that renders an [entry] within a [ModalBottomSheet]. */ +@OptIn(ExperimentalMaterial3Api::class) +internal class BottomSheetScene( + override val key: T, + override val previousEntries: List>, + override val overlaidEntries: List>, + private val entry: NavEntry, + private val modalBottomSheetProperties: ModalBottomSheetProperties, + private val onBack: (count: Int) -> Unit, +) : OverlayScene { + + override val entries: List> = listOf(entry) + + override val content: @Composable (() -> Unit) = { + ModalBottomSheet( + onDismissRequest = { onBack(1) }, + properties = modalBottomSheetProperties, + ) { + entry.Content() + } + } +} + +/** + * A [SceneStrategy] that displays entries that have added [bottomSheet] to their [NavEntry.metadata] + * within a [ModalBottomSheet] instance. + * + * This strategy should always be added before any non-overlay scene strategies. + */ +@OptIn(ExperimentalMaterial3Api::class) +class BottomSheetSceneStrategy() : SceneStrategy { + + @Composable + override fun calculateScene( + entries: List>, + onBack: (Int) -> Unit + ): Scene? { + val lastEntry = entries.lastOrNull() + val bottomSheetProperties = lastEntry?.metadata?.get(BOTTOM_SHEET_KEY) as? ModalBottomSheetProperties + return bottomSheetProperties?.let { properties -> + @Suppress("UNCHECKED_CAST") + BottomSheetScene( + key = lastEntry.contentKey as T, + previousEntries = entries.dropLast(1), + overlaidEntries = entries.dropLast(1), + entry = lastEntry, + modalBottomSheetProperties = properties, + onBack = onBack + ) + } + } + + companion object { + /** + * Function to be called on the [NavEntry.metadata] to mark this entry as something that + * should be displayed within a [ModalBottomSheet]. + * + * @param modalBottomSheetProperties properties that should be passed to the containing + * [ModalBottomSheet]. + */ + @OptIn(ExperimentalMaterial3Api::class) + fun bottomSheet( + modalBottomSheetProperties: ModalBottomSheetProperties = ModalBottomSheetProperties() + ): Map = mapOf(BOTTOM_SHEET_KEY to modalBottomSheetProperties) + + internal const val BOTTOM_SHEET_KEY = "bottomsheet" + } +} \ No newline at end of file From 2bb993e9cbe2d6f4c7882fc87ebb90d9437085cf Mon Sep 17 00:00:00 2001 From: jbw0033 Date: Tue, 19 Aug 2025 18:07:39 +0000 Subject: [PATCH 43/64] Remove parenthesis from BottomSheetSceneStrategy Doing this for Kotlin code syntax --- .../example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt index 0939ddb..1a79615 100644 --- a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt @@ -39,7 +39,7 @@ internal class BottomSheetScene( * This strategy should always be added before any non-overlay scene strategies. */ @OptIn(ExperimentalMaterial3Api::class) -class BottomSheetSceneStrategy() : SceneStrategy { +class BottomSheetSceneStrategy : SceneStrategy { @Composable override fun calculateScene( From 8d0e30d9fdbcff436d997540c3a7fa4151bb5467 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 21 Aug 2025 17:26:34 +0100 Subject: [PATCH 44/64] Minor edits --- .../main/java/com/example/nav3recipes/RecipePickerActivity.kt | 4 +++- .../example/nav3recipes/bottomsheet/BottomSheetActivity.kt | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt b/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt index 127ad53..6437799 100644 --- a/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt @@ -29,6 +29,7 @@ import com.example.nav3recipes.animations.AnimatedActivity import com.example.nav3recipes.basic.BasicActivity import com.example.nav3recipes.basicdsl.BasicDslActivity import com.example.nav3recipes.basicsaveable.BasicSaveableActivity +import com.example.nav3recipes.bottomsheet.BottomSheetActivity import com.example.nav3recipes.commonui.CommonUiActivity import com.example.nav3recipes.conditional.ConditionalActivity import com.example.nav3recipes.dialog.DialogActivity @@ -56,8 +57,9 @@ private val recipes = listOf( Recipe("Basic Saveable", BasicSaveableActivity::class.java), Heading("Layouts and animations"), - Recipe("Material list-detail layout", MaterialListDetailActivity::class.java), + Recipe("Bottom Sheet", BottomSheetActivity::class.java), Recipe("Dialog", DialogActivity::class.java), + Recipe("Material list-detail layout", MaterialListDetailActivity::class.java), Recipe("Two pane layout (custom scene)", TwoPaneActivity::class.java), Recipe("Animations", AnimatedActivity::class.java), diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt index 29b3935..57b43b7 100644 --- a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt @@ -41,7 +41,7 @@ import kotlinx.serialization.Serializable * This recipe demonstrates how to create a bottom sheet. It does this by: * * - Adding the `BottomSheetSceneStrategy` to the list of strategies used by `NavDisplay`. - * - Adding `BottomSheetSceneStrategy.bottomsheet` to a `NavEntry`'s metadata to indicate that it + * - Adding `BottomSheetSceneStrategy.bottomSheet()` to a `NavEntry`'s metadata to indicate that it * is a bottom sheet. In this case it is applied to the `NavEntry` for `RouteB`. * * See also https://developer.android.com/guide/navigation/navigation-3/custom-layouts From df2d43efdb537f4993f8ece37024979f382eb446 Mon Sep 17 00:00:00 2001 From: jbw0033 Date: Tue, 19 Aug 2025 03:32:11 +0000 Subject: [PATCH 45/64] Add bottom sheet recipe This commit adds a recipe that demonstrates how to display a navigation destination within a Material `ModalBottomSheet`. It introduces `BottomSheetSceneStrategy`, a `SceneStrategy` that can be added to a `NavDisplay`. This strategy checks for specific metadata on a `NavEntry` to determine if it should be rendered as a bottom sheet. A new `BottomSheetActivity` is added to showcase how to use this strategy. --- app/src/main/AndroidManifest.xml | 5 + .../bottomsheet/BottomSheetActivity.kt | 94 +++++++++++++++++++ .../bottomsheet/BottomSheetSceneStrategy.kt | 79 ++++++++++++++++ 3 files changed, 178 insertions(+) create mode 100644 app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt create mode 100644 app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index dec698f..6a360a6 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -66,6 +66,11 @@ android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> + diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt new file mode 100644 index 0000000..29b3935 --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt @@ -0,0 +1,94 @@ +/* + * Copyright 2025 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example.nav3recipes.bottomsheet + +import android.os.Bundle +import androidx.activity.ComponentActivity +import androidx.activity.compose.setContent +import androidx.compose.foundation.shape.RoundedCornerShape +import androidx.compose.material3.Button +import androidx.compose.material3.ExperimentalMaterial3Api +import androidx.compose.material3.Text +import androidx.compose.runtime.remember +import androidx.compose.ui.Modifier +import androidx.compose.ui.draw.clip +import androidx.compose.ui.unit.dp +import androidx.navigation3.runtime.NavKey +import androidx.navigation3.runtime.entry +import androidx.navigation3.runtime.entryProvider +import androidx.navigation3.runtime.rememberNavBackStack +import androidx.navigation3.ui.NavDisplay +import com.example.nav3recipes.content.ContentBlue +import com.example.nav3recipes.content.ContentGreen +import com.example.nav3recipes.ui.setEdgeToEdgeConfig +import kotlinx.serialization.Serializable + +/** + * This recipe demonstrates how to create a bottom sheet. It does this by: + * + * - Adding the `BottomSheetSceneStrategy` to the list of strategies used by `NavDisplay`. + * - Adding `BottomSheetSceneStrategy.bottomsheet` to a `NavEntry`'s metadata to indicate that it + * is a bottom sheet. In this case it is applied to the `NavEntry` for `RouteB`. + * + * See also https://developer.android.com/guide/navigation/navigation-3/custom-layouts + */ + +@Serializable +private data object RouteA : NavKey + +@Serializable +private data class RouteB(val id: String) : NavKey + +class BottomSheetActivity : ComponentActivity() { + + @OptIn(ExperimentalMaterial3Api::class) + override fun onCreate(savedInstanceState: Bundle?) { + setEdgeToEdgeConfig() + super.onCreate(savedInstanceState) + setContent { + val backStack = rememberNavBackStack(RouteA) + val bottomSheetStrategy = remember { BottomSheetSceneStrategy() } + + NavDisplay( + backStack = backStack, + onBack = { backStack.removeLastOrNull() }, + sceneStrategy = bottomSheetStrategy, + entryProvider = entryProvider { + entry { + ContentGreen("Welcome to Nav3") { + Button(onClick = { + backStack.add(RouteB("123")) + }) { + Text("Click to open bottom sheet") + } + } + } + entry( + metadata = BottomSheetSceneStrategy.bottomSheet() + ) { key -> + ContentBlue( + title = "Route id: ${key.id}", + modifier = Modifier.clip( + shape = RoundedCornerShape(16.dp) + ) + ) + } + } + ) + } + } +} diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt new file mode 100644 index 0000000..0939ddb --- /dev/null +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt @@ -0,0 +1,79 @@ +package com.example.nav3recipes.bottomsheet + +import androidx.compose.material3.ExperimentalMaterial3Api +import androidx.compose.material3.ModalBottomSheet +import androidx.compose.material3.ModalBottomSheetProperties +import androidx.compose.runtime.Composable +import androidx.navigation3.runtime.NavEntry +import androidx.navigation3.ui.OverlayScene +import androidx.navigation3.ui.Scene +import androidx.navigation3.ui.SceneStrategy + +/** An [OverlayScene] that renders an [entry] within a [ModalBottomSheet]. */ +@OptIn(ExperimentalMaterial3Api::class) +internal class BottomSheetScene( + override val key: T, + override val previousEntries: List>, + override val overlaidEntries: List>, + private val entry: NavEntry, + private val modalBottomSheetProperties: ModalBottomSheetProperties, + private val onBack: (count: Int) -> Unit, +) : OverlayScene { + + override val entries: List> = listOf(entry) + + override val content: @Composable (() -> Unit) = { + ModalBottomSheet( + onDismissRequest = { onBack(1) }, + properties = modalBottomSheetProperties, + ) { + entry.Content() + } + } +} + +/** + * A [SceneStrategy] that displays entries that have added [bottomSheet] to their [NavEntry.metadata] + * within a [ModalBottomSheet] instance. + * + * This strategy should always be added before any non-overlay scene strategies. + */ +@OptIn(ExperimentalMaterial3Api::class) +class BottomSheetSceneStrategy() : SceneStrategy { + + @Composable + override fun calculateScene( + entries: List>, + onBack: (Int) -> Unit + ): Scene? { + val lastEntry = entries.lastOrNull() + val bottomSheetProperties = lastEntry?.metadata?.get(BOTTOM_SHEET_KEY) as? ModalBottomSheetProperties + return bottomSheetProperties?.let { properties -> + @Suppress("UNCHECKED_CAST") + BottomSheetScene( + key = lastEntry.contentKey as T, + previousEntries = entries.dropLast(1), + overlaidEntries = entries.dropLast(1), + entry = lastEntry, + modalBottomSheetProperties = properties, + onBack = onBack + ) + } + } + + companion object { + /** + * Function to be called on the [NavEntry.metadata] to mark this entry as something that + * should be displayed within a [ModalBottomSheet]. + * + * @param modalBottomSheetProperties properties that should be passed to the containing + * [ModalBottomSheet]. + */ + @OptIn(ExperimentalMaterial3Api::class) + fun bottomSheet( + modalBottomSheetProperties: ModalBottomSheetProperties = ModalBottomSheetProperties() + ): Map = mapOf(BOTTOM_SHEET_KEY to modalBottomSheetProperties) + + internal const val BOTTOM_SHEET_KEY = "bottomsheet" + } +} \ No newline at end of file From c303cd05dc741118a612492ef269d41d1b75d647 Mon Sep 17 00:00:00 2001 From: jbw0033 Date: Tue, 19 Aug 2025 18:07:39 +0000 Subject: [PATCH 46/64] Remove parenthesis from BottomSheetSceneStrategy Doing this for Kotlin code syntax --- .../example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt index 0939ddb..1a79615 100644 --- a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt @@ -39,7 +39,7 @@ internal class BottomSheetScene( * This strategy should always be added before any non-overlay scene strategies. */ @OptIn(ExperimentalMaterial3Api::class) -class BottomSheetSceneStrategy() : SceneStrategy { +class BottomSheetSceneStrategy : SceneStrategy { @Composable override fun calculateScene( From 49cff71811716322539a2f048f7c1eed75ef6463 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 21 Aug 2025 17:26:34 +0100 Subject: [PATCH 47/64] Minor edits --- .../main/java/com/example/nav3recipes/RecipePickerActivity.kt | 3 +++ .../com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt b/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt index 31d3634..8d60280 100644 --- a/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt @@ -29,6 +29,7 @@ import com.example.nav3recipes.animations.AnimatedActivity import com.example.nav3recipes.basic.BasicActivity import com.example.nav3recipes.basicdsl.BasicDslActivity import com.example.nav3recipes.basicsaveable.BasicSaveableActivity +import com.example.nav3recipes.bottomsheet.BottomSheetActivity import com.example.nav3recipes.commonui.CommonUiActivity import com.example.nav3recipes.conditional.ConditionalActivity import com.example.nav3recipes.dialog.DialogActivity @@ -58,9 +59,11 @@ private val recipes = listOf( Recipe("Basic Saveable", BasicSaveableActivity::class.java), Heading("Layouts and animations"), + Recipe("Bottom Sheet", BottomSheetActivity::class.java), Recipe("Material list-detail layout", MaterialListDetailActivity::class.java), Recipe("Material supporting-pane layout", MaterialSupportingPaneActivity::class.java), Recipe("Dialog", DialogActivity::class.java), + Recipe("Material list-detail layout", MaterialListDetailActivity::class.java), Recipe("Two pane layout (custom scene)", TwoPaneActivity::class.java), Recipe("Animations", AnimatedActivity::class.java), diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt index 29b3935..57b43b7 100644 --- a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt @@ -41,7 +41,7 @@ import kotlinx.serialization.Serializable * This recipe demonstrates how to create a bottom sheet. It does this by: * * - Adding the `BottomSheetSceneStrategy` to the list of strategies used by `NavDisplay`. - * - Adding `BottomSheetSceneStrategy.bottomsheet` to a `NavEntry`'s metadata to indicate that it + * - Adding `BottomSheetSceneStrategy.bottomSheet()` to a `NavEntry`'s metadata to indicate that it * is a bottom sheet. In this case it is applied to the `NavEntry` for `RouteB`. * * See also https://developer.android.com/guide/navigation/navigation-3/custom-layouts From a857897f146c73ee5ab7446d02c9157cd7b030ca Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 2 Oct 2025 17:33:24 +0100 Subject: [PATCH 48/64] Update to alpha10 --- .../nav3recipes/animations/AnimatedActivity.kt | 1 - .../nav3recipes/basicdsl/BasicDslActivity.kt | 1 - .../nav3recipes/commonui/CommonUiActivity.kt | 1 - .../conditional/ConditionalActivity.kt | 1 - .../nav3recipes/dialog/DialogActivity.kt | 3 +-- .../listdetail/MaterialListDetailActivity.kt | 1 - .../MaterialSupportingPaneActivity.kt | 1 - .../modular/hilt/ConversationModule.kt | 1 - .../nav3recipes/modular/hilt/ProfileModule.kt | 1 - .../basic/BasicViewModelsActivity.kt | 3 +-- .../viewmodels/hilt/HiltViewModelsActivity.kt | 5 ++--- .../viewmodels/koin/KoinViewModelsActivity.kt | 3 +-- .../scenes/twopane/TwoPaneActivity.kt | 5 ++--- .../nav3recipes/scenes/twopane/TwoPaneScene.kt | 5 ++--- gradle/libs.versions.toml | 18 +++++++++--------- 15 files changed, 18 insertions(+), 32 deletions(-) diff --git a/app/src/main/java/com/example/nav3recipes/animations/AnimatedActivity.kt b/app/src/main/java/com/example/nav3recipes/animations/AnimatedActivity.kt index b906976..9fdac6d 100644 --- a/app/src/main/java/com/example/nav3recipes/animations/AnimatedActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/animations/AnimatedActivity.kt @@ -15,7 +15,6 @@ import androidx.compose.animation.togetherWith import androidx.compose.material3.Button import androidx.compose.material3.Text import androidx.navigation3.runtime.NavKey -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberNavBackStack import androidx.navigation3.ui.NavDisplay diff --git a/app/src/main/java/com/example/nav3recipes/basicdsl/BasicDslActivity.kt b/app/src/main/java/com/example/nav3recipes/basicdsl/BasicDslActivity.kt index bad77ca..3b25100 100644 --- a/app/src/main/java/com/example/nav3recipes/basicdsl/BasicDslActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/basicdsl/BasicDslActivity.kt @@ -22,7 +22,6 @@ import androidx.activity.compose.setContent import androidx.compose.material3.Button import androidx.compose.material3.Text import androidx.navigation3.runtime.NavKey -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberNavBackStack import androidx.navigation3.ui.NavDisplay diff --git a/app/src/main/java/com/example/nav3recipes/commonui/CommonUiActivity.kt b/app/src/main/java/com/example/nav3recipes/commonui/CommonUiActivity.kt index 2b1cb0e..bd3d014 100644 --- a/app/src/main/java/com/example/nav3recipes/commonui/CommonUiActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/commonui/CommonUiActivity.kt @@ -36,7 +36,6 @@ import androidx.compose.runtime.remember import androidx.compose.runtime.setValue import androidx.compose.runtime.snapshots.SnapshotStateList import androidx.compose.ui.graphics.vector.ImageVector -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.ui.NavDisplay import com.example.nav3recipes.content.ContentBlue diff --git a/app/src/main/java/com/example/nav3recipes/conditional/ConditionalActivity.kt b/app/src/main/java/com/example/nav3recipes/conditional/ConditionalActivity.kt index ccc15e1..18f9670 100644 --- a/app/src/main/java/com/example/nav3recipes/conditional/ConditionalActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/conditional/ConditionalActivity.kt @@ -27,7 +27,6 @@ import androidx.compose.runtime.mutableStateListOf import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember import androidx.compose.runtime.setValue -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.ui.NavDisplay import com.example.nav3recipes.content.ContentBlue diff --git a/app/src/main/java/com/example/nav3recipes/dialog/DialogActivity.kt b/app/src/main/java/com/example/nav3recipes/dialog/DialogActivity.kt index 4d69ed8..3923d25 100644 --- a/app/src/main/java/com/example/nav3recipes/dialog/DialogActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/dialog/DialogActivity.kt @@ -28,10 +28,9 @@ import androidx.compose.ui.draw.clip import androidx.compose.ui.unit.dp import androidx.compose.ui.window.DialogProperties import androidx.navigation3.runtime.NavKey -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberNavBackStack -import androidx.navigation3.ui.DialogSceneStrategy +import androidx.navigation3.scene.DialogSceneStrategy import androidx.navigation3.ui.NavDisplay import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen diff --git a/app/src/main/java/com/example/nav3recipes/material/listdetail/MaterialListDetailActivity.kt b/app/src/main/java/com/example/nav3recipes/material/listdetail/MaterialListDetailActivity.kt index a7e5058..370d2f6 100644 --- a/app/src/main/java/com/example/nav3recipes/material/listdetail/MaterialListDetailActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/material/listdetail/MaterialListDetailActivity.kt @@ -31,7 +31,6 @@ import androidx.compose.runtime.remember import androidx.compose.ui.Alignment import androidx.compose.ui.unit.dp import androidx.navigation3.runtime.NavKey -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberNavBackStack import androidx.navigation3.ui.NavDisplay diff --git a/app/src/main/java/com/example/nav3recipes/material/supportingpane/MaterialSupportingPaneActivity.kt b/app/src/main/java/com/example/nav3recipes/material/supportingpane/MaterialSupportingPaneActivity.kt index 8e8c694..0241621 100644 --- a/app/src/main/java/com/example/nav3recipes/material/supportingpane/MaterialSupportingPaneActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/material/supportingpane/MaterialSupportingPaneActivity.kt @@ -32,7 +32,6 @@ import androidx.compose.runtime.remember import androidx.compose.ui.Alignment import androidx.compose.ui.unit.dp import androidx.navigation3.runtime.NavKey -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberNavBackStack import androidx.navigation3.ui.NavDisplay diff --git a/app/src/main/java/com/example/nav3recipes/modular/hilt/ConversationModule.kt b/app/src/main/java/com/example/nav3recipes/modular/hilt/ConversationModule.kt index c99cd75..25dcc98 100644 --- a/app/src/main/java/com/example/nav3recipes/modular/hilt/ConversationModule.kt +++ b/app/src/main/java/com/example/nav3recipes/modular/hilt/ConversationModule.kt @@ -20,7 +20,6 @@ import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color import androidx.compose.ui.unit.dp -import androidx.navigation3.runtime.entry import com.example.nav3recipes.ui.theme.colors import dagger.Module import dagger.Provides diff --git a/app/src/main/java/com/example/nav3recipes/modular/hilt/ProfileModule.kt b/app/src/main/java/com/example/nav3recipes/modular/hilt/ProfileModule.kt index 4d399a3..6c8b7f3 100644 --- a/app/src/main/java/com/example/nav3recipes/modular/hilt/ProfileModule.kt +++ b/app/src/main/java/com/example/nav3recipes/modular/hilt/ProfileModule.kt @@ -11,7 +11,6 @@ import androidx.compose.runtime.Composable import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.unit.dp -import androidx.navigation3.runtime.entry import dagger.Module import dagger.Provides import dagger.hilt.InstallIn diff --git a/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/basic/BasicViewModelsActivity.kt b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/basic/BasicViewModelsActivity.kt index 9017a39..dd1463f 100644 --- a/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/basic/BasicViewModelsActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/basic/BasicViewModelsActivity.kt @@ -29,11 +29,10 @@ import androidx.lifecycle.ViewModel import androidx.lifecycle.ViewModelProvider import androidx.lifecycle.viewmodel.compose.viewModel import androidx.lifecycle.viewmodel.navigation3.rememberViewModelStoreNavEntryDecorator -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberSavedStateNavEntryDecorator +import androidx.navigation3.scene.rememberSceneSetupNavEntryDecorator import androidx.navigation3.ui.NavDisplay -import androidx.navigation3.ui.rememberSceneSetupNavEntryDecorator import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen import com.example.nav3recipes.ui.setEdgeToEdgeConfig diff --git a/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/hilt/HiltViewModelsActivity.kt b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/hilt/HiltViewModelsActivity.kt index e812755..093d593 100644 --- a/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/hilt/HiltViewModelsActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/hilt/HiltViewModelsActivity.kt @@ -25,14 +25,13 @@ import androidx.compose.material3.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.mutableStateListOf import androidx.compose.runtime.remember -import androidx.hilt.navigation.compose.hiltViewModel +import androidx.hilt.lifecycle.viewmodel.compose.hiltViewModel import androidx.lifecycle.ViewModel import androidx.lifecycle.viewmodel.navigation3.rememberViewModelStoreNavEntryDecorator -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberSavedStateNavEntryDecorator +import androidx.navigation3.scene.rememberSceneSetupNavEntryDecorator import androidx.navigation3.ui.NavDisplay -import androidx.navigation3.ui.rememberSceneSetupNavEntryDecorator import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen import com.example.nav3recipes.passingarguments.viewmodels.basic.RouteB diff --git a/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt index 52235da..3374677 100644 --- a/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/passingarguments/viewmodels/koin/KoinViewModelsActivity.kt @@ -11,11 +11,10 @@ import androidx.compose.runtime.mutableStateListOf import androidx.compose.runtime.remember import androidx.lifecycle.ViewModel import androidx.lifecycle.viewmodel.navigation3.rememberViewModelStoreNavEntryDecorator -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberSavedStateNavEntryDecorator +import androidx.navigation3.scene.rememberSceneSetupNavEntryDecorator import androidx.navigation3.ui.NavDisplay -import androidx.navigation3.ui.rememberSceneSetupNavEntryDecorator import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen import com.example.nav3recipes.ui.setEdgeToEdgeConfig diff --git a/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt b/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt index 6273c89..db6202c 100644 --- a/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneActivity.kt @@ -35,14 +35,13 @@ import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.navigation3.runtime.NavBackStack import androidx.navigation3.runtime.NavKey -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.navEntryDecorator import androidx.navigation3.runtime.rememberNavBackStack import androidx.navigation3.runtime.rememberSavedStateNavEntryDecorator +import androidx.navigation3.scene.rememberSceneSetupNavEntryDecorator import androidx.navigation3.ui.LocalNavAnimatedContentScope import androidx.navigation3.ui.NavDisplay -import androidx.navigation3.ui.rememberSceneSetupNavEntryDecorator import com.example.nav3recipes.content.ContentBase import com.example.nav3recipes.content.ContentGreen import com.example.nav3recipes.content.ContentRed @@ -105,7 +104,7 @@ class TwoPaneActivity : ComponentActivity() { val backStack = rememberNavBackStack(Home) - val twoPaneStrategy = remember { TwoPaneSceneStrategy() } + val twoPaneStrategy = remember { TwoPaneSceneStrategy() } SharedTransitionLayout { CompositionLocalProvider(localNavSharedTransitionScope provides this) { diff --git a/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneScene.kt b/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneScene.kt index c214625..03b8b11 100644 --- a/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneScene.kt +++ b/app/src/main/java/com/example/nav3recipes/scenes/twopane/TwoPaneScene.kt @@ -7,11 +7,10 @@ import androidx.compose.material3.adaptive.ExperimentalMaterial3AdaptiveApi import androidx.compose.material3.adaptive.currentWindowAdaptiveInfo import androidx.compose.material3.windowsizeclass.ExperimentalMaterial3WindowSizeClassApi import androidx.compose.runtime.Composable -import androidx.compose.runtime.remember import androidx.compose.ui.Modifier import androidx.navigation3.runtime.NavEntry -import androidx.navigation3.ui.Scene -import androidx.navigation3.ui.SceneStrategy +import androidx.navigation3.scene.Scene +import androidx.navigation3.scene.SceneStrategy import androidx.window.core.layout.WindowSizeClass.Companion.WIDTH_DP_MEDIUM_LOWER_BOUND diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 6056372..9bddd58 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -14,21 +14,21 @@ [versions] agp = "8.11.2" -kotlin = "2.2.20" -kotlinSerialization = "2.2.20" +kotlin = "2.2.10" +kotlinSerialization = "2.2.10" coreKtx = "1.17.0" junit = "4.13.2" junitVersion = "1.3.0" espressoCore = "3.7.0" kotlinxSerializationCore = "1.9.0" -lifecycleRuntimeKtx = "2.9.3" +lifecycleRuntimeKtx = "2.9.4" lifecycleViewmodel = "1.0.0-alpha04" -activityCompose = "1.12.0-alpha08" -composeBom = "2025.09.00" -navigation3 = "1.0.0-alpha09" -material3 = "1.4.0-rc01" -nav3Material = "1.0.0-alpha02" -ksp = "2.2.0-2.0.2" +activityCompose = "1.12.0-alpha09" +composeBom = "2025.09.01" +navigation3 = "1.0.0-alpha10" +material3 = "1.4.0" +nav3Material = "1.0.0-alpha03" +ksp = "2.2.10-2.0.2" hilt = "2.57.1" hiltNavigationCompose = "1.3.0" koin = "4.1.1" From 2648ce84c225734c8f149c9d3aa64980db625a45 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Thu, 2 Oct 2025 18:57:37 +0100 Subject: [PATCH 49/64] Update gradle/libs.versions.toml Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- gradle/libs.versions.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 9bddd58..8ba50ba 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -14,7 +14,7 @@ [versions] agp = "8.11.2" -kotlin = "2.2.10" +kotlin = "2.2.10" # Downgraded from 2.2.20 to align with KSP kotlinSerialization = "2.2.10" coreKtx = "1.17.0" junit = "4.13.2" From 72108df78805742575a5d8316129b08f14f52ac0 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 10:58:42 +0100 Subject: [PATCH 50/64] Add migration guide --- docs/MigratingFromNavigation2.md | 640 +++++++++++++++++++++++++++++++ 1 file changed, 640 insertions(+) create mode 100644 docs/MigratingFromNavigation2.md diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md new file mode 100644 index 0000000..0c6f3a2 --- /dev/null +++ b/docs/MigratingFromNavigation2.md @@ -0,0 +1,640 @@ +# Navigation 2 to 3 migration guide + +## Overview {:#overview} + +This is intended to be a general guide to [Navigation 2][2] to [Navigation 3][3] +migration which can be applied to any project. It attempts to keep the project +in a working state during migration (build succeeds, navigation tests pass) and +does this by maintaining interoperability between Nav2 and Nav3. + +The guide assumes that the project is [modularized][4], and the suggested +approach allows feature modules to adopt Nav3 on an incremental basis. Once all +feature modules have migrated, the Nav2 code can be safely removed. If the +codebase is not modularized, the steps for specific modules should be applied to +the main `app` module. + +### Features {:#features} + +This guide covers the migration of the following Nav2 features: + +- Nested navigation graphs - single level of nesting only +- Shared destinations - ones that can appear in different navigation graphs +- Dialog destinations + +The following features are not yet supported: + +- More than one level of nested navigation +- [Custom destination types][5] +- Deeplinks + +### Prerequisites {:#prerequisites} + +- Familiarity with [navigation terminology][2]. +- Destinations are Composable functions. Nav3 is designed exclusively for + Compose. Fragment destinations can be wrapped with [`AndroidFragment`][6] for + interoperability with Compose. +- Routes are strongly typed. If you are using string-based routes, [migrate to + type-safe routes][7]{:.external} first ([example][8]. +- Optional but highly recommended: test coverage that verifies existing + navigation behavior. These will ensure that during migration, navigation + behavior is not changed. See [here for an example of navigation + tests][9]{:.external}. +- Your app must have a [minSdk][10] of 23 or above. + +## Step-by-step code examples {:#step-by-step-code} + +A [migration recipe][11]{:.external} exists to accompany this guide. It starts +with an activity containing only Nav2 code. The end state of each migration step +is represented by another activity. Instrumented tests verify the navigation +behavior in every step. + +To use the migration recipe as a guide: + +- Clone the [nav3-recipes repository][12]{:.external}, load it into Android + Studio and switch to the Android view in the project explorer +- Expand the `com.example.nav3recipes.migration` package +- Open `start.StartMigrationActivity`. Familiarise yourself with the navigation + structure and behavior defined in this activity. For simplicity, the recipe + codebase is not modularized, however, it is structured in a way that should + make it clear where the module boundaries would be in a real app. This is the + starting point for migration. +- Open `MigrationActivityNavigationTest` which is under the `androidTest` source + set. This file contains the instrumented tests that verify the navigation + behavior. +- Run the tests. Note that the tests are run on every migration step activity. + +Tips for working with the migration recipe: + +- It can be useful to see the differences between migration steps. To do this, + highlight both files in Android Studio project explorer then right click and + choose "Compare files". The first file to be selected is the one that will + appear in the left window pane. + +
+ INSERT ALT TEXT HERE +
Figure 2. INSERT CAPTION HERE
+
+ +- To run the migration tests only on a single activity, uncomment the other + activities in the `data` function inside `MigrationActivityNavigationTest`. +- The migration steps introduce a `Navigator` class. Setting its + `shouldPrintDebugInfo` parameter to `true` will output lots of debug + information to Logcat. + +## Step 1. Add the Nav3 dependencies {:#step-1.} + +The latest dependencies can be found here: +[https://developer.android.com/guide/navigation/navigation-3/get-started][13] + +- Update `lib.versions.toml` to include the Nav3 dependencies. Use the [latest + version from here][14]. + +``` +androidxNavigation3 = "1.0.0-alpha07" +androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "androidxNavigation3" } +androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" } +``` + +### 1.1 Create a common navigation module {:#1.1-create} + +- If you don't have one already, create a :`core:navigation` module +- Add the Nav3 runtime as a dependency using + `api(libs.androidx.navigation3.runtime). This` allows modules depending on + :core:navigation `to` use the Nav3 runtime API. +- Add the Nav2 dependencies. These will be removed once migration is complete. + +Example `build.gradle.kts`: + +``` +dependencies { + api(libs.androidx.navigation3.runtime) + implementation(libs.androidx.navigation2) +} +``` + +**Note**: Nav3 has two libraries: `runtime` and `ui`. Usually only the `app` +module needs to depend on `navigation3.ui` which is why it isn't included in the +:`core:navigation` dependencies above. + +### 1.2 Update main app module {:#1.2-update} + +- Update the `app` module to depend on :`core:navigation` and on + `androidx.navigation3.ui` +- Update compileSdk to 36 or above +- Update minSdk to 23 or above +- Update AGP to 8.9.3 or above + +## Step 2. Create a back stack and use it with NavDisplay {:#step-2.} + +### 2.1 Add the Navigator class {:#2.1-add} + +Important: A fundamental difference between Nav2 and Nav3 is that **you own the +back stack**. This means much of the logic and state that was previously managed +by Nav2, must now be managed by you. This gives you greater flexibility and +control, but also more responsibility. + +To aid with migration, a class which provides and manages a back stack named +`Navigator` is provided for you. It is not part of the Nav3 library and it does +not provide all the features of Nav2. Instead it is intended to be an assistant +during migration, and after to be a starting point for you to implement your own +navigation behavior and logic. + +Copy the [`Navigator`][15]{:.external} [class][15]{:.external} to the +:`core:navigation` module. This class contains `backStack: +SnapshotStateList` that can be used with `NavDisplay.It` will mirror +`NavController`'s back stack ensuring that Nav2's state remains the source of +truth throughout migration. After the migration is complete, the NavController +mirroring code will be removed. + +### 2.2 Make the Navigator available everywhere that NavController is +{:#2.2-make} + +Goal: The `Navigator` class is available everywhere that `NavController` is +used. + +- Create the `Navigator` immediately after `NavController` is created + +Example: + +``` +val navController = rememberNavController() +val navigator = remember { Navigator(navController) } +``` + +- Do a project-wide search for "NavController" and "NavHostController" +- Update any classes or methods that accept a `NavController` or + `NavHostController` to also accept `Navigator` as a parameter + +### 2.3 Wrap NavHost with NavDisplay {:#2.3-wrap} + +Goal: `NavDisplay` displays your existing `NavHost` using a fallback `NavEntry`. + +- Wrap `NavHost` with a `NavDisplay` +- Pass your `Navigator`'s back stack to the `NavDisplay` +- Set `NavDisplay.onBack` to call `navigator.goBack()` +- Create an `entryProvider` with a `fallback` lambda that always displays the + existing `NavHost` + +Example: + +``` +NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) { + NavHost(...) + } + }, + ) { + // No Nav3 entries yet + }, +) +``` + +## Step 3. [Single feature] Migrate routes {:#step-3.} + +Goal: Routes are moved into their own :`feature:api` module and their properties +are modelled outside of `NavHost` + +### 3.1 Split feature module into api and impl {:#3.1-split} + +Choose **a single feature module** that does not contain the start destination +for your app. The feature module containing the start destination will be +migrated last. + +Create the `api` module: + +- Create a new feature module named :`:api` +- Move the routes into it +- Apply the KotlinX Serialization plugin to the module by updating the + `build.gradle.kts` + +Update the :`core:navigation` module: + +- Add a dependency on :`:api` - this allows `Navigator` to + access the feature's routes. It is not good practice for :`core` modules to + depend on :`feature` modules, however, this is necessary during migration. + This dependency will be removed once migration is complete. + +Create the `impl` module: + +- Move the remaining contents of :`` into + :`:impl` +- Add the following dependencies: + - :`:api` so it has access to the routes + - :`core:navigation` so it has access to the Nav3 APIs and the `Navigator` + class + +Update :`app` dependencies: + +- Update the :`app` module to depend on both :`:api` and + :`:impl`. + +### 3.2 Model nested navigation graphs {:#3.2-model} + +Skip this section if you don't use nested navigation graphs. + +#### 3.2.1 Nested graph migration overview + +In Nav2, you can define nested navigation graphs using the `navigation` builder +function inside `NavHost. NavController` provides a back stack for each nested +graph. This allows you to have several top level destinations, each with +sub-destinations. You can also define shared destinations - ones that are +accessible from more than one navigation graph - by duplicating the destination +in multiple graphs. + +For example, the following code defines two nested navigation graphs, each +containing a shared destination defined by `RouteE`. + +``` +@Serializable private data object BaseRouteA +@Serializable private data object RouteA +@Serializable private data object RouteA1 +@Serializable private data object BaseRouteB +@Serializable private data object RouteB +@Serializable private data object RouteB1 +@Serializable private data object RouteE + +NavHost(startDestination = BaseRouteA){ + navigation(startDestination = RouteA) { + composable { ContentRed("Route A title") } + composable { ContentRed("Route A1 title") } + composable { SharedScreen() } + } + navigation(startDestination = RouteB) { + composable { ContentRed("Route B title") } + composable { ContentRed("Route B1 title") } + composable { SharedScreen() } + } +} +``` + +In Nav3, how you model relationships between routes is up to you. In this +migration guide, `NavHost` will be removed so it's important that the properties +and relationships defined here are captured elsewhere. + +One possible way of modelling these properties (though by no means the only +way), is to define marker interfaces for the top level and shared routes. + +``` +@Serializable private data object RouteA : Route.TopLevel +@Serializable private data object RouteA1 +@Serializable private data object RouteB : Route.TopLevel +@Serializable private data object RouteB1 +@Serializable private data object RouteE : Route.Shared + +sealed interface Route { + interface TopLevel : Route + interface Shared : Route +} +``` + +Once modelled, the nested navigation and shared destination behavior can be +implemented as follows inside a class that provides a back stack, such as the +provided `Navigator`. + +##### For nested navigation + +- Each top level route has its own back stack. +- The first element in that back stack is the top level route - this approach + means we no longer need the `BaseRoute` objects to identify each nested + navigation graph, the first element is sufficient. +- The current top level route is tracked and sub routes are added to its back + stack - there is no explicit definition of parent-child relationships between + routes +- When the top level route changes, other top level stacks can be retained or + discarded. +- The top level stacks can be flattened into a single list which is observed by + `NavDisplay`. + +##### For shared routes + +- When navigating to a route that implements `Route.Shared`, check whether it's + already on a top level stack: + - If so, move it to the current top level stack + - If not, add it to the current top level stack + +##### Example + +Taking the code example from above. The starting route is A. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

User action

Current top level route

Top level stacks

Back stack

Notes

Open app

A

A => [A]

A

Tap on A1

A

A => [A, A1]

A, A1

Tap on B

B

A => [A, A1]

B => [B]

A, A1, B

Tap on B1

B

A => [A, A1]

B => [B, B1]

A, A1, B, B1

Tap on E

B

A => [A, A1]

B => [B, B1, E]

A, A1, B, B1, E

Tap on A

A

A => [A, A1]

A, A1

We make the decision to pop all B's routes from the stack, this is similar to using popUpTo(A) when navigating using Nav2

Tap on E

A

A => [A, A1, E]

A, A1, E

+ +##### Steps + +Review the provided `Navigator` class to ensure that it can model your app's current navigation behavior. In particular: + +- Review the [`add`][16]{:.external} [method][16]{:.external} +- Note that `popUpTo` in the [`navigate`][17]{:.external} [method][17]{:.external} will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. + +#### 3.2.2 Update routes to implement marker interfaces + +Steps: + +- Update each top level route so that it implements the `Route.TopLevel` interface provided by `Navigator.kt` +- Update each shared route so that it implements the `Route.Shared` interface provided by `Navigator.kt` + +## Step 4. [Single feature] Move destinations from NavHost to entryProvider {:#step-4.} + +Goal: When navigating to a route, it is provided using `NavDisplay's entryProvider`. + +### 4.1 Move composable content from NavHost into entryProvider {:#4.1-move} + +Continue only with the feature module being migrated in the previous step. + +#### 4.1.1 Move directly defined destinations, such as composable + +For each destination inside `NavHost`, do the following based the destination type: + +- `navigation` - do nothing +- `composable` - Copy the function into `entryProvider` and rename `composable` to `entry`, retaining the type parameter. Remove the composable content from the old `composable` leaving it empty i.e., `composable`{}. +- `dialog` - Same as composable but add metadata to the entry as follows: entry(metadata `= DialogSceneStrategy.dialog()`) + - If you haven't already, add `DialogSceneStrategy` to `NavDisplay's sceneStrategy` parameter. +- [`bottomSheet`][18] - [Follow the bottom sheet recipe here][19]{:.external}. This essentially the same as the instructions for `dialog` except that `BottomSheetSceneStrategy` is not part of the core Nav3 library and so should be copied/modified to your individual requirements. + +#### 4.1.2 Obtain navigation arguments + +In Nav2, when navigation arguments are passed using the route instance, you must first obtain the route instance from `NavBackStackEntry` by calling `toRoute`. In Nav3, the route instance is directly accessible with `entry`'s lambda parameter so there's no need to obtain the route instance. + +If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels][20]{:.external} and apply the technique most appropriate to your codebase. + +#### 4.1.3 Code example + +Existing code: + +``` +NavHost(...){ + navigation(startDestination = RouteB) { + composable{ entry -> + val id = entry.toRoute().id + Text("Route B, id: $id") + } + dialog { Text ("Dialog D") } + } +} +``` + +New code: + +``` +NavHost(...){ + navigation(startDestination = RouteB) { + composable{} + dialog {} + } +} + +NavDisplay(..., + sceneStrategy = remember { DialogSceneStrategy() }, + entryProvider = entryProvider { + entry{ route -> Text("Route B, id: ${route.id}") } + entry(metadata = DialogSceneStrategy.dialog()) { Text ("Dialog D") } + } +) +``` + +#### 4.2.1 Move NavGraphBuilder extension functions + +[`NavGraphBuilder`][21] [extension functions][21] can be refactored to `EntryProviderBuilder` extension functions. These functions can then be called inside `entryProvider`. + +Refactoring `NavHost`: + +- Copy the function call into `entryProvider` +- Inline the original function reference and keep the existing function + +
+ INSERT ALT TEXT HERE +
Figure 3. INSERT CAPTION HERE
+
+ +- Remove any composable content associated with the entries inside `NavHost`. Keeping blank entries for each route ensures that `NavController`'s back stack is still the source of truth for the navigation state. + +Refactoring the extension function: + +- Change the method signature from `NavGraphBuilder.existingScreen()` to `EntryProviderBuilder.existingScreen()`. +- Remove `navigation` destinations, leaving only the destinations they contain. +- Replace `composable` and `dialog` destinations with `entry` + - For `dialog` destinations add the dialog metadata following the instructions in the previous step + +#### 4.2.2 Code example + +Existing code: + +``` +NavHost(...) { + featureBSection() +} + +private fun NavGraphBuilder.featureBSection(onDetailClick: () -> Unit) { + navigation(startDestination = RouteB) { + composable { ContentRed("Route B title") } + } +} +``` + +New code: + +``` +NavHost(...) { + navigation(startDestination = RouteB) { + composable { } + } +} + +NavDisplay(..., entryProvider = entryProvider { + featureBSection() +}) + +private fun EntryProviderBuilder.featureBSection() { + entry { ContentRed("Route B title") } +} +``` + +### 4.3 In Navigator, convert NavBackStackEntry back to its route instance {:#4.3-navigator,} + +Steps: + +- Locate the line starting `val route` in `Navigator`. +- Add an `if` branch for each migrated route that converts the `NavBackStackEntry` into a route instance using `NavBackStackEntry.toRoute`. For example: + +``` +val route = + if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else { + // Non migrated route + entry + } +``` + +You should now be able to navigate to, and back from, the migrated destinations. These destinations will be displayed directly inside `NavDisplay` rather than by `NavHost`. + +**Note**: When navigating (both forward and back) between destinations handled by `NavHost` and `NavDisplay`, you may see the blank destination until the transition animation has completed. + +## Step 5. [Single feature] Replace NavController with Navigator {:#step-5.} + +Goal: Within the migrated feature module, navigation events are handled by `Navigator` instead of `NavController` + +Steps: + +- Replace `NavController.popBackStack` with `Navigator.goBack` +- Replace `NavController.navigate` with Navigator.navigate + +TODO: Add warning about `navOptions` - you'll need to modify `Navigator` behavior if you don't like what it does + +For `NavController` extension functions defined by **other modules**: + +- Inline the function, leaving the other module's function in place +- Make the replacements above + +Remove Nav2 imports and module dependencies: + +- Remove all imports starting with `import androidx.navigation` +- Remove feature module dependencies on `androidx.navigation` + +At this point, this feature module has been fully migrated to Nav3. + +## Step 6. Migrate all feature modules {:#step-6.} + +Goal: Feature modules use Nav3. They don't contain any Nav2 code. + +Complete steps 3-5 for each feature module. Start with the module with the least dependencies and end with the module that contains the start route. + +Ensure that shared entries are not duplicated. + +## Step 7. Use Navigator.backStack as source of truth for navigation state {:#step-7.} + +### 7.1 Ensure Navigator is used instead of NavController everywhere {:#7.1-ensure} + +Replace any remaining instances of: + +- `NavController.navigate` with `Navigator.navigate` +- `NavController.popBackStack` with `Navigator.goBack` + +### 7.2 Update Navigator to modify its back stack directly {:#7.2-update} + +- Open `Navigator` +- In `navigate` and `goBack`: + - Remove the code that calls `NavController` + - Uncomment the code that modifies the back stack directly +- Remove all code which references `NavController` + +The final `Navigator` [should look like this][22]{:.external}. + +### 7.3 Set the app's start route {:#7.3-set} + +When creating the `Navigator` specify the starting route for your app. + +``` +val navigator = remember { Navigator(navController, startRoute = RouteA) } +``` + +### 7.4 Update common navigation UI components {:#7.4-update} + +If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here][23]{:.external}. + +In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. `BaseRouteA` and `RouteA`). This is no longer necessary so remove any redundant types for the navigation graph from the :`api` modules. Ensure that the correct types are used to identify top level routes. + +### 7.5 Remove the entryProvider fallback {:#7.5-remove} + +Remove the `fallback` parameter from `entryProvider` as there are no longer any unmigrated routes that must be handled by `NavHost`. + +### 7.6. Remove unused dependencies {:#7.6.-remove} + +- Remove all remaining Nav2 dependencies from the project +- In :`core:navigation` remove any dependencies on :`feature:api` modules + +Congratulations! Your project is now migrated to Navigation 3. + +## Next steps {:#next-steps} + +In the supplied `Navigator`, the type of items in the back stack is `Any`. You may now want to change this to use stronger types, for example the `NavKey` interface provided by Nav3. + +[1]: http://goto.google.com/nav2to3 +[2]: https://developer.android.com/guide/navigation +[3]: https://developer.android.com/guide/navigation/navigation-3 +[4]: https://developer.android.com/topic/modularization +[5]: https://developer.android.com/guide/navigation/design/kotlin-dsl#custom +[6]: https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1) +[7]: https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657 +[8]: https://github.com/android/nowinandroid/pull/1413){:.external} +[9]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +[10]: /guide/topics/manifest/uses-sdk-element#min +[11]: https://github.com/android/nav3-recipes/tree/dt/2to3migration +[12]: https://github.com/android/nav3-recipes +[13]: /guide/navigation/navigation-3/get-started +[14]: /jetpack/androidx/releases/navigation3 +[15]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt +[16]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142 +[17]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121 +[18]: /reference/kotlin/androidx/compose/material/navigation/package-summary#(androidx.navigation.NavGraphBuilder).bottomSheet(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2) +[19]: https://github.com/android/nav3-recipes/pull/67 +[20]: https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels +[21]: /guide/navigation/design/encapsulate +[22]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15 +[23]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94 From 0c9eb4b487926110a47651b67e72bbe848907745 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 11:06:47 +0100 Subject: [PATCH 51/64] Update guide --- docs/MigratingFromNavigation2.md | 377 ++++++++++++------------------- 1 file changed, 143 insertions(+), 234 deletions(-) diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index 0c6f3a2..10ed8a6 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -1,19 +1,12 @@ # Navigation 2 to 3 migration guide -## Overview {:#overview} +## Overview {#overview} -This is intended to be a general guide to [Navigation 2][2] to [Navigation 3][3] -migration which can be applied to any project. It attempts to keep the project -in a working state during migration (build succeeds, navigation tests pass) and -does this by maintaining interoperability between Nav2 and Nav3. +This is intended to be a general guide to [Navigation 2][1] to [Navigation 3][2] migration which can be applied to any project. It attempts to keep the project in a working state during migration (build succeeds, navigation tests pass) and does this by maintaining interoperability between Nav2 and Nav3. -The guide assumes that the project is [modularized][4], and the suggested -approach allows feature modules to adopt Nav3 on an incremental basis. Once all -feature modules have migrated, the Nav2 code can be safely removed. If the -codebase is not modularized, the steps for specific modules should be applied to -the main `app` module. +The guide assumes that the project is [modularized][3], and the suggested approach allows feature modules to adopt Nav3 on an incremental basis. Once all feature modules have migrated, the Nav2 code can be safely removed. If the codebase is not modularized, the steps for specific modules should be applied to the main `app` module. -### Features {:#features} +### Features {#features} This guide covers the migration of the following Nav2 features: @@ -24,72 +17,43 @@ This guide covers the migration of the following Nav2 features: The following features are not yet supported: - More than one level of nested navigation -- [Custom destination types][5] +- [Custom destination types][4] - Deeplinks -### Prerequisites {:#prerequisites} +### Prerequisites {#prerequisites} -- Familiarity with [navigation terminology][2]. -- Destinations are Composable functions. Nav3 is designed exclusively for - Compose. Fragment destinations can be wrapped with [`AndroidFragment`][6] for - interoperability with Compose. -- Routes are strongly typed. If you are using string-based routes, [migrate to - type-safe routes][7]{:.external} first ([example][8]. -- Optional but highly recommended: test coverage that verifies existing - navigation behavior. These will ensure that during migration, navigation - behavior is not changed. See [here for an example of navigation - tests][9]{:.external}. -- Your app must have a [minSdk][10] of 23 or above. +- Familiarity with [navigation terminology][1]. +- Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [`AndroidFragment`][5] for interoperability with Compose. +- Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes][6] first ([example][7]. +- Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests][8]. +- Your app must have a [minSdk][9] of 23 or above. -## Step-by-step code examples {:#step-by-step-code} +## Step-by-step code examples {#step-by-step-code} -A [migration recipe][11]{:.external} exists to accompany this guide. It starts -with an activity containing only Nav2 code. The end state of each migration step -is represented by another activity. Instrumented tests verify the navigation -behavior in every step. +A [migration recipe][10] exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. To use the migration recipe as a guide: -- Clone the [nav3-recipes repository][12]{:.external}, load it into Android - Studio and switch to the Android view in the project explorer +- Clone the [nav3-recipes repository][11], load it into Android Studio and switch to the Android view in the project explorer - Expand the `com.example.nav3recipes.migration` package -- Open `start.StartMigrationActivity`. Familiarise yourself with the navigation - structure and behavior defined in this activity. For simplicity, the recipe - codebase is not modularized, however, it is structured in a way that should - make it clear where the module boundaries would be in a real app. This is the - starting point for migration. -- Open `MigrationActivityNavigationTest` which is under the `androidTest` source - set. This file contains the instrumented tests that verify the navigation - behavior. +- Open `start.StartMigrationActivity`. Familiarise yourself with the navigation structure and behavior defined in this activity. For simplicity, the recipe codebase is not modularized, however, it is structured in a way that should make it clear where the module boundaries would be in a real app. This is the starting point for migration. +- Open `MigrationActivityNavigationTest` which is under the `androidTest` source set. This file contains the instrumented tests that verify the navigation behavior. - Run the tests. Note that the tests are run on every migration step activity. Tips for working with the migration recipe: -- It can be useful to see the differences between migration steps. To do this, - highlight both files in Android Studio project explorer then right click and - choose "Compare files". The first file to be selected is the one that will - appear in the left window pane. +- It can be useful to see the differences between migration steps. To do this, highlight both files in Android Studio project explorer then right click and choose "Compare files". The first file to be selected is the one that will appear in the left window pane. -
- INSERT ALT TEXT HERE -
Figure 2. INSERT CAPTION HERE
-
+![INSERT ALT TEXT HERE](INSERT FILE NAME HERE) -- To run the migration tests only on a single activity, uncomment the other - activities in the `data` function inside `MigrationActivityNavigationTest`. -- The migration steps introduce a `Navigator` class. Setting its - `shouldPrintDebugInfo` parameter to `true` will output lots of debug - information to Logcat. +- To run the migration tests only on a single activity, uncomment the other activities in the `data` function inside `MigrationActivityNavigationTest`. +- The migration steps introduce a `Navigator` class. Setting its `shouldPrintDebugInfo` parameter to `true` will output lots of debug information to Logcat. -## Step 1. Add the Nav3 dependencies {:#step-1.} +## Step 1. Add the Nav3 dependencies {#step-1.} -The latest dependencies can be found here: -[https://developer.android.com/guide/navigation/navigation-3/get-started][13] +The latest dependencies can be found here: [https://developer.android.com/guide/navigation/navigation-3/get-started][12] -- Update `lib.versions.toml` to include the Nav3 dependencies. Use the [latest - version from here][14]. +- Update `lib.versions.toml` to include the Nav3 dependencies. Use the [latest version from here][13]. ``` androidxNavigation3 = "1.0.0-alpha07" @@ -97,12 +61,10 @@ androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runt androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" } ``` -### 1.1 Create a common navigation module {:#1.1-create} +### 1.1 Create a common navigation module {#1.1-create} - If you don't have one already, create a :`core:navigation` module -- Add the Nav3 runtime as a dependency using - `api(libs.androidx.navigation3.runtime). This` allows modules depending on - :core:navigation `to` use the Nav3 runtime API. +- Add the Nav3 runtime as a dependency using `api(libs.androidx.navigation3.runtime). This` allows modules depending on :core:navigation `to` use the Nav3 runtime API. - Add the Nav2 dependencies. These will be removed once migration is complete. Example `build.gradle.kts`: @@ -114,45 +76,28 @@ dependencies { } ``` -**Note**: Nav3 has two libraries: `runtime` and `ui`. Usually only the `app` -module needs to depend on `navigation3.ui` which is why it isn't included in the -:`core:navigation` dependencies above. +**Note**: Nav3 has two libraries: `runtime` and `ui`. Usually only the `app` module needs to depend on `navigation3.ui` which is why it isn't included in the :`core:navigation` dependencies above. -### 1.2 Update main app module {:#1.2-update} +### 1.2 Update main app module {#1.2-update} -- Update the `app` module to depend on :`core:navigation` and on - `androidx.navigation3.ui` +- Update the `app` module to depend on :`core:navigation` and on `androidx.navigation3.ui` - Update compileSdk to 36 or above - Update minSdk to 23 or above - Update AGP to 8.9.3 or above -## Step 2. Create a back stack and use it with NavDisplay {:#step-2.} +## Step 2. Create a back stack and use it with NavDisplay {#step-2.} -### 2.1 Add the Navigator class {:#2.1-add} +### 2.1 Add the Navigator class {#2.1-add} -Important: A fundamental difference between Nav2 and Nav3 is that **you own the -back stack**. This means much of the logic and state that was previously managed -by Nav2, must now be managed by you. This gives you greater flexibility and -control, but also more responsibility. +Important: A fundamental difference between Nav2 and Nav3 is that **you own the back stack**. This means much of the logic and state that was previously managed by Nav2, must now be managed by you. This gives you greater flexibility and control, but also more responsibility. -To aid with migration, a class which provides and manages a back stack named -`Navigator` is provided for you. It is not part of the Nav3 library and it does -not provide all the features of Nav2. Instead it is intended to be an assistant -during migration, and after to be a starting point for you to implement your own -navigation behavior and logic. +To aid with migration, a class which provides and manages a back stack named `Navigator` is provided for you. It is not part of the Nav3 library and it does not provide all the features of Nav2. Instead it is intended to be an assistant during migration, and after to be a starting point for you to implement your own navigation behavior and logic. -Copy the [`Navigator`][15]{:.external} [class][15]{:.external} to the -:`core:navigation` module. This class contains `backStack: -SnapshotStateList` that can be used with `NavDisplay.It` will mirror -`NavController`'s back stack ensuring that Nav2's state remains the source of -truth throughout migration. After the migration is complete, the NavController -mirroring code will be removed. +Copy the [`Navigator`][14] [class][14] to the :`core:navigation` module. This class contains `backStack: SnapshotStateList` that can be used with `NavDisplay.It` will mirror `NavController`'s back stack ensuring that Nav2's state remains the source of truth throughout migration. After the migration is complete, the NavController mirroring code will be removed. -### 2.2 Make the Navigator available everywhere that NavController is -{:#2.2-make} +### 2.2 Make the Navigator available everywhere that NavController is {#2.2-make} -Goal: The `Navigator` class is available everywhere that `NavController` is -used. +Goal: The `Navigator` class is available everywhere that `NavController` is used. - Create the `Navigator` immediately after `NavController` is created @@ -164,18 +109,16 @@ val navigator = remember { Navigator(navController) } ``` - Do a project-wide search for "NavController" and "NavHostController" -- Update any classes or methods that accept a `NavController` or - `NavHostController` to also accept `Navigator` as a parameter +- Update any classes or methods that accept a `NavController` or `NavHostController` to also accept `Navigator` as a parameter -### 2.3 Wrap NavHost with NavDisplay {:#2.3-wrap} +### 2.3 Wrap NavHost with NavDisplay {#2.3-wrap} Goal: `NavDisplay` displays your existing `NavHost` using a fallback `NavEntry`. - Wrap `NavHost` with a `NavDisplay` - Pass your `Navigator`'s back stack to the `NavDisplay` - Set `NavDisplay.onBack` to call `navigator.goBack()` -- Create an `entryProvider` with a `fallback` lambda that always displays the - existing `NavHost` +- Create an `entryProvider` with a `fallback` lambda that always displays the existing `NavHost` Example: @@ -195,60 +138,44 @@ NavDisplay( ) ``` -## Step 3. [Single feature] Migrate routes {:#step-3.} +## Step 3. [Single feature] Migrate routes {#step-3.} -Goal: Routes are moved into their own :`feature:api` module and their properties -are modelled outside of `NavHost` +Goal: Routes are moved into their own :`feature:api` module and their properties are modelled outside of `NavHost` -### 3.1 Split feature module into api and impl {:#3.1-split} +### 3.1 Split feature module into api and impl {#3.1-split} -Choose **a single feature module** that does not contain the start destination -for your app. The feature module containing the start destination will be -migrated last. +Choose **a single feature module** that does not contain the start destination for your app. The feature module containing the start destination will be migrated last. Create the `api` module: - Create a new feature module named :`:api` - Move the routes into it -- Apply the KotlinX Serialization plugin to the module by updating the - `build.gradle.kts` +- Apply the KotlinX Serialization plugin to the module by updating the `build.gradle.kts` Update the :`core:navigation` module: -- Add a dependency on :`:api` - this allows `Navigator` to - access the feature's routes. It is not good practice for :`core` modules to - depend on :`feature` modules, however, this is necessary during migration. - This dependency will be removed once migration is complete. +- Add a dependency on :`:api` - this allows `Navigator` to access the feature's routes. It is not good practice for :`core` modules to depend on :`feature` modules, however, this is necessary during migration. This dependency will be removed once migration is complete. Create the `impl` module: -- Move the remaining contents of :`` into - :`:impl` +- Move the remaining contents of :`` into :`:impl` - Add the following dependencies: - - :`:api` so it has access to the routes - - :`core:navigation` so it has access to the Nav3 APIs and the `Navigator` - class + - :`:api` so it has access to the routes + - :`core:navigation` so it has access to the Nav3 APIs and the `Navigator` class Update :`app` dependencies: -- Update the :`app` module to depend on both :`:api` and - :`:impl`. +- Update the :`app` module to depend on both :`:api` and :`:impl`. -### 3.2 Model nested navigation graphs {:#3.2-model} +### 3.2 Model nested navigation graphs {#3.2-model} Skip this section if you don't use nested navigation graphs. #### 3.2.1 Nested graph migration overview -In Nav2, you can define nested navigation graphs using the `navigation` builder -function inside `NavHost. NavController` provides a back stack for each nested -graph. This allows you to have several top level destinations, each with -sub-destinations. You can also define shared destinations - ones that are -accessible from more than one navigation graph - by duplicating the destination -in multiple graphs. +In Nav2, you can define nested navigation graphs using the `navigation` builder function inside `NavHost. NavController` provides a back stack for each nested graph. This allows you to have several top level destinations, each with sub-destinations. You can also define shared destinations - ones that are accessible from more than one navigation graph - by duplicating the destination in multiple graphs. -For example, the following code defines two nested navigation graphs, each -containing a shared destination defined by `RouteE`. +For example, the following code defines two nested navigation graphs, each containing a shared destination defined by `RouteE`. ``` @Serializable private data object BaseRouteA @@ -273,12 +200,9 @@ NavHost(startDestination = BaseRouteA){ } ``` -In Nav3, how you model relationships between routes is up to you. In this -migration guide, `NavHost` will be removed so it's important that the properties -and relationships defined here are captured elsewhere. +In Nav3, how you model relationships between routes is up to you. In this migration guide, `NavHost` will be removed so it's important that the properties and relationships defined here are captured elsewhere. -One possible way of modelling these properties (though by no means the only -way), is to define marker interfaces for the top level and shared routes. +One possible way of modelling these properties (though by no means the only way), is to define marker interfaces for the top level and shared routes. ``` @Serializable private data object RouteA : Route.TopLevel @@ -293,30 +217,21 @@ sealed interface Route { } ``` -Once modelled, the nested navigation and shared destination behavior can be -implemented as follows inside a class that provides a back stack, such as the -provided `Navigator`. +Once modelled, the nested navigation and shared destination behavior can be implemented as follows inside a class that provides a back stack, such as the provided `Navigator`. ##### For nested navigation - Each top level route has its own back stack. -- The first element in that back stack is the top level route - this approach - means we no longer need the `BaseRoute` objects to identify each nested - navigation graph, the first element is sufficient. -- The current top level route is tracked and sub routes are added to its back - stack - there is no explicit definition of parent-child relationships between - routes -- When the top level route changes, other top level stacks can be retained or - discarded. -- The top level stacks can be flattened into a single list which is observed by - `NavDisplay`. +- The first element in that back stack is the top level route - this approach means we no longer need the `BaseRoute` objects to identify each nested navigation graph, the first element is sufficient. +- The current top level route is tracked and sub routes are added to its back stack - there is no explicit definition of parent-child relationships between routes +- When the top level route changes, other top level stacks can be retained or discarded. +- The top level stacks can be flattened into a single list which is observed by `NavDisplay`. ##### For shared routes -- When navigating to a route that implements `Route.Shared`, check whether it's - already on a top level stack: - - If so, move it to the current top level stack - - If not, add it to the current top level stack +- When navigating to a route that implements `Route.Shared`, check whether it's already on a top level stack: + - If so, move it to the current top level stack + - If not, add it to the current top level stack ##### Example @@ -324,59 +239,59 @@ Taking the code example from above. The starting route is A. - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + +

User action

Current top level route

Top level stacks

Back stack

User action

Current top level route

Top level stacks

Back stack

Notes

Open app

A

A => [A]

A

Open app

A

A => [A]

A

Tap on A1

A

A => [A, A1]

A, A1

Tap on A1

A

A => [A, A1]

A, A1

Tap on B

B

A => [A, A1]

B => [B]

A, A1, B

Tap on B

B

A => [A, A1]

B => [B]

A, A1, B

Tap on B1

B

A => [A, A1]

B => [B, B1]

A, A1, B, B1

Tap on B1

B

A => [A, A1]

B => [B, B1]

A, A1, B, B1

Tap on E

B

A => [A, A1]

B => [B, B1, E]

A, A1, B, B1, E

Tap on E

B

A => [A, A1]

B => [B, B1, E]

A, A1, B, B1, E

Tap on A

A

A => [A, A1]

A, A1

Tap on A

A

A => [A, A1]

A, A1

We make the decision to pop all B's routes from the stack, this is similar to using popUpTo(A) when navigating using Nav2

Tap on E

A

A => [A, A1, E]

A, A1, E

Tap on E

A

A => [A, A1, E]

A, A1, E
@@ -385,8 +300,8 @@ Taking the code example from above. The starting route is A. Review the provided `Navigator` class to ensure that it can model your app's current navigation behavior. In particular: -- Review the [`add`][16]{:.external} [method][16]{:.external} -- Note that `popUpTo` in the [`navigate`][17]{:.external} [method][17]{:.external} will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. +- Review the [`add`][15] [method][15] +- Note that `popUpTo` in the [`navigate`][16] [method][16] will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. #### 3.2.2 Update routes to implement marker interfaces @@ -395,11 +310,11 @@ Steps: - Update each top level route so that it implements the `Route.TopLevel` interface provided by `Navigator.kt` - Update each shared route so that it implements the `Route.Shared` interface provided by `Navigator.kt` -## Step 4. [Single feature] Move destinations from NavHost to entryProvider {:#step-4.} +## Step 4. [Single feature] Move destinations from NavHost to entryProvider {#step-4.} Goal: When navigating to a route, it is provided using `NavDisplay's entryProvider`. -### 4.1 Move composable content from NavHost into entryProvider {:#4.1-move} +### 4.1 Move composable content from NavHost into entryProvider {#4.1-move} Continue only with the feature module being migrated in the previous step. @@ -410,14 +325,14 @@ For each destination inside `NavHost`, do the following based the destination ty - `navigation` - do nothing - `composable` - Copy the function into `entryProvider` and rename `composable` to `entry`, retaining the type parameter. Remove the composable content from the old `composable` leaving it empty i.e., `composable`{}. - `dialog` - Same as composable but add metadata to the entry as follows: entry(metadata `= DialogSceneStrategy.dialog()`) - - If you haven't already, add `DialogSceneStrategy` to `NavDisplay's sceneStrategy` parameter. -- [`bottomSheet`][18] - [Follow the bottom sheet recipe here][19]{:.external}. This essentially the same as the instructions for `dialog` except that `BottomSheetSceneStrategy` is not part of the core Nav3 library and so should be copied/modified to your individual requirements. + - If you haven't already, add `DialogSceneStrategy` to `NavDisplay's sceneStrategy` parameter. +- [`bottomSheet`][17] - [Follow the bottom sheet recipe here][18]. This essentially the same as the instructions for `dialog` except that `BottomSheetSceneStrategy` is not part of the core Nav3 library and so should be copied/modified to your individual requirements. #### 4.1.2 Obtain navigation arguments In Nav2, when navigation arguments are passed using the route instance, you must first obtain the route instance from `NavBackStackEntry` by calling `toRoute`. In Nav3, the route instance is directly accessible with `entry`'s lambda parameter so there's no need to obtain the route instance. -If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels][20]{:.external} and apply the technique most appropriate to your codebase. +If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels][19] and apply the technique most appropriate to your codebase. #### 4.1.3 Code example @@ -426,9 +341,9 @@ Existing code: ``` NavHost(...){ navigation(startDestination = RouteB) { - composable{ entry -> + composable{ entry -> val id = entry.toRoute().id - Text("Route B, id: $id") + Text("Route B, id: $id") } dialog { Text ("Dialog D") } } @@ -445,7 +360,7 @@ NavHost(...){ } } -NavDisplay(..., +NavDisplay(..., sceneStrategy = remember { DialogSceneStrategy() }, entryProvider = entryProvider { entry{ route -> Text("Route B, id: ${route.id}") } @@ -456,19 +371,14 @@ NavDisplay(..., #### 4.2.1 Move NavGraphBuilder extension functions -[`NavGraphBuilder`][21] [extension functions][21] can be refactored to `EntryProviderBuilder` extension functions. These functions can then be called inside `entryProvider`. +[`NavGraphBuilder`][20] [extension functions][20] can be refactored to `EntryProviderBuilder` extension functions. These functions can then be called inside `entryProvider`. Refactoring `NavHost`: - Copy the function call into `entryProvider` - Inline the original function reference and keep the existing function -
- INSERT ALT TEXT HERE -
Figure 3. INSERT CAPTION HERE
-
+![INSERT ALT TEXT HERE](INSERT FILE NAME HERE) - Remove any composable content associated with the entries inside `NavHost`. Keeping blank entries for each route ensures that `NavController`'s back stack is still the source of truth for the navigation state. @@ -477,7 +387,7 @@ Refactoring the extension function: - Change the method signature from `NavGraphBuilder.existingScreen()` to `EntryProviderBuilder.existingScreen()`. - Remove `navigation` destinations, leaving only the destinations they contain. - Replace `composable` and `dialog` destinations with `entry` - - For `dialog` destinations add the dialog metadata following the instructions in the previous step + - For `dialog` destinations add the dialog metadata following the instructions in the previous step #### 4.2.2 Code example @@ -513,7 +423,7 @@ private fun EntryProviderBuilder.featureBSection() { } ``` -### 4.3 In Navigator, convert NavBackStackEntry back to its route instance {:#4.3-navigator,} +### 4.3 In Navigator, convert NavBackStackEntry back to its route instance {#4.3-navigator,} Steps: @@ -536,7 +446,7 @@ You should now be able to navigate to, and back from, the migrated destinations. **Note**: When navigating (both forward and back) between destinations handled by `NavHost` and `NavDisplay`, you may see the blank destination until the transition animation has completed. -## Step 5. [Single feature] Replace NavController with Navigator {:#step-5.} +## Step 5. [Single feature] Replace NavController with Navigator {#step-5.} Goal: Within the migrated feature module, navigation events are handled by `Navigator` instead of `NavController` @@ -559,7 +469,7 @@ Remove Nav2 imports and module dependencies: At this point, this feature module has been fully migrated to Nav3. -## Step 6. Migrate all feature modules {:#step-6.} +## Step 6. Migrate all feature modules {#step-6.} Goal: Feature modules use Nav3. They don't contain any Nav2 code. @@ -567,26 +477,26 @@ Complete steps 3-5 for each feature module. Start with the module with the least Ensure that shared entries are not duplicated. -## Step 7. Use Navigator.backStack as source of truth for navigation state {:#step-7.} +## Step 7. Use Navigator.backStack as source of truth for navigation state {#step-7.} -### 7.1 Ensure Navigator is used instead of NavController everywhere {:#7.1-ensure} +### 7.1 Ensure Navigator is used instead of NavController everywhere {#7.1-ensure} Replace any remaining instances of: - `NavController.navigate` with `Navigator.navigate` - `NavController.popBackStack` with `Navigator.goBack` -### 7.2 Update Navigator to modify its back stack directly {:#7.2-update} +### 7.2 Update Navigator to modify its back stack directly {#7.2-update} - Open `Navigator` - In `navigate` and `goBack`: - - Remove the code that calls `NavController` - - Uncomment the code that modifies the back stack directly + - Remove the code that calls `NavController` + - Uncomment the code that modifies the back stack directly - Remove all code which references `NavController` -The final `Navigator` [should look like this][22]{:.external}. +The final `Navigator` [should look like this][21]. -### 7.3 Set the app's start route {:#7.3-set} +### 7.3 Set the app's start route {#7.3-set} When creating the `Navigator` specify the starting route for your app. @@ -594,47 +504,46 @@ When creating the `Navigator` specify the starting route for your app. val navigator = remember { Navigator(navController, startRoute = RouteA) } ``` -### 7.4 Update common navigation UI components {:#7.4-update} +### 7.4 Update common navigation UI components {#7.4-update} -If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here][23]{:.external}. +If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here][22]. In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. `BaseRouteA` and `RouteA`). This is no longer necessary so remove any redundant types for the navigation graph from the :`api` modules. Ensure that the correct types are used to identify top level routes. -### 7.5 Remove the entryProvider fallback {:#7.5-remove} +### 7.5 Remove the entryProvider fallback {#7.5-remove} Remove the `fallback` parameter from `entryProvider` as there are no longer any unmigrated routes that must be handled by `NavHost`. -### 7.6. Remove unused dependencies {:#7.6.-remove} +### 7.6. Remove unused dependencies {#7.6.-remove} - Remove all remaining Nav2 dependencies from the project - In :`core:navigation` remove any dependencies on :`feature:api` modules Congratulations! Your project is now migrated to Navigation 3. -## Next steps {:#next-steps} +## Next steps {#next-steps} In the supplied `Navigator`, the type of items in the back stack is `Any`. You may now want to change this to use stronger types, for example the `NavKey` interface provided by Nav3. -[1]: http://goto.google.com/nav2to3 -[2]: https://developer.android.com/guide/navigation -[3]: https://developer.android.com/guide/navigation/navigation-3 -[4]: https://developer.android.com/topic/modularization -[5]: https://developer.android.com/guide/navigation/design/kotlin-dsl#custom -[6]: https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1) -[7]: https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657 -[8]: https://github.com/android/nowinandroid/pull/1413){:.external} -[9]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt -[10]: /guide/topics/manifest/uses-sdk-element#min -[11]: https://github.com/android/nav3-recipes/tree/dt/2to3migration -[12]: https://github.com/android/nav3-recipes -[13]: /guide/navigation/navigation-3/get-started -[14]: /jetpack/androidx/releases/navigation3 -[15]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt -[16]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142 -[17]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121 -[18]: /reference/kotlin/androidx/compose/material/navigation/package-summary#(androidx.navigation.NavGraphBuilder).bottomSheet(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2) -[19]: https://github.com/android/nav3-recipes/pull/67 -[20]: https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels -[21]: /guide/navigation/design/encapsulate -[22]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15 -[23]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94 +[1]: /guide/navigation +[2]: /guide/navigation/navigation-3 +[3]: /topic/modularization +[4]: /guide/navigation/design/kotlin-dsl#custom +[5]: /reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1) +[6]: https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657 +[7]: https://github.com/android/nowinandroid/pull/1413) +[8]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +[9]: /guide/topics/manifest/uses-sdk-element#min +[10]: https://github.com/android/nav3-recipes/tree/dt/2to3migration +[11]: https://github.com/android/nav3-recipes +[12]: /guide/navigation/navigation-3/get-started +[13]: /jetpack/androidx/releases/navigation3 +[14]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt +[15]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142 +[16]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121 +[17]: /reference/kotlin/androidx/compose/material/navigation/package-summary#(androidx.navigation.NavGraphBuilder).bottomSheet(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2) +[18]: https://github.com/android/nav3-recipes/pull/67 +[19]: https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels +[20]: /guide/navigation/design/encapsulate +[21]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15 +[22]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94 \ No newline at end of file From 7510ef3caa40b7e4af213e7acf9ec7a924a87061 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 11:10:58 +0100 Subject: [PATCH 52/64] Update guide --- docs/MigratingFromNavigation2.md | 707 +++++++++++++++++++------------ 1 file changed, 441 insertions(+), 266 deletions(-) diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index 10ed8a6..a2eff45 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -2,180 +2,256 @@ ## Overview {#overview} -This is intended to be a general guide to [Navigation 2][1] to [Navigation 3][2] migration which can be applied to any project. It attempts to keep the project in a working state during migration (build succeeds, navigation tests pass) and does this by maintaining interoperability between Nav2 and Nav3. +This is intended to be a general guide to [Navigation 2](https://developer.android.com/guide/navigation) to [Navigation 3](https://developer.android.com/guide/navigation/navigation-3) migration which can be applied to any project. It attempts to keep the project in a working state during migration (build succeeds, navigation tests pass) and does this by maintaining interoperability between Nav2 and Nav3. -The guide assumes that the project is [modularized][3], and the suggested approach allows feature modules to adopt Nav3 on an incremental basis. Once all feature modules have migrated, the Nav2 code can be safely removed. If the codebase is not modularized, the steps for specific modules should be applied to the main `app` module. +The guide assumes that the project is [modularized](https://developer.android.com/topic/modularization), and the suggested approach allows feature modules to adopt Nav3 on an incremental basis. Once all feature modules have migrated, the Nav2 code can be safely removed. If the codebase is not modularized, the steps for specific modules should be applied to the main `app` module. -### Features {#features} + +### Features This guide covers the migration of the following Nav2 features: -- Nested navigation graphs - single level of nesting only -- Shared destinations - ones that can appear in different navigation graphs -- Dialog destinations + + +* Nested navigation graphs - single level of nesting only +* Shared destinations - ones that can appear in different navigation graphs +* Dialog destinations The following features are not yet supported: -- More than one level of nested navigation -- [Custom destination types][4] -- Deeplinks -### Prerequisites {#prerequisites} -- Familiarity with [navigation terminology][1]. -- Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [`AndroidFragment`][5] for interoperability with Compose. -- Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes][6] first ([example][7]. -- Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests][8]. -- Your app must have a [minSdk][9] of 23 or above. +* More than one level of nested navigation +* [Custom destination types](https://developer.android.com/guide/navigation/design/kotlin-dsl#custom) +* Deeplinks + + +### Prerequisites + -## Step-by-step code examples {#step-by-step-code} -A [migration recipe][10] exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. +* Familiarity with [navigation terminology](https://developer.android.com/guide/navigation). +* Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [AndroidFragment](https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1)) for interoperability with Compose. +* Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657) first ([example](https://github.com/android/nowinandroid/pull/1413)). +* Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt). +* Your app must have a [minSdk](https://developer.android.com/guide/topics/manifest/uses-sdk-element#min) of 23 or above. + + +## Step-by-step code examples {#step-by-step-code-examples} + +A [migration recipe](https://github.com/android/nav3-recipes/tree/dt/2to3migration) exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. To use the migration recipe as a guide: -- Clone the [nav3-recipes repository][11], load it into Android Studio and switch to the Android view in the project explorer -- Expand the `com.example.nav3recipes.migration` package -- Open `start.StartMigrationActivity`. Familiarise yourself with the navigation structure and behavior defined in this activity. For simplicity, the recipe codebase is not modularized, however, it is structured in a way that should make it clear where the module boundaries would be in a real app. This is the starting point for migration. -- Open `MigrationActivityNavigationTest` which is under the `androidTest` source set. This file contains the instrumented tests that verify the navigation behavior. -- Run the tests. Note that the tests are run on every migration step activity. + + +* Clone the [nav3-recipes repository](https://github.com/android/nav3-recipes), load it into Android Studio and switch to the Android view in the project explorer +* Expand the `com.example.nav3recipes.migration` package +* Open `start.StartMigrationActivity`. Familiarise yourself with the navigation structure and behavior defined in this activity. For simplicity, the recipe codebase is not modularized, however, it is structured in a way that should make it clear where the module boundaries would be in a real app. This is the starting point for migration. + + + +

>>>>> gd2md-html alert: inline image link here (to images/image1.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

+ + +![alt_text](images/image1.png "image_tooltip") + + + + +* Open `MigrationActivityNavigationTest` which is under the `androidTest` source set. This file contains the instrumented tests that verify the navigation behavior. +* Run the tests. Note that the tests are run on every migration step activity. Tips for working with the migration recipe: -- It can be useful to see the differences between migration steps. To do this, highlight both files in Android Studio project explorer then right click and choose "Compare files". The first file to be selected is the one that will appear in the left window pane. -![INSERT ALT TEXT HERE](INSERT FILE NAME HERE) -- To run the migration tests only on a single activity, uncomment the other activities in the `data` function inside `MigrationActivityNavigationTest`. -- The migration steps introduce a `Navigator` class. Setting its `shouldPrintDebugInfo` parameter to `true` will output lots of debug information to Logcat. +* It can be useful to see the differences between migration steps. To do this, highlight both files in Android Studio project explorer then right click and choose "Compare files". The first file to be selected is the one that will appear in the left window pane. -## Step 1. Add the Nav3 dependencies {#step-1.} -The latest dependencies can be found here: [https://developer.android.com/guide/navigation/navigation-3/get-started][12] -- Update `lib.versions.toml` to include the Nav3 dependencies. Use the [latest version from here][13]. +

>>>>> gd2md-html alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

-``` + +![alt_text](images/image2.png "image_tooltip") + + + + +* To run the migration tests only on a single activity, uncomment the other activities in the `data` function inside `MigrationActivityNavigationTest`. +* The migration steps introduce a `Navigator` class. Setting its `shouldPrintDebugInfo` parameter to `true` will output lots of debug information to Logcat. + + +## Step 1. Add the Nav3 dependencies {#step-1-add-the-nav3-dependencies} + +The latest dependencies can be found here: [https://developer.android.com/guide/navigation/navigation-3/get-started](https://developer.android.com/guide/navigation/navigation-3/get-started) + + + +* Update `lib.versions.toml` to include the Nav3 dependencies. Use the [latest version from here](https://developer.android.com/jetpack/androidx/releases/navigation3). + + ``` androidxNavigation3 = "1.0.0-alpha07" androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "androidxNavigation3" } androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" } ``` -### 1.1 Create a common navigation module {#1.1-create} -- If you don't have one already, create a :`core:navigation` module -- Add the Nav3 runtime as a dependency using `api(libs.androidx.navigation3.runtime). This` allows modules depending on :core:navigation `to` use the Nav3 runtime API. -- Add the Nav2 dependencies. These will be removed once migration is complete. -Example `build.gradle.kts`: + +### 1.1 Create a common navigation module + + + +* If you don't have one already, create a `:core:navigation` module +* Add the Nav3 runtime as a dependency using ` api(libs.androidx.navigation3.runtime)`. This allows modules depending on `:core:navigation` to use the Nav3 runtime API. +* Add the Nav2 dependencies. These will be removed once migration is complete. + +Example `build.gradle.kts`: + ``` dependencies { - api(libs.androidx.navigation3.runtime) - implementation(libs.androidx.navigation2) +api(libs.androidx.navigation3.runtime) +implementation(libs.androidx.navigation2) } ``` -**Note**: Nav3 has two libraries: `runtime` and `ui`. Usually only the `app` module needs to depend on `navigation3.ui` which is why it isn't included in the :`core:navigation` dependencies above. -### 1.2 Update main app module {#1.2-update} +**Note:** Nav3 has two libraries: `runtime` and `ui`. Usually only the `app` module needs to depend on `navigation3.ui` which is why it isn't included in the `:core:navigation` dependencies above. -- Update the `app` module to depend on :`core:navigation` and on `androidx.navigation3.ui` -- Update compileSdk to 36 or above -- Update minSdk to 23 or above -- Update AGP to 8.9.3 or above -## Step 2. Create a back stack and use it with NavDisplay {#step-2.} +### 1.2 Update main app module -### 2.1 Add the Navigator class {#2.1-add} -Important: A fundamental difference between Nav2 and Nav3 is that **you own the back stack**. This means much of the logic and state that was previously managed by Nav2, must now be managed by you. This gives you greater flexibility and control, but also more responsibility. -To aid with migration, a class which provides and manages a back stack named `Navigator` is provided for you. It is not part of the Nav3 library and it does not provide all the features of Nav2. Instead it is intended to be an assistant during migration, and after to be a starting point for you to implement your own navigation behavior and logic. +* Update the `app` module to depend on `:core:navigation `and on `androidx.navigation3.ui` +* Update compileSdk to 36 or above +* Update minSdk to 23 or above +* Update AGP to 8.9.3 or above -Copy the [`Navigator`][14] [class][14] to the :`core:navigation` module. This class contains `backStack: SnapshotStateList` that can be used with `NavDisplay.It` will mirror `NavController`'s back stack ensuring that Nav2's state remains the source of truth throughout migration. After the migration is complete, the NavController mirroring code will be removed. -### 2.2 Make the Navigator available everywhere that NavController is {#2.2-make} +## Step 2. Create a back stack and use it with `NavDisplay` {#step-2-create-a-back-stack-and-use-it-with-navdisplay} -Goal: The `Navigator` class is available everywhere that `NavController` is used. -- Create the `Navigator` immediately after `NavController` is created +### 2.1 Add the `Navigator` class + + +``` +Important: A fundamental difference between Nav2 and Nav3 is that you own the back stack. This means much of the logic and state that was previously managed by Nav2, must now be managed by you. This gives you greater flexibility and control, but also more responsibility. + +To aid with migration, a class which provides and manages a back stack named Navigator is provided for you. It is not part of the Nav3 library and it does not provide all the features of Nav2. Instead it is intended to be an assistant during migration, and after to be a starting point for you to implement your own navigation behavior and logic. +``` + + +Copy the [Navigator class](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt) to the `:core:navigation` module. This class contains `backStack: SnapshotStateList<Any>` that can be used with `NavDisplay.`It will mirror `NavController`'s back stack ensuring that Nav2's state remains the source of truth throughout migration. After the migration is complete, the `NavController` mirroring code will be removed. + + +### 2.2 Make the `Navigator` available everywhere that `NavController` is + +Goal: The `Navigator` class is available everywhere that `NavController` is used. + + + +* Create the `Navigator` immediately after `NavController` is created Example: + ``` val navController = rememberNavController() val navigator = remember { Navigator(navController) } ``` -- Do a project-wide search for "NavController" and "NavHostController" -- Update any classes or methods that accept a `NavController` or `NavHostController` to also accept `Navigator` as a parameter -### 2.3 Wrap NavHost with NavDisplay {#2.3-wrap} -Goal: `NavDisplay` displays your existing `NavHost` using a fallback `NavEntry`. -- Wrap `NavHost` with a `NavDisplay` -- Pass your `Navigator`'s back stack to the `NavDisplay` -- Set `NavDisplay.onBack` to call `navigator.goBack()` -- Create an `entryProvider` with a `fallback` lambda that always displays the existing `NavHost` +* Do a project-wide search for "NavController" and "NavHostController" +* Update any classes or methods that accept a `NavController` or `NavHostController` to also accept `Navigator` as a parameter + + +### 2.3 Wrap `NavHost` with `NavDisplay` + +Goal: `NavDisplay` displays your existing `NavHost` using a fallback `NavEntry`. + + + +* Wrap `NavHost` with a `NavDisplay` +* Pass your `Navigator`'s back stack to the `NavDisplay` +* Set `NavDisplay.onBack` to call `navigator.goBack()` +* Create an `entryProvider` with a `fallback` lambda that always displays the existing `NavHost` + +Example: -Example: ``` NavDisplay( - backStack = navigator.backStack, - onBack = { navigator.goBack() }, - entryProvider = entryProvider( - fallback = { key -> - NavEntry(key = key) { - NavHost(...) - } - }, - ) { - // No Nav3 entries yet - }, +backStack = navigator.backStack, +onBack = { navigator.goBack() }, +entryProvider = entryProvider( +fallback = { key -> +NavEntry(key = key) { +NavHost(...) +} +}, +) { +// No Nav3 entries yet +}, ) ``` -## Step 3. [Single feature] Migrate routes {#step-3.} -Goal: Routes are moved into their own :`feature:api` module and their properties are modelled outside of `NavHost` -### 3.1 Split feature module into api and impl {#3.1-split} +## Step 3. [Single feature] Migrate routes {#step-3-[single-feature]-migrate-routes} + +Goal: Routes are moved into their own `:feature:api` module and their properties are modelled outside of `NavHost` + -Choose **a single feature module** that does not contain the start destination for your app. The feature module containing the start destination will be migrated last. +### 3.1 Split feature module into `api` and `impl` + +Choose **a single feature module** that does not contain the start destination for your app. The feature module containing the start destination will be migrated last. Create the `api` module: -- Create a new feature module named :`:api` -- Move the routes into it -- Apply the KotlinX Serialization plugin to the module by updating the `build.gradle.kts` -Update the :`core:navigation` module: -- Add a dependency on :`:api` - this allows `Navigator` to access the feature's routes. It is not good practice for :`core` modules to depend on :`feature` modules, however, this is necessary during migration. This dependency will be removed once migration is complete. +* Create a new feature module named `:<existingfeaturename>:api` +* Move the routes into it +* Apply the KotlinX Serialization plugin to the module by updating the `build.gradle.kts` + +Update the `:core:navigation` module: + + + +* Add a dependency on `:<existingfeaturename>:api` - this allows `Navigator` to access the feature's routes. It is not good practice for `:core` modules to depend on `:feature` modules, however, this is necessary during migration. This dependency will be removed once migration is complete. Create the `impl` module: -- Move the remaining contents of :`` into :`:impl` -- Add the following dependencies: - - :`:api` so it has access to the routes - - :`core:navigation` so it has access to the Nav3 APIs and the `Navigator` class -Update :`app` dependencies: -- Update the :`app` module to depend on both :`:api` and :`:impl`. +* Move the remaining contents of `:<existingfeaturename>` into `:<existingfeaturename>:impl` +* Add the following dependencies: + * `:<existingfeaturename>:api` so it has access to the routes + * `:core:navigation` so it has access to the Nav3 APIs and the `Navigator` class + +Update `:app` dependencies: + -### 3.2 Model nested navigation graphs {#3.2-model} -Skip this section if you don't use nested navigation graphs. +* Update the `:app` module to depend on both `:<existingfeaturename>:api` and `:<existingfeaturename>:impl`. + + +### 3.2 Model nested navigation graphs + +Skip this section if you don't use nested navigation graphs. + #### 3.2.1 Nested graph migration overview -In Nav2, you can define nested navigation graphs using the `navigation` builder function inside `NavHost. NavController` provides a back stack for each nested graph. This allows you to have several top level destinations, each with sub-destinations. You can also define shared destinations - ones that are accessible from more than one navigation graph - by duplicating the destination in multiple graphs. +In Nav2, you can define nested navigation graphs using the `navigation` builder function inside `NavHost`. `NavController` provides a back stack for each nested graph. This allows you to have several top level destinations, each with sub-destinations. You can also define shared destinations - ones that are accessible from more than one navigation graph - by duplicating the destination in multiple graphs. + +For example, the following code defines two nested navigation graphs, each containing a shared destination defined by `RouteE`. -For example, the following code defines two nested navigation graphs, each containing a shared destination defined by `RouteE`. ``` @Serializable private data object BaseRouteA @@ -187,22 +263,24 @@ For example, the following code defines two nested navigation graphs, each conta @Serializable private data object RouteE NavHost(startDestination = BaseRouteA){ - navigation(startDestination = RouteA) { - composable { ContentRed("Route A title") } - composable { ContentRed("Route A1 title") } - composable { SharedScreen() } - } - navigation(startDestination = RouteB) { - composable { ContentRed("Route B title") } - composable { ContentRed("Route B1 title") } - composable { SharedScreen() } - } +navigation(startDestination = RouteA) { +composable { ContentRed("Route A title") } +composable { ContentRed("Route A1 title") } +composable { SharedScreen() } +} +navigation(startDestination = RouteB) { +composable { ContentRed("Route B title") } +composable { ContentRed("Route B1 title") } +composable { SharedScreen() } +} } ``` -In Nav3, how you model relationships between routes is up to you. In this migration guide, `NavHost` will be removed so it's important that the properties and relationships defined here are captured elsewhere. -One possible way of modelling these properties (though by no means the only way), is to define marker interfaces for the top level and shared routes. +In Nav3, how you model relationships between routes is up to you. In this migration guide, `NavHost` will be removed so it's important that the properties and relationships defined here are captured elsewhere. + +One possible way of modelling these properties (though by no means the only way), is to define marker interfaces for the top level and shared routes. + ``` @Serializable private data object RouteA : Route.TopLevel @@ -212,225 +290,319 @@ One possible way of modelling these properties (though by no means the only way) @Serializable private data object RouteE : Route.Shared sealed interface Route { - interface TopLevel : Route - interface Shared : Route +interface TopLevel : Route +interface Shared : Route } ``` -Once modelled, the nested navigation and shared destination behavior can be implemented as follows inside a class that provides a back stack, such as the provided `Navigator`. + +Once modelled, the nested navigation and shared destination behavior can be implemented as follows inside a class that provides a back stack, such as the provided `Navigator`. + ##### For nested navigation -- Each top level route has its own back stack. -- The first element in that back stack is the top level route - this approach means we no longer need the `BaseRoute` objects to identify each nested navigation graph, the first element is sufficient. -- The current top level route is tracked and sub routes are added to its back stack - there is no explicit definition of parent-child relationships between routes -- When the top level route changes, other top level stacks can be retained or discarded. -- The top level stacks can be flattened into a single list which is observed by `NavDisplay`. + + +* Each top level route has its own back stack. +* The first element in that back stack is the top level route - this approach means we no longer need the `BaseRoute` objects to identify each nested navigation graph, the first element is sufficient. +* The current top level route is tracked and sub routes are added to its back stack - there is no explicit definition of parent-child relationships between routes +* When the top level route changes, other top level stacks can be retained or discarded. +* The top level stacks can be flattened into a single list which is observed by `NavDisplay`. + ##### For shared routes -- When navigating to a route that implements `Route.Shared`, check whether it's already on a top level stack: - - If so, move it to the current top level stack - - If not, add it to the current top level stack + + +* When navigating to a route that implements `Route.Shared`, check whether it's already on a top level stack: + * If so, move it to the current top level stack + * If not, add it to the current top level stack + ##### Example -Taking the code example from above. The starting route is A. +Taking the code example from above. The starting route is A. + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + +

User action

Current top level route

Top level stacks

Back stack

Notes

User action + Current top level route + Top level stacks + Back stack + Notes +

Open app

A

A => [A]

A

Open app + A + A => [A] + A + +

Tap on A1

A

A => [A, A1]

A, A1

Tap on A1 + A + A => [A, A1] + A, A1 + +

Tap on B

B

A => [A, A1]

B => [B]

A, A1, B

Tap on B + B + A => [A, A1] +

+B => [B] +

A, A1, B + +

Tap on B1

B

A => [A, A1]

B => [B, B1]

A, A1, B, B1

Tap on B1 + B + A => [A, A1] +

+B => [B, B1] +

A, A1, B, B1 + +

Tap on E

B

A => [A, A1]

B => [B, B1, E]

A, A1, B, B1, E

Tap on E + B + A => [A, A1] +

+B => [B, B1, E] +

A, A1, B, B1, E + +

Tap on A

A

A => [A, A1]

A, A1

We make the decision to pop all B's routes from the stack, this is similar to using popUpTo(A) when navigating using Nav2

Tap on A + A + A => [A, A1] + A, A1 + We make the decision to pop all B's routes from the stack, this is similar to using popUpTo(A) when navigating using Nav2 +

Tap on E

A

A => [A, A1, E]

A, A1, E

Tap on E + A + A => [A, A1, E] + A, A1, E + +
+ + ##### Steps -Review the provided `Navigator` class to ensure that it can model your app's current navigation behavior. In particular: +Review the provided `Navigator` class to ensure that it can model your app's current navigation behavior. In particular: + + + +* Review the [add method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142) +* Note that popUpTo in the [navigate method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121) will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. -- Review the [`add`][15] [method][15] -- Note that `popUpTo` in the [`navigate`][16] [method][16] will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. #### 3.2.2 Update routes to implement marker interfaces Steps: -- Update each top level route so that it implements the `Route.TopLevel` interface provided by `Navigator.kt` -- Update each shared route so that it implements the `Route.Shared` interface provided by `Navigator.kt` -## Step 4. [Single feature] Move destinations from NavHost to entryProvider {#step-4.} -Goal: When navigating to a route, it is provided using `NavDisplay's entryProvider`. +* Update each top level route so that it implements the `Route.TopLevel` interface provided by `Navigator.kt` +* Update each shared route so that it implements the `Route.Shared` interface provided by `Navigator.kt` + + +## Step 4. [Single feature] Move destinations from `NavHost` to `entryProvider` {#step-4-[single-feature]-move-destinations-from-navhost-to-entryprovider} -### 4.1 Move composable content from NavHost into entryProvider {#4.1-move} +Goal: When navigating to a route, it is provided using `NavDisplay`'s `entryProvider`. -Continue only with the feature module being migrated in the previous step. -#### 4.1.1 Move directly defined destinations, such as composable +### 4.1 Move composable content from `NavHost` into `entryProvider` + +Continue only with the feature module being migrated in the previous step. + + +#### 4.1.1 Move directly defined destinations, such as `composable` For each destination inside `NavHost`, do the following based the destination type: -- `navigation` - do nothing -- `composable` - Copy the function into `entryProvider` and rename `composable` to `entry`, retaining the type parameter. Remove the composable content from the old `composable` leaving it empty i.e., `composable`{}. -- `dialog` - Same as composable but add metadata to the entry as follows: entry(metadata `= DialogSceneStrategy.dialog()`) - - If you haven't already, add `DialogSceneStrategy` to `NavDisplay's sceneStrategy` parameter. -- [`bottomSheet`][17] - [Follow the bottom sheet recipe here][18]. This essentially the same as the instructions for `dialog` except that `BottomSheetSceneStrategy` is not part of the core Nav3 library and so should be copied/modified to your individual requirements. + + +* `navigation` - do nothing +* `composable<T>` - Copy the function into `entryProvider` and rename `composable` to `entry`, retaining the type parameter. Remove the composable content from the old `composable<T>` leaving it empty i.e., `composable<T>{}`. +* `dialog<T>` - Same as `composable` but add metadata to the `entry` as follows: `entry<T>(metadata = DialogSceneStrategy.dialog())` + * If you haven't already, add `DialogSceneStrategy` to `NavDisplay`'s `sceneStrategy` parameter. +* [bottomSheet](https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/package-summary#(androidx.navigation.NavGraphBuilder).bottomSheet(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2)) - [Follow the bottom sheet recipe here](https://github.com/android/nav3-recipes/pull/67). This essentially the same as the instructions for `dialog` except that `BottomSheetSceneStrategy` is not part of the core Nav3 library and so should be copied/modified to your individual requirements. + #### 4.1.2 Obtain navigation arguments -In Nav2, when navigation arguments are passed using the route instance, you must first obtain the route instance from `NavBackStackEntry` by calling `toRoute`. In Nav3, the route instance is directly accessible with `entry`'s lambda parameter so there's no need to obtain the route instance. +In Nav2, when navigation arguments are passed using the route instance, you must first obtain the route instance from `NavBackStackEntry` by calling `toRoute`. In Nav3, the route instance is directly accessible with `entry`'s lambda parameter so there's no need to obtain the route instance. + +If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels](https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels) and apply the technique most appropriate to your codebase. -If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels][19] and apply the technique most appropriate to your codebase. #### 4.1.3 Code example Existing code: + ``` NavHost(...){ - navigation(startDestination = RouteB) { - composable{ entry -> - val id = entry.toRoute().id - Text("Route B, id: $id") - } - dialog { Text ("Dialog D") } - } +navigation(startDestination = RouteB) { +composable{ entry -> +val id = entry.toRoute().id +Text("Route B, id: $id") +} +dialog { Text ("Dialog D") } +} } ``` + New code: + ``` NavHost(...){ - navigation(startDestination = RouteB) { - composable{} - dialog {} - } +navigation(startDestination = RouteB) { +composable{} +dialog {} +} } -NavDisplay(..., - sceneStrategy = remember { DialogSceneStrategy() }, - entryProvider = entryProvider { - entry{ route -> Text("Route B, id: ${route.id}") } - entry(metadata = DialogSceneStrategy.dialog()) { Text ("Dialog D") } - } +NavDisplay(..., +sceneStrategy = remember { DialogSceneStrategy() }, +entryProvider = entryProvider { +entry{ route -> Text("Route B, id: ${route.id}") } +entry(metadata = DialogSceneStrategy.dialog()) { Text ("Dialog D") } +} ) ``` -#### 4.2.1 Move NavGraphBuilder extension functions -[`NavGraphBuilder`][20] [extension functions][20] can be refactored to `EntryProviderBuilder` extension functions. These functions can then be called inside `entryProvider`. -Refactoring `NavHost`: +#### 4.2.1 Move `NavGraphBuilder` extension functions + +[NavGraphBuilder extension functions](https://developer.android.com/guide/navigation/design/encapsulate) can be refactored to `EntryProviderBuilder` extension functions. These functions can then be called inside `entryProvider`. + +Refactoring `NavHost`: + + + +* Copy the function call into `entryProvider` +* Inline the original function reference and keep the existing function + + + +

>>>>> gd2md-html alert: inline image link here (to images/image3.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

+ + +![alt_text](images/image3.png "image_tooltip") + -- Copy the function call into `entryProvider` -- Inline the original function reference and keep the existing function -![INSERT ALT TEXT HERE](INSERT FILE NAME HERE) -- Remove any composable content associated with the entries inside `NavHost`. Keeping blank entries for each route ensures that `NavController`'s back stack is still the source of truth for the navigation state. +* Remove any composable content associated with the entries inside `NavHost`. Keeping blank entries for each route ensures that `NavController`'s back stack is still the source of truth for the navigation state. -Refactoring the extension function: +Refactoring the extension function: + + + +* Change the method signature from `NavGraphBuilder.existingScreen()` to `EntryProviderBuilder<Any>.existingScreen()`. +* Remove `navigation` destinations, leaving only the destinations they contain. +* Replace `composable` and `dialog` destinations with `entry` + * For `dialog` destinations add the dialog metadata following the instructions in the previous step -- Change the method signature from `NavGraphBuilder.existingScreen()` to `EntryProviderBuilder.existingScreen()`. -- Remove `navigation` destinations, leaving only the destinations they contain. -- Replace `composable` and `dialog` destinations with `entry` - - For `dialog` destinations add the dialog metadata following the instructions in the previous step #### 4.2.2 Code example Existing code: + ``` NavHost(...) { - featureBSection() +featureBSection() } private fun NavGraphBuilder.featureBSection(onDetailClick: () -> Unit) { - navigation(startDestination = RouteB) { - composable { ContentRed("Route B title") } - } +navigation(startDestination = RouteB) { +composable { ContentRed("Route B title") } +} } ``` + New code: + ``` NavHost(...) { - navigation(startDestination = RouteB) { - composable { } - } +navigation(startDestination = RouteB) { +composable { } +} } NavDisplay(..., entryProvider = entryProvider { - featureBSection() +featureBSection() }) private fun EntryProviderBuilder.featureBSection() { - entry { ContentRed("Route B title") } +entry { ContentRed("Route B title") } } ``` -### 4.3 In Navigator, convert NavBackStackEntry back to its route instance {#4.3-navigator,} -Steps: -- Locate the line starting `val route` in `Navigator`. -- Add an `if` branch for each migrated route that converts the `NavBackStackEntry` into a route instance using `NavBackStackEntry.toRoute`. For example: +### 4.3 In `Navigator`, convert `NavBackStackEntry` back to its route instance -``` +Steps: + + + +* Locate the line starting `val route` in `Navigator`. +* Add an `if` branch for each migrated route that converts the `NavBackStackEntry` into a route instance using `NavBackStackEntry.toRoute<MigratedRouteType>`. For example: + + ``` val route = if (destination.hasRoute()) { entry.toRoute() @@ -442,34 +614,44 @@ val route = } ``` + + You should now be able to navigate to, and back from, the migrated destinations. These destinations will be displayed directly inside `NavDisplay` rather than by `NavHost`. -**Note**: When navigating (both forward and back) between destinations handled by `NavHost` and `NavDisplay`, you may see the blank destination until the transition animation has completed. +**Note:** When navigating (both forward and back) between destinations handled by `NavHost` and `NavDisplay`, you may see the blank destination until the transition animation has completed. + -## Step 5. [Single feature] Replace NavController with Navigator {#step-5.} +## Step 5. [Single feature] Replace `NavController` with `Navigator` {#step-5-[single-feature]-replace-navcontroller-with-navigator} Goal: Within the migrated feature module, navigation events are handled by `Navigator` instead of `NavController` Steps: -- Replace `NavController.popBackStack` with `Navigator.goBack` -- Replace `NavController.navigate` with Navigator.navigate + + +* Replace `NavController.popBackStack` with `Navigator.goBack` +* Replace `NavController.navigate` with `Navigator.navigate` TODO: Add warning about `navOptions` - you'll need to modify `Navigator` behavior if you don't like what it does For `NavController` extension functions defined by **other modules**: -- Inline the function, leaving the other module's function in place -- Make the replacements above + + +* Inline the function, leaving the other module's function in place +* Make the replacements above Remove Nav2 imports and module dependencies: -- Remove all imports starting with `import androidx.navigation` -- Remove feature module dependencies on `androidx.navigation` + + +* Remove all imports starting with `import androidx.navigation` +* Remove feature module dependencies on `androidx.navigation` At this point, this feature module has been fully migrated to Nav3. -## Step 6. Migrate all feature modules {#step-6.} + +## Step 6. Migrate all feature modules {#step-6-migrate-all-feature-modules} Goal: Feature modules use Nav3. They don't contain any Nav2 code. @@ -477,73 +659,66 @@ Complete steps 3-5 for each feature module. Start with the module with the least Ensure that shared entries are not duplicated. -## Step 7. Use Navigator.backStack as source of truth for navigation state {#step-7.} -### 7.1 Ensure Navigator is used instead of NavController everywhere {#7.1-ensure} +## Step 7. Use `Navigator.backStack` as source of truth for navigation state {#step-7-use-navigator-backstack-as-source-of-truth-for-navigation-state} + + +### 7.1 Ensure `Navigator` is used instead of `NavController` everywhere Replace any remaining instances of: -- `NavController.navigate` with `Navigator.navigate` -- `NavController.popBackStack` with `Navigator.goBack` -### 7.2 Update Navigator to modify its back stack directly {#7.2-update} -- Open `Navigator` -- In `navigate` and `goBack`: - - Remove the code that calls `NavController` - - Uncomment the code that modifies the back stack directly -- Remove all code which references `NavController` +* `NavController.navigate` with `Navigator.navigate` +* `NavController.popBackStack` with `Navigator.goBack` + + +### 7.2 Update `Navigator` to modify its back stack directly + + -The final `Navigator` [should look like this][21]. +* Open `Navigator` +* In `navigate` and `goBack`: + * Remove the code that calls `NavController` + * Uncomment the code that modifies the back stack directly +* Remove all code which references `NavController` -### 7.3 Set the app's start route {#7.3-set} +The final `Navigator` [should look like this](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15). + + +### 7.3 Set the app's start route When creating the `Navigator` specify the starting route for your app. + ``` val navigator = remember { Navigator(navController, startRoute = RouteA) } ``` -### 7.4 Update common navigation UI components {#7.4-update} -If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here][22]. -In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. `BaseRouteA` and `RouteA`). This is no longer necessary so remove any redundant types for the navigation graph from the :`api` modules. Ensure that the correct types are used to identify top level routes. +### 7.4 Update common navigation UI components + +If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94). + +In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. `BaseRouteA` and `RouteA`). This is no longer necessary so remove any redundant types for the navigation graph from the `:api` modules. Ensure that the correct types are used to identify top level routes. -### 7.5 Remove the entryProvider fallback {#7.5-remove} + +### 7.5 Remove the `entryProvider` fallback Remove the `fallback` parameter from `entryProvider` as there are no longer any unmigrated routes that must be handled by `NavHost`. -### 7.6. Remove unused dependencies {#7.6.-remove} -- Remove all remaining Nav2 dependencies from the project -- In :`core:navigation` remove any dependencies on :`feature:api` modules +### 7.6. Remove unused dependencies + + + +* Remove all remaining Nav2 dependencies from the project +* In `:core:navigation` remove any dependencies on `:feature:api` modules Congratulations! Your project is now migrated to Navigation 3. + ## Next steps {#next-steps} -In the supplied `Navigator`, the type of items in the back stack is `Any`. You may now want to change this to use stronger types, for example the `NavKey` interface provided by Nav3. - -[1]: /guide/navigation -[2]: /guide/navigation/navigation-3 -[3]: /topic/modularization -[4]: /guide/navigation/design/kotlin-dsl#custom -[5]: /reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1) -[6]: https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657 -[7]: https://github.com/android/nowinandroid/pull/1413) -[8]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt -[9]: /guide/topics/manifest/uses-sdk-element#min -[10]: https://github.com/android/nav3-recipes/tree/dt/2to3migration -[11]: https://github.com/android/nav3-recipes -[12]: /guide/navigation/navigation-3/get-started -[13]: /jetpack/androidx/releases/navigation3 -[14]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt -[15]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142 -[16]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121 -[17]: /reference/kotlin/androidx/compose/material/navigation/package-summary#(androidx.navigation.NavGraphBuilder).bottomSheet(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2) -[18]: https://github.com/android/nav3-recipes/pull/67 -[19]: https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels -[20]: /guide/navigation/design/encapsulate -[21]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15 -[22]: https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94 \ No newline at end of file +In the supplied `Navigator`, the type of items in the back stack is `Any`. You may now want to change this to use stronger types, for example the `NavKey` interface provided by Nav3. From a8da9c41c75903b4250d2b4d84ccae4c28fc65aa Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 11:16:21 +0100 Subject: [PATCH 53/64] Update guide --- docs/MigratingFromNavigation2.md | 697 ++++++++++--------------------- 1 file changed, 223 insertions(+), 474 deletions(-) diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index a2eff45..2ec9181 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -1,724 +1,473 @@ # Navigation 2 to 3 migration guide -## Overview {#overview} +## Overview -This is intended to be a general guide to [Navigation 2](https://developer.android.com/guide/navigation) to [Navigation 3](https://developer.android.com/guide/navigation/navigation-3) migration which can be applied to any project. It attempts to keep the project in a working state during migration (build succeeds, navigation tests pass) and does this by maintaining interoperability between Nav2 and Nav3. +This is intended to be a general guide to [Navigation 2](https://developer.android.com/guide/navigation) to [Navigation 3](https://developer.android.com/guide/navigation/navigation-3) migration which can be applied to any project. It attempts to keep the project in a working state during migration (build succeeds, navigation tests pass) and does this by maintaining interoperability between Nav2 and Nav3.  -The guide assumes that the project is [modularized](https://developer.android.com/topic/modularization), and the suggested approach allows feature modules to adopt Nav3 on an incremental basis. Once all feature modules have migrated, the Nav2 code can be safely removed. If the codebase is not modularized, the steps for specific modules should be applied to the main `app` module. +The guide assumes that the project is [modularized](https://developer.android.com/topic/modularization), and the suggested approach allows feature modules to adopt Nav3 on an incremental basis. Once all feature modules have migrated, the Nav2 code can be safely removed. If the codebase is not modularized, the steps for specific modules should be applied to the main app module.   -### Features +## Features This guide covers the migration of the following Nav2 features: +- Nested navigation graphs - single level of nesting only +- Shared destinations - ones that can appear in different navigation graphs  -* Nested navigation graphs - single level of nesting only -* Shared destinations - ones that can appear in different navigation graphs -* Dialog destinations +- Dialog destinations The following features are not yet supported: +- More than one level of nested navigation +- [Custom destination types](https://developer.android.com/guide/navigation/design/kotlin-dsl#custom) -* More than one level of nested navigation -* [Custom destination types](https://developer.android.com/guide/navigation/design/kotlin-dsl#custom) -* Deeplinks +- Deeplinks -### Prerequisites +## Prerequisites +- Familiarity with [navigation terminology](https://developer.android.com/guide/navigation). +- Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [AndroidFragment](https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment\(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1\)) for interoperability with Compose. -* Familiarity with [navigation terminology](https://developer.android.com/guide/navigation). -* Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [AndroidFragment](https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1)) for interoperability with Compose. -* Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657) first ([example](https://github.com/android/nowinandroid/pull/1413)). -* Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt). -* Your app must have a [minSdk](https://developer.android.com/guide/topics/manifest/uses-sdk-element#min) of 23 or above. +- Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657) first ([example](https://github.com/android/nowinandroid/pull/1413)). +- Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt).  -## Step-by-step code examples {#step-by-step-code-examples} +- Your app must have a [minSdk](https://developer.android.com/guide/topics/manifest/uses-sdk-element#min) of 23 or above.  -A [migration recipe](https://github.com/android/nav3-recipes/tree/dt/2to3migration) exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. -To use the migration recipe as a guide: - - - -* Clone the [nav3-recipes repository](https://github.com/android/nav3-recipes), load it into Android Studio and switch to the Android view in the project explorer -* Expand the `com.example.nav3recipes.migration` package -* Open `start.StartMigrationActivity`. Familiarise yourself with the navigation structure and behavior defined in this activity. For simplicity, the recipe codebase is not modularized, however, it is structured in a way that should make it clear where the module boundaries would be in a real app. This is the starting point for migration. +## Step-by-step code examples +A [migration recipe](https://github.com/android/nav3-recipes/tree/dt/2to3migration) exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step.  +To use the migration recipe as a guide: -

>>>>> gd2md-html alert: inline image link here (to images/image1.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

- +- Clone the [nav3-recipes repository](https://github.com/android/nav3-recipes), load it into Android Studio and switch to the Android view in the project explorer -![alt_text](images/image1.png "image_tooltip") +- Expand the com.example.nav3recipes.migration package +- Open start.StartMigrationActivity. Familiarise yourself with the navigation structure and behavior defined in this activity. For simplicity, the recipe codebase is not modularized, however, it is structured in a way that should make it clear where the module boundaries would be in a real app. This is the starting point for migration.  +![](data:image/png;base64,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)  +- Open MigrationActivityNavigationTest which is under the androidTest source set. This file contains the instrumented tests that verify the navigation behavior.  -* Open `MigrationActivityNavigationTest` which is under the `androidTest` source set. This file contains the instrumented tests that verify the navigation behavior. -* Run the tests. Note that the tests are run on every migration step activity. +- Run the tests. Note that the tests are run on every migration step activity. Tips for working with the migration recipe: +- It can be useful to see the differences between migration steps. To do this, highlight both files in Android Studio project explorer then right click and choose "Compare files". The first file to be selected is the one that will appear in the left window pane.  +![](data:image/png;base64,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) -* It can be useful to see the differences between migration steps. To do this, highlight both files in Android Studio project explorer then right click and choose "Compare files". The first file to be selected is the one that will appear in the left window pane. - - - -

>>>>> gd2md-html alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

- - -![alt_text](images/image2.png "image_tooltip") - - - +- To run the migration tests only on a single activity, uncomment the other activities in the data function inside MigrationActivityNavigationTest.  -* To run the migration tests only on a single activity, uncomment the other activities in the `data` function inside `MigrationActivityNavigationTest`. -* The migration steps introduce a `Navigator` class. Setting its `shouldPrintDebugInfo` parameter to `true` will output lots of debug information to Logcat. +- The migration steps introduce a Navigator class. Setting its shouldPrintDebugInfo parameter to true will output lots of debug information to Logcat.  -## Step 1. Add the Nav3 dependencies {#step-1-add-the-nav3-dependencies} +## Step 1. Add the Nav3 dependencies -The latest dependencies can be found here: [https://developer.android.com/guide/navigation/navigation-3/get-started](https://developer.android.com/guide/navigation/navigation-3/get-started) +The latest dependencies can be found here: +- Update lib.versions.toml to include the Nav3 dependencies. Use the [latest version from here](https://developer.android.com/jetpack/androidx/releases/navigation3). +| | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| androidxNavigation3 = "1.0.0-alpha07"androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "androidxNavigation3" }androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" } | -* Update `lib.versions.toml` to include the Nav3 dependencies. Use the [latest version from here](https://developer.android.com/jetpack/androidx/releases/navigation3). - ``` -androidxNavigation3 = "1.0.0-alpha07" -androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "androidxNavigation3" } -androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" } -``` +## 1.1 Create a common navigation module +- If you don't have one already, create a :core:navigation module +- Add the Nav3 runtime as a dependency using     api(libs.androidx.navigation3.runtime). This allows modules depending on :core:navigation to use the Nav3 runtime API.  +- Add the Nav2 dependencies. These will be removed once migration is complete.  -### 1.1 Create a common navigation module +Example build.gradle.kts:  +| | +| ------------------------------------------------------------------------------------------------------ | +| dependencies {    api(libs.androidx.navigation3.runtime)    implementation(libs.androidx.navigation2)} | +**Note:** Nav3 has two libraries: runtime and ui. Usually only the app module needs to depend on navigation3.ui which is why it isn't included in the :core:navigation dependencies above.  -* If you don't have one already, create a `:core:navigation` module -* Add the Nav3 runtime as a dependency using ` api(libs.androidx.navigation3.runtime)`. This allows modules depending on `:core:navigation` to use the Nav3 runtime API. -* Add the Nav2 dependencies. These will be removed once migration is complete. -Example `build.gradle.kts`: +## 1.2 Update main app module +- Update the app module to depend on :core:navigation and on androidx.navigation3.ui  -``` -dependencies { -api(libs.androidx.navigation3.runtime) -implementation(libs.androidx.navigation2) -} -``` +- Update compileSdk to 36 or above +- Update minSdk to 23 or above -**Note:** Nav3 has two libraries: `runtime` and `ui`. Usually only the `app` module needs to depend on `navigation3.ui` which is why it isn't included in the `:core:navigation` dependencies above. +- Update AGP to 8.9.3 or above -### 1.2 Update main app module +## Step 2. Create a back stack and use it with NavDisplay +## 2.1 Add the Navigator class +| | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Important:** A fundamental difference between Nav2 and Nav3 is that **you own the back stack**. This means much of the logic and state that was previously managed by Nav2, must now be managed by you. This gives you greater flexibility and control, but also more responsibility. To aid with migration, a class which provides and manages a back stack named Navigator is provided for you. It is not part of the Nav3 library and it does not provide all the features of Nav2. Instead it is intended to be an assistant during migration, and after to be a starting point for you to implement your own navigation behavior and logic.  | -* Update the `app` module to depend on `:core:navigation `and on `androidx.navigation3.ui` -* Update compileSdk to 36 or above -* Update minSdk to 23 or above -* Update AGP to 8.9.3 or above +Copy the [Navigator class](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt) to the :core:navigation module. This class contains backStack: SnapshotStateList\ that can be used with NavDisplay.It will mirror NavController's back stack ensuring that Nav2's state remains the source of truth throughout migration.  After the migration is complete, the NavController mirroring code will be removed.  -## Step 2. Create a back stack and use it with `NavDisplay` {#step-2-create-a-back-stack-and-use-it-with-navdisplay} +## 2.2 Make the Navigator available everywhere that NavController is +Goal: The Navigator class is available everywhere that NavController is used.   -### 2.1 Add the `Navigator` class +- Create the Navigator immediately after NavController is created +Example: -``` -Important: A fundamental difference between Nav2 and Nav3 is that you own the back stack. This means much of the logic and state that was previously managed by Nav2, must now be managed by you. This gives you greater flexibility and control, but also more responsibility. - -To aid with migration, a class which provides and manages a back stack named Navigator is provided for you. It is not part of the Nav3 library and it does not provide all the features of Nav2. Instead it is intended to be an assistant during migration, and after to be a starting point for you to implement your own navigation behavior and logic. -``` - - -Copy the [Navigator class](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt) to the `:core:navigation` module. This class contains `backStack: SnapshotStateList<Any>` that can be used with `NavDisplay.`It will mirror `NavController`'s back stack ensuring that Nav2's state remains the source of truth throughout migration. After the migration is complete, the `NavController` mirroring code will be removed. - - -### 2.2 Make the `Navigator` available everywhere that `NavController` is - -Goal: The `Navigator` class is available everywhere that `NavController` is used. - +| | +| ------------------------------------------------------------------------------------------------ | +| val navController = rememberNavController()val navigator = remember { Navigator(navController) } | +- Do a project-wide search for "NavController" and "NavHostController" -* Create the `Navigator` immediately after `NavController` is created +- Update any classes or methods that accept a NavController or NavHostController to also accept Navigator as a parameter -Example: +## 2.3 Wrap NavHost with NavDisplay -``` -val navController = rememberNavController() -val navigator = remember { Navigator(navController) } -``` +Goal: NavDisplay displays your existing NavHost using a fallback NavEntry.  +- Wrap NavHost with a NavDisplay +- Pass your Navigator's back stack to the NavDisplay +- Set NavDisplay.onBack to call navigator.goBack() -* Do a project-wide search for "NavController" and "NavHostController" -* Update any classes or methods that accept a `NavController` or `NavHostController` to also accept `Navigator` as a parameter +- Create an entryProvider with a fallback lambda that always displays the existing NavHost +Example:  -### 2.3 Wrap `NavHost` with `NavDisplay` +| | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NavDisplay(   backStack = navigator.backStack,   onBack = { navigator.goBack() },   entryProvider = entryProvider(       fallback = { key ->           NavEntry(key = key) {               NavHost(...)           }       },   ) {       // No Nav3 entries yet   },) | -Goal: `NavDisplay` displays your existing `NavHost` using a fallback `NavEntry`. +## Step 3. \[Single feature] Migrate routes +Goal: Routes are moved into their own :feature:api module and their properties are modelled outside of NavHost -* Wrap `NavHost` with a `NavDisplay` -* Pass your `Navigator`'s back stack to the `NavDisplay` -* Set `NavDisplay.onBack` to call `navigator.goBack()` -* Create an `entryProvider` with a `fallback` lambda that always displays the existing `NavHost` -Example: +## 3.1 Split feature module into api and impl +Choose **a single feature module** that does not contain the start destination for your app. The feature module containing the start destination will be migrated last.  -``` -NavDisplay( -backStack = navigator.backStack, -onBack = { navigator.goBack() }, -entryProvider = entryProvider( -fallback = { key -> -NavEntry(key = key) { -NavHost(...) -} -}, -) { -// No Nav3 entries yet -}, -) -``` +Create the api module: +- Create a new feature module named :\:api  +- Move the routes into it -## Step 3. [Single feature] Migrate routes {#step-3-[single-feature]-migrate-routes} +- Apply the KotlinX Serialization plugin to the module by updating the build.gradle.kts -Goal: Routes are moved into their own `:feature:api` module and their properties are modelled outside of `NavHost` +Update the :core:navigation module: +- Add a dependency on :\:api - this allows Navigator to access the feature's routes. It is not good practice for :core modules to depend on :feature modules, however, this is necessary during migration. This dependency will be removed once migration is complete.  -### 3.1 Split feature module into `api` and `impl` +Create the impl module: -Choose **a single feature module** that does not contain the start destination for your app. The feature module containing the start destination will be migrated last. +- Move the remaining contents of :\ into :\:impl -Create the `api` module: +- Add the following dependencies: + - :\:api so it has access to the routes + - :core:navigation so it has access to the Nav3 APIs and the Navigator class  -* Create a new feature module named `:<existingfeaturename>:api` -* Move the routes into it -* Apply the KotlinX Serialization plugin to the module by updating the `build.gradle.kts` +Update :app dependencies: -Update the `:core:navigation` module: +- Update the :app module to depend on both :\:api and :\:impl.  +## 3.2 Model nested navigation graphs -* Add a dependency on `:<existingfeaturename>:api` - this allows `Navigator` to access the feature's routes. It is not good practice for `:core` modules to depend on `:feature` modules, however, this is necessary during migration. This dependency will be removed once migration is complete. +Skip this section if you don't use nested navigation graphs.  -Create the `impl` module: +### 3.2.1 Nested graph migration overview +In Nav2, you can define nested navigation graphs using the navigation builder function inside NavHost. NavController provides a back stack for each nested graph. This allows you to have several top level destinations, each with sub-destinations. You can also define shared destinations - ones that are accessible from more than one navigation graph - by duplicating the destination in multiple graphs. -* Move the remaining contents of `:<existingfeaturename>` into `:<existingfeaturename>:impl` -* Add the following dependencies: - * `:<existingfeaturename>:api` so it has access to the routes - * `:core:navigation` so it has access to the Nav3 APIs and the `Navigator` class +For example, the following code defines two nested navigation graphs, each containing a shared destination defined by RouteE.  -Update `:app` dependencies: +| | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| @Serializable private data object BaseRouteA\@Serializable private data object RouteA\@Serializable private data object RouteA1\@Serializable private data object BaseRouteB\@Serializable private data object RouteB\@Serializable private data object RouteB1\@Serializable private data object RouteENavHost(startDestination = BaseRouteA){    navigation\(startDestination = RouteA) {        composable\ { ContentRed("Route A title") }        composable\ { ContentRed("Route A1 title") }        composable\ { SharedScreen() }    }    navigation\(startDestination = RouteB) {        composable\ { ContentRed("Route B title") }        composable\ { ContentRed("Route B1 title") }        composable\ { SharedScreen() }    }} | +In Nav3, how you model relationships between routes is up to you. In this migration guide, NavHost will be removed so it's important that the properties and relationships defined here are captured elsewhere.  +One possible way of modelling these properties (though by no means the only way), is to define marker interfaces for the top level and shared routes.  -* Update the `:app` module to depend on both `:<existingfeaturename>:api` and `:<existingfeaturename>:impl`. +| | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| @Serializable private data object RouteA : Route.TopLevel\@Serializable private data object RouteA1\@Serializable private data object RouteB : Route.TopLevel\@Serializable private data object RouteB1\@Serializable private data object RouteE : Route.Sharedsealed interface Route {    interface TopLevel : Route    interface Shared : Route} | +Once modelled, the nested navigation and shared destination behavior can be implemented as follows inside a class that provides a back stack, such as the provided Navigator.  -### 3.2 Model nested navigation graphs -Skip this section if you don't use nested navigation graphs. +#### For nested navigation +- Each top level route has its own back stack. -#### 3.2.1 Nested graph migration overview +- The first element in that back stack is the top level route - this approach means we no longer need the BaseRoute objects to identify each nested navigation graph, the first element is sufficient. -In Nav2, you can define nested navigation graphs using the `navigation` builder function inside `NavHost`. `NavController` provides a back stack for each nested graph. This allows you to have several top level destinations, each with sub-destinations. You can also define shared destinations - ones that are accessible from more than one navigation graph - by duplicating the destination in multiple graphs. +- The current top level route is tracked and sub routes are added to its back stack - there is no explicit definition of parent-child relationships between routes -For example, the following code defines two nested navigation graphs, each containing a shared destination defined by `RouteE`. +- When the top level route changes, other top level stacks can be retained or discarded.  +- The top level stacks can be flattened into a single list which is observed by NavDisplay.  -``` -@Serializable private data object BaseRouteA -@Serializable private data object RouteA -@Serializable private data object RouteA1 -@Serializable private data object BaseRouteB -@Serializable private data object RouteB -@Serializable private data object RouteB1 -@Serializable private data object RouteE -NavHost(startDestination = BaseRouteA){ -navigation(startDestination = RouteA) { -composable { ContentRed("Route A title") } -composable { ContentRed("Route A1 title") } -composable { SharedScreen() } -} -navigation(startDestination = RouteB) { -composable { ContentRed("Route B title") } -composable { ContentRed("Route B1 title") } -composable { SharedScreen() } -} -} -``` +#### For shared routes +- When navigating to a route that implements Route.Shared, check whether it's already on a top level stack: -In Nav3, how you model relationships between routes is up to you. In this migration guide, `NavHost` will be removed so it's important that the properties and relationships defined here are captured elsewhere. + - If so, move it to the current top level stack -One possible way of modelling these properties (though by no means the only way), is to define marker interfaces for the top level and shared routes. + - If not, add it to the current top level stack -``` -@Serializable private data object RouteA : Route.TopLevel -@Serializable private data object RouteA1 -@Serializable private data object RouteB : Route.TopLevel -@Serializable private data object RouteB1 -@Serializable private data object RouteE : Route.Shared +#### Example -sealed interface Route { -interface TopLevel : Route -interface Shared : Route -} -``` +Taking the code example from above. The starting route is A.  +| | | | | | +| --------------- | --------------------------- | ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- | +| **User action** | **Current top level route** | **Top level stacks** | **Back stack** | **Notes** | +| Open app | A | A => \[A] | A | | +| Tap on A1 | A | A => \[A, A1] | A, A1 | | +| Tap on B | B | A => \[A, A1]B => \[B] | A, A1, B | | +| Tap on B1 | B | A => \[A, A1]B => \[B, B1] | A, A1, B, B1 | | +| Tap on E | B | A => \[A, A1]B => \[B, B1, E] | A, A1, B, B1, E | | +| Tap on A | A | A => \[A, A1] | A, A1 | We make the decision to pop all B's routes from the stack, this is similar to using popUpTo(A) when navigating using Nav2 | +| Tap on E | A | A => \[A, A1, E] | A, A1, E | | -Once modelled, the nested navigation and shared destination behavior can be implemented as follows inside a class that provides a back stack, such as the provided `Navigator`. +#### Steps -##### For nested navigation +Review the provided Navigator class to ensure that it can model your app's current navigation behavior. In particular:  +- Review the [add method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142) +- Note that popUpTo in the [navigate method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121) will be ignored when switching to Nav3 in the final step. There is no equivalent to popUpTo in Nav3 because you control the back stack. The supplied Navigator class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using canTopLevelRoutesExistTogether.  -* Each top level route has its own back stack. -* The first element in that back stack is the top level route - this approach means we no longer need the `BaseRoute` objects to identify each nested navigation graph, the first element is sufficient. -* The current top level route is tracked and sub routes are added to its back stack - there is no explicit definition of parent-child relationships between routes -* When the top level route changes, other top level stacks can be retained or discarded. -* The top level stacks can be flattened into a single list which is observed by `NavDisplay`. - -##### For shared routes - - - -* When navigating to a route that implements `Route.Shared`, check whether it's already on a top level stack: - * If so, move it to the current top level stack - * If not, add it to the current top level stack - - -##### Example - -Taking the code example from above. The starting route is A. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
User action - Current top level route - Top level stacks - Back stack - Notes -
Open app - A - A => [A] - A - -
Tap on A1 - A - A => [A, A1] - A, A1 - -
Tap on B - B - A => [A, A1] -

-B => [B] -

A, A1, B - -
Tap on B1 - B - A => [A, A1] -

-B => [B, B1] -

A, A1, B, B1 - -
Tap on E - B - A => [A, A1] -

-B => [B, B1, E] -

A, A1, B, B1, E - -
Tap on A - A - A => [A, A1] - A, A1 - We make the decision to pop all B's routes from the stack, this is similar to using popUpTo(A) when navigating using Nav2 -
Tap on E - A - A => [A, A1, E] - A, A1, E - -
- - - -##### Steps - -Review the provided `Navigator` class to ensure that it can model your app's current navigation behavior. In particular: - - - -* Review the [add method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142) -* Note that popUpTo in the [navigate method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121) will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. - - -#### 3.2.2 Update routes to implement marker interfaces +### 3.2.2 Update routes to implement marker interfaces Steps: +- Update each top level route so that it implements the Route.TopLevel interface provided by Navigator.kt + +- Update each shared route so that it implements the Route.Shared interface provided by Navigator.kt -* Update each top level route so that it implements the `Route.TopLevel` interface provided by `Navigator.kt` -* Update each shared route so that it implements the `Route.Shared` interface provided by `Navigator.kt` +## Step 4. \[Single feature] Move destinations from NavHost to entryProvider +Goal: When navigating to a route, it is provided using NavDisplay's entryProvider. -## Step 4. [Single feature] Move destinations from `NavHost` to `entryProvider` {#step-4-[single-feature]-move-destinations-from-navhost-to-entryprovider} -Goal: When navigating to a route, it is provided using `NavDisplay`'s `entryProvider`. +## 4.1 Move composable content from NavHost into entryProvider +Continue only with the feature module being migrated in the previous step.  -### 4.1 Move composable content from `NavHost` into `entryProvider` -Continue only with the feature module being migrated in the previous step. +### 4.1.1 Move directly defined destinations, such as composable +For each destination inside NavHost, do the following based the destination type: -#### 4.1.1 Move directly defined destinations, such as `composable` +- navigation - do nothing -For each destination inside `NavHost`, do the following based the destination type: +- composable\ - Copy the function into entryProvider and rename composable to entry, retaining the type parameter. Remove the composable content from the old composable\ leaving it empty i.e., composable\{}.    +- dialog\ -  Same as composable but add metadata to the entry as follows: entry\(metadata = DialogSceneStrategy.dialog()) + - If you haven't already, add DialogSceneStrategy to NavDisplay's sceneStrategy parameter.  -* `navigation` - do nothing -* `composable<T>` - Copy the function into `entryProvider` and rename `composable` to `entry`, retaining the type parameter. Remove the composable content from the old `composable<T>` leaving it empty i.e., `composable<T>{}`. -* `dialog<T>` - Same as `composable` but add metadata to the `entry` as follows: `entry<T>(metadata = DialogSceneStrategy.dialog())` - * If you haven't already, add `DialogSceneStrategy` to `NavDisplay`'s `sceneStrategy` parameter. -* [bottomSheet](https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/package-summary#(androidx.navigation.NavGraphBuilder).bottomSheet(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2)) - [Follow the bottom sheet recipe here](https://github.com/android/nav3-recipes/pull/67). This essentially the same as the instructions for `dialog` except that `BottomSheetSceneStrategy` is not part of the core Nav3 library and so should be copied/modified to your individual requirements. +- [bottomSheet](https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/package-summary#\(androidx.navigation.NavGraphBuilder\).bottomSheet\(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2\)) - [Follow the bottom sheet recipe here](https://github.com/android/nav3-recipes/pull/67). This essentially the same as the instructions for dialog except that BottomSheetSceneStrategy is not part of the core Nav3 library and so should be copied/modified to your individual requirements. -#### 4.1.2 Obtain navigation arguments +### 4.1.2 Obtain navigation arguments -In Nav2, when navigation arguments are passed using the route instance, you must first obtain the route instance from `NavBackStackEntry` by calling `toRoute`. In Nav3, the route instance is directly accessible with `entry`'s lambda parameter so there's no need to obtain the route instance. +In Nav2, when navigation arguments are passed using the route instance, you must first obtain the route instance from NavBackStackEntry by calling toRoute. In Nav3, the route instance is directly accessible with entry's lambda parameter so there's no need to obtain the route instance.  If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels](https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels) and apply the technique most appropriate to your codebase. -#### 4.1.3 Code example +### 4.1.3 Code example Existing code: - -``` -NavHost(...){ -navigation(startDestination = RouteB) { -composable{ entry -> -val id = entry.toRoute().id -Text("Route B, id: $id") -} -dialog { Text ("Dialog D") } -} -} -``` - +| | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| NavHost(...){    navigation\(startDestination = RouteB) {        composable\{ entry ->             val id = entry.toRoute\().id            Text("Route B, id: $id")         }        dialog\ { Text ("Dialog D") }    }} | New code: +| | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NavHost(...){    navigation\(startDestination = RouteB) {        composable\{}        dialog\ {}    }}NavDisplay(...,     sceneStrategy = remember { DialogSceneStrategy() },    entryProvider = entryProvider {        entry\{ route -> Text("Route B, id: ${route.id}") }        entry\(metadata = DialogSceneStrategy.dialog()) { Text ("Dialog D") }    }) | -``` -NavHost(...){ -navigation(startDestination = RouteB) { -composable{} -dialog {} -} -} - -NavDisplay(..., -sceneStrategy = remember { DialogSceneStrategy() }, -entryProvider = entryProvider { -entry{ route -> Text("Route B, id: ${route.id}") } -entry(metadata = DialogSceneStrategy.dialog()) { Text ("Dialog D") } -} -) -``` +### 4.2.1 Move NavGraphBuilder extension functions +[NavGraphBuilder extension functions](https://developer.android.com/guide/navigation/design/encapsulate) can be refactored to EntryProviderBuilder extension functions. These functions can then be called inside entryProvider.  -#### 4.2.1 Move `NavGraphBuilder` extension functions +Refactoring NavHost:  -[NavGraphBuilder extension functions](https://developer.android.com/guide/navigation/design/encapsulate) can be refactored to `EntryProviderBuilder` extension functions. These functions can then be called inside `entryProvider`. +- Copy the function call into entryProvider -Refactoring `NavHost`: +- Inline the original function reference and keep the existing function +![](data:image/png;base64,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U9PHmxLOX+NSsleIBhRBl7IhjmALlzWwAEPbxm1qEH3MmDFyySV/rJJuuql4cluD8E3GpXXr1tK+fXthktm8ub/zKb04FhtuueVmef75f8q1114rH330UdrcZPn0nT/PP/+CXHfdtXLHHXfIv//9r0W+5uowX+QLrOECdthhB+EdkPzucMioUaPkqaeekssu+7OccMLxcvPNN8nH+L4siN6byELVscceR9cM8dFEFv+onDVrlvzzn/+UY489Rvbaa0854ID95b777hWej7TzzsLjjzuebJOgcO60bdu26Hoef/wxFJEfk7/+9a9y6623FPVZWpX77befXHrpn2X11VdXCPjZK2ONIWAIGAKGgCFgCDQ6ArmQo2VmQp4W5WdUxz4pnSCb04QNrpK3FVGpB/NGZbRhsKwnNTQV+lHriXmyFbo8FtbWAQEbUk8EeAYWhAgnMi4VKTuLXM4Fm4hzTkmwpdwgVbWHy4L3qXocfT05uNMXU4ILO7URDyM9KWV9qIkIDtgjwXcYpowfk7XSBgRwSY307FJTOnE6Vhs6K7PoGibn77zzjlRFH3/88aJb4EKc+d1330WSfqu8/vq/F+I5YMOpAAAQAElEQVSs9ZuqefPmcYB33nk75o1pOAR2330Pcc6ft2+99aacccbpcu+998j//vc/+eGHH+TFF1+U884/T26//TaZF/0oySabbCKhqBVWst7662mciooKufPOO+S2226VESNGqHnGjBny5JNPykUXXSTjx/tXAwxcYQXho6nq0MQbFor5SOcDD9wv6bu7mviyF8ryfve7HbTAzn8LP/jgA7nmmqsXyrw2iSFgCBgChoAhYAgEBJwELqdZWi6IcU+98H/3YhMZKuBClgRW4BSzkt1Caud7jqVnDiNESbDRRgIb7fTzbPS/m/booofDWkNgESAQzsLU1PyfeC8mJytlSsHGYeRJtJFoZ59QLmEjLrkYFNoil1SHiOrmcBkTvagk4yXa6AA/7lwUtN6HehIM0OmuLHWUfB8NKbxTDGZ1p2sgKqDXiyd02kPWhaFxIKjjXe2x1DSZk046Sc488yzhnQqlVshHtOjD9xilfcJYvtOH+i222FKOP/4Euerqq+Wyyy6TI488Ut/zQ1tVtN5668kRRxyBwsDFctWVV8mpp54mvGMm3HUTxrLYwHWwD7oNNthA1089CxJBf9BB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) +- Remove any composable content associated with the entries inside NavHost. Keeping blank entries for each route ensures that NavController's back stack is still the source of truth for the navigation state.  -* Copy the function call into `entryProvider` -* Inline the original function reference and keep the existing function +Refactoring the extension function:  +- Change the method signature from NavGraphBuilder.existingScreen() to EntryProviderBuilder\.existingScreen().  +* Remove navigation destinations, leaving only the destinations they contain. -

>>>>> gd2md-html alert: inline image link here (to images/image3.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

+* Replace composable and dialog destinations with entry + - For dialog destinations add the dialog metadata following the instructions in the previous step -![alt_text](images/image3.png "image_tooltip") - - - -* Remove any composable content associated with the entries inside `NavHost`. Keeping blank entries for each route ensures that `NavController`'s back stack is still the source of truth for the navigation state. - -Refactoring the extension function: - - - -* Change the method signature from `NavGraphBuilder.existingScreen()` to `EntryProviderBuilder<Any>.existingScreen()`. -* Remove `navigation` destinations, leaving only the destinations they contain. -* Replace `composable` and `dialog` destinations with `entry` - * For `dialog` destinations add the dialog metadata following the instructions in the previous step - - -#### 4.2.2 Code example +### 4.2.2 Code example Existing code: - -``` -NavHost(...) { -featureBSection() -} - -private fun NavGraphBuilder.featureBSection(onDetailClick: () -> Unit) { -navigation(startDestination = RouteB) { -composable { ContentRed("Route B title") } -} -} -``` - +| | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NavHost(...) {    featureBSection()}private fun NavGraphBuilder.featureBSection(onDetailClick: () -> Unit) {    navigation\(startDestination = RouteB) {        composable\ { ContentRed("Route B title") }    }} | New code: +| | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NavHost(...) {    navigation\(startDestination = RouteB) {        composable\ { }    }}NavDisplay(..., entryProvider = entryProvider {    featureBSection()})private fun EntryProviderBuilder\.featureBSection() {    entry\ { ContentRed("Route B title") }} | -``` -NavHost(...) { -navigation(startDestination = RouteB) { -composable { } -} -} - -NavDisplay(..., entryProvider = entryProvider { -featureBSection() -}) -private fun EntryProviderBuilder.featureBSection() { -entry { ContentRed("Route B title") } -} -``` +## 4.3 In Navigator, convert NavBackStackEntry back to its route instance +Steps:  +- Locate the line starting val route in Navigator.   -### 4.3 In `Navigator`, convert `NavBackStackEntry` back to its route instance +- Add an if branch for each migrated route that converts the NavBackStackEntry into a route instance using NavBackStackEntry.toRoute\. For example: -Steps: +| | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| val route =   if (destination.hasRoute\()) {       entry.toRoute\()   } else if (destination.hasRoute\()) {       entry.toRoute\()   } else {       // Non migrated route       entry   } | +You should now be able to navigate to, and back from, the migrated destinations. These destinations will be displayed directly inside NavDisplay rather than by NavHost. +**Note:** When navigating (both forward and back) between destinations handled by NavHost and NavDisplay, you may see the blank destination until the transition animation has completed.  -* Locate the line starting `val route` in `Navigator`. -* Add an `if` branch for each migrated route that converts the `NavBackStackEntry` into a route instance using `NavBackStackEntry.toRoute<MigratedRouteType>`. For example: - ``` -val route = - if (destination.hasRoute()) { - entry.toRoute() - } else if (destination.hasRoute()) { - entry.toRoute() - } else { - // Non migrated route - entry - } -``` +## Step 5. \[Single feature] Replace NavController with Navigator  +Goal: Within the migrated feature module, navigation events are handled by Navigator instead of NavController +Steps:  -You should now be able to navigate to, and back from, the migrated destinations. These destinations will be displayed directly inside `NavDisplay` rather than by `NavHost`. +- Replace NavController.popBackStack with Navigator.goBack -**Note:** When navigating (both forward and back) between destinations handled by `NavHost` and `NavDisplay`, you may see the blank destination until the transition animation has completed. +- Replace NavController.navigate  with Navigator.navigate +TODO: Add warning about navOptions - you'll need to modify Navigator behavior if you don't like what it does -## Step 5. [Single feature] Replace `NavController` with `Navigator` {#step-5-[single-feature]-replace-navcontroller-with-navigator} +For NavController extension functions defined by **other modules**:  -Goal: Within the migrated feature module, navigation events are handled by `Navigator` instead of `NavController` - -Steps: - - - -* Replace `NavController.popBackStack` with `Navigator.goBack` -* Replace `NavController.navigate` with `Navigator.navigate` - -TODO: Add warning about `navOptions` - you'll need to modify `Navigator` behavior if you don't like what it does - -For `NavController` extension functions defined by **other modules**: +- Inline the function, leaving the other module's function in place  +- Make the replacements above  +Remove Nav2 imports and module dependencies:  -* Inline the function, leaving the other module's function in place -* Make the replacements above +- Remove all imports starting with import androidx.navigation -Remove Nav2 imports and module dependencies: - - - -* Remove all imports starting with `import androidx.navigation` -* Remove feature module dependencies on `androidx.navigation` +- Remove feature module dependencies on androidx.navigation  At this point, this feature module has been fully migrated to Nav3. -## Step 6. Migrate all feature modules {#step-6-migrate-all-feature-modules} +## Step 6. Migrate all feature modules  Goal: Feature modules use Nav3. They don't contain any Nav2 code. Complete steps 3-5 for each feature module. Start with the module with the least dependencies and end with the module that contains the start route. -Ensure that shared entries are not duplicated. +Ensure that shared entries are not duplicated.  -## Step 7. Use `Navigator.backStack` as source of truth for navigation state {#step-7-use-navigator-backstack-as-source-of-truth-for-navigation-state} +## Step 7. Use Navigator.backStack as source of truth for navigation state - -### 7.1 Ensure `Navigator` is used instead of `NavController` everywhere +## 7.1 Ensure Navigator is used instead of NavController everywhere Replace any remaining instances of: +- NavController.navigate with Navigator.navigate +- NavController.popBackStack with Navigator.goBack -* `NavController.navigate` with `Navigator.navigate` -* `NavController.popBackStack` with `Navigator.goBack` - - -### 7.2 Update `Navigator` to modify its back stack directly +## 7.2 Update Navigator to modify its back stack directly +- Open Navigator -* Open `Navigator` -* In `navigate` and `goBack`: - * Remove the code that calls `NavController` - * Uncomment the code that modifies the back stack directly -* Remove all code which references `NavController` +- In navigate and goBack: -The final `Navigator` [should look like this](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15). + - Remove the code that calls NavController + - Uncomment the code that modifies the back stack directly -### 7.3 Set the app's start route +- Remove all code which references NavController -When creating the `Navigator` specify the starting route for your app. +The final Navigator [should look like this](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15). -``` -val navigator = remember { Navigator(navController, startRoute = RouteA) } -``` +## 7.3 Set the app's start route +When creating the Navigator specify the starting route for your app.  +| | +| -------------------------------------------------------------------------- | +| val navigator = remember { Navigator(navController, startRoute = RouteA) } | -### 7.4 Update common navigation UI components -If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94). +## 7.4 Update common navigation UI components -In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. `BaseRouteA` and `RouteA`). This is no longer necessary so remove any redundant types for the navigation graph from the `:api` modules. Ensure that the correct types are used to identify top level routes. +If using a common navigation component, such as a NavBar, change the logic for when a top level route is selected to use Navigator.topLevelRoute. [See example here](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94). +In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. BaseRouteA and RouteA). This is no longer necessary so remove any redundant types for the navigation graph from the :api modules. Ensure that the correct types are used to identify top level routes. -### 7.5 Remove the `entryProvider` fallback -Remove the `fallback` parameter from `entryProvider` as there are no longer any unmigrated routes that must be handled by `NavHost`. +## 7.5 Remove the entryProvider fallback +Remove the fallback parameter from entryProvider as there are no longer any unmigrated routes that must be handled by NavHost. -### 7.6. Remove unused dependencies +## 7.6. Remove unused dependencies +- Remove all remaining Nav2 dependencies from the project -* Remove all remaining Nav2 dependencies from the project -* In `:core:navigation` remove any dependencies on `:feature:api` modules +- In :core:navigation remove any dependencies on :feature:api modules Congratulations! Your project is now migrated to Navigation 3. -## Next steps {#next-steps} +## Next steps -In the supplied `Navigator`, the type of items in the back stack is `Any`. You may now want to change this to use stronger types, for example the `NavKey` interface provided by Nav3. +In the supplied Navigator, the type of items in the back stack is Any. You may now want to change this to use stronger types, for example the NavKey interface provided by Nav3.   From 90f66abb07e2e4e6252ba13b5e9583eeefc10dea Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 11:45:21 +0100 Subject: [PATCH 54/64] Update guide --- docs/MigratingFromNavigation2.md | 631 ++++++++++++---------- docs/images/migration/compare_files.png | Bin 0 -> 36507 bytes docs/images/migration/inline.png | Bin 0 -> 168012 bytes docs/images/migration/start_migration.png | Bin 0 -> 40874 bytes 4 files changed, 344 insertions(+), 287 deletions(-) create mode 100644 docs/images/migration/compare_files.png create mode 100644 docs/images/migration/inline.png create mode 100644 docs/images/migration/start_migration.png diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index 2ec9181..d536f14 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -1,473 +1,530 @@ -# Navigation 2 to 3 migration guide -## Overview +# Navigation 2 to 3 migration guide -This is intended to be a general guide to [Navigation 2](https://developer.android.com/guide/navigation) to [Navigation 3](https://developer.android.com/guide/navigation/navigation-3) migration which can be applied to any project. It attempts to keep the project in a working state during migration (build succeeds, navigation tests pass) and does this by maintaining interoperability between Nav2 and Nav3.  +## Overview {:#overview} -The guide assumes that the project is [modularized](https://developer.android.com/topic/modularization), and the suggested approach allows feature modules to adopt Nav3 on an incremental basis. Once all feature modules have migrated, the Nav2 code can be safely removed. If the codebase is not modularized, the steps for specific modules should be applied to the main app module.   +This is intended to be a general guide to [Navigation 2](https://developer.android.com/guide/navigation) to [Navigation 3](https://developer.android.com/guide/navigation/navigation-3) migration which can be applied to any project. It attempts to keep the project in a working state during migration (build succeeds, navigation tests pass) and does this by maintaining interoperability between Nav2 and Nav3. +The guide assumes that the project is [modularized](https://developer.android.com/topic/modularization), and the suggested approach allows feature modules to adopt Nav3 on an incremental basis. Once all feature modules have migrated, the Nav2 code can be safely removed. If the codebase is not modularized, the steps for specific modules should be applied to the main `app` module. -## Features +### Features {:#features} This guide covers the migration of the following Nav2 features: - Nested navigation graphs - single level of nesting only - -- Shared destinations - ones that can appear in different navigation graphs  - +- Shared destinations - ones that can appear in different navigation graphs - Dialog destinations The following features are not yet supported: - More than one level of nested navigation - - [Custom destination types](https://developer.android.com/guide/navigation/design/kotlin-dsl#custom) - - Deeplinks - -## Prerequisites +### Prerequisites {:#prerequisites} - Familiarity with [navigation terminology](https://developer.android.com/guide/navigation). +- Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [`AndroidFragment`](https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1)) for interoperability with Compose. +- Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657){:.external} first ([example](https://github.com/android/nowinandroid/pull/1413){:.external}). +- Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt){:.external}. +- Your app must have a [minSdk](https://developer.android.com/guide/topics/manifest/uses-sdk-element#min) of 23 or above. -- Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [AndroidFragment](https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment\(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1\)) for interoperability with Compose. - -- Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657) first ([example](https://github.com/android/nowinandroid/pull/1413)). - -- Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt).  - -- Your app must have a [minSdk](https://developer.android.com/guide/topics/manifest/uses-sdk-element#min) of 23 or above.  - - -## Step-by-step code examples +### Step-by-step code examples {:#step-by-step-code} -A [migration recipe](https://github.com/android/nav3-recipes/tree/dt/2to3migration) exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step.  +A [migration recipe](https://github.com/android/nav3-recipes/tree/dt/2to3migration){:.external} exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. To use the migration recipe as a guide: -- Clone the [nav3-recipes repository](https://github.com/android/nav3-recipes), load it into Android Studio and switch to the Android view in the project explorer +- Clone the [nav3-recipes repository](https://github.com/android/nav3-recipes){:.external}, load it into Android Studio and switch to the Android view in the project explorer +- Expand the `com.example.nav3recipes.migration` package +- Open `start.StartMigrationActivity`. Familiarise yourself with the navigation structure and behavior defined in this activity. For simplicity, the recipe codebase is not modularized, however, it is structured in a way that should make it clear where the module boundaries would be in a real app. This is the starting point for migration. -- Expand the com.example.nav3recipes.migration package - -- Open start.StartMigrationActivity. Familiarise yourself with the navigation structure and behavior defined in this activity. For simplicity, the recipe codebase is not modularized, however, it is structured in a way that should make it clear where the module boundaries would be in a real app. This is the starting point for migration.  - -![](data:image/png;base64,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)  - -- Open MigrationActivityNavigationTest which is under the androidTest source set. This file contains the instrumented tests that verify the navigation behavior.  +![Screenshot of Android Studio showing the starting point for migration](images/migration/start_migration.png) +- Open `MigrationActivityNavigationTest` which is under the `androidTest` source set. This file contains the instrumented tests that verify the navigation behavior. - Run the tests. Note that the tests are run on every migration step activity. Tips for working with the migration recipe: -- It can be useful to see the differences between migration steps. To do this, highlight both files in Android Studio project explorer then right click and choose "Compare files". The first file to be selected is the one that will appear in the left window pane.  - -![](data:image/png;base64,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) - -- To run the migration tests only on a single activity, uncomment the other activities in the data function inside MigrationActivityNavigationTest.  - -- The migration steps introduce a Navigator class. Setting its shouldPrintDebugInfo parameter to true will output lots of debug information to Logcat.  +- It can be useful to see the differences between migration steps. To do this, highlight both files in Android Studio project explorer then right click and choose "Compare files". The first file to be selected is the one that will appear in the left window pane. +![Screenshot of Android Studio showing how to compare files](images/migration/compare_files.png) -## Step 1. Add the Nav3 dependencies +- To run the migration tests only on a single activity, uncomment the other activities in the `data` function inside `MigrationActivityNavigationTest`. +- The migration steps introduce a `Navigator` class. Setting its `shouldPrintDebugInfo` parameter to `true` will output lots of debug information to Logcat. -The latest dependencies can be found here: +## Step 1. Add the Nav3 dependencies {:#step-1.} -- Update lib.versions.toml to include the Nav3 dependencies. Use the [latest version from here](https://developer.android.com/jetpack/androidx/releases/navigation3). +The latest dependencies can be found here: [https://developer.android.com/guide/navigation/navigation-3/get-started](https://developer.android.com/guide/navigation/navigation-3/get-started) -| | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| androidxNavigation3 = "1.0.0-alpha07"androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "androidxNavigation3" }androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" } | +- Update `lib.versions.toml` to include the Nav3 dependencies. Use the [latest version from here](https://developer.android.com/jetpack/androidx/releases/navigation3). +``` +androidxNavigation3 = "1.0.0-alpha11" +androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "androidxNavigation3" } +androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" } +``` -## 1.1 Create a common navigation module +### 1.1 Create a common navigation module {:#1.1-create} -- If you don't have one already, create a :core:navigation module +- If you don't have one already, create a :`core:navigation` module +- Add the Nav3 runtime as a dependency using `api(libs.androidx.navigation3.runtime). This` allows modules depending on :core:navigation `to` use the Nav3 runtime API. +- Add the Nav2 dependencies. These will be removed once migration is complete. -- Add the Nav3 runtime as a dependency using     api(libs.androidx.navigation3.runtime). This allows modules depending on :core:navigation to use the Nav3 runtime API.  +Example `build.gradle.kts`: -- Add the Nav2 dependencies. These will be removed once migration is complete.  +``` +dependencies { + api(libs.androidx.navigation3.runtime) + implementation(libs.androidx.navigation2) +} +``` -Example build.gradle.kts:  +**Note**: Nav3 has two libraries: `runtime` and `ui`. Usually only the `app` module needs to depend on `navigation3.ui` which is why it isn't included in the :`core:navigation` dependencies above. -| | -| ------------------------------------------------------------------------------------------------------ | -| dependencies {    api(libs.androidx.navigation3.runtime)    implementation(libs.androidx.navigation2)} | - -**Note:** Nav3 has two libraries: runtime and ui. Usually only the app module needs to depend on navigation3.ui which is why it isn't included in the :core:navigation dependencies above.  - - -## 1.2 Update main app module - -- Update the app module to depend on :core:navigation and on androidx.navigation3.ui  +### 1.2 Update main app module {:#1.2-update} +- Update the `app` module to depend on :`core:navigation` and on `androidx.navigation3.ui` - Update compileSdk to 36 or above - - Update minSdk to 23 or above - - Update AGP to 8.9.3 or above +## Step 2. Create a back stack and use it with NavDisplay {:#step-2.} -## Step 2. Create a back stack and use it with NavDisplay - -## 2.1 Add the Navigator class +### 2.1 Add the Navigator class {:#2.1-add} -| | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Important:** A fundamental difference between Nav2 and Nav3 is that **you own the back stack**. This means much of the logic and state that was previously managed by Nav2, must now be managed by you. This gives you greater flexibility and control, but also more responsibility. To aid with migration, a class which provides and manages a back stack named Navigator is provided for you. It is not part of the Nav3 library and it does not provide all the features of Nav2. Instead it is intended to be an assistant during migration, and after to be a starting point for you to implement your own navigation behavior and logic.  | +Important: A fundamental difference between Nav2 and Nav3 is that **you own the back stack**. This means much of the logic and state that was previously managed by Nav2, must now be managed by you. This gives you greater flexibility and control, but also more responsibility. -Copy the [Navigator class](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt) to the :core:navigation module. This class contains backStack: SnapshotStateList\ that can be used with NavDisplay.It will mirror NavController's back stack ensuring that Nav2's state remains the source of truth throughout migration.  After the migration is complete, the NavController mirroring code will be removed.  +To aid with migration, a class which provides and manages a back stack named `Navigator` is provided for you. It is not part of the Nav3 library and it does not provide all the features of Nav2. Instead it is intended to be an assistant during migration, and after to be a starting point for you to implement your own navigation behavior and logic. +Copy the [`Navigator`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt){:.external} [class](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt){:.external} to the :`core:navigation` module. This class contains `backStack: SnapshotStateList` that can be used with `NavDisplay.It` will mirror `NavController`'s back stack ensuring that Nav2's state remains the source of truth throughout migration. After the migration is complete, the NavController mirroring code will be removed. -## 2.2 Make the Navigator available everywhere that NavController is +### 2.2 Make the Navigator available everywhere that NavController is {:#2.2-make} -Goal: The Navigator class is available everywhere that NavController is used.   +Goal: The `Navigator` class is available everywhere that `NavController` is used. -- Create the Navigator immediately after NavController is created +- Create the `Navigator` immediately after `NavController` is created Example: -| | -| ------------------------------------------------------------------------------------------------ | -| val navController = rememberNavController()val navigator = remember { Navigator(navController) } | +``` +val navController = rememberNavController() +val navigator = remember { Navigator(navController) } +``` - Do a project-wide search for "NavController" and "NavHostController" +- Update any classes or methods that accept a `NavController` or `NavHostController` to also accept `Navigator` as a parameter -- Update any classes or methods that accept a NavController or NavHostController to also accept Navigator as a parameter - - -## 2.3 Wrap NavHost with NavDisplay - -Goal: NavDisplay displays your existing NavHost using a fallback NavEntry.  - -- Wrap NavHost with a NavDisplay +### 2.3 Wrap NavHost with NavDisplay {:#2.3-wrap} -- Pass your Navigator's back stack to the NavDisplay +Goal: `NavDisplay` displays your existing `NavHost` using a fallback `NavEntry`. -- Set NavDisplay.onBack to call navigator.goBack() +- Wrap `NavHost` with a `NavDisplay` +- Pass your `Navigator`'s back stack to the `NavDisplay` +- Set `NavDisplay.onBack` to call `navigator.goBack()` +- Create an `entryProvider` with a `fallback` lambda that always displays the existing `NavHost` -- Create an entryProvider with a fallback lambda that always displays the existing NavHost - -Example:  - -| | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NavDisplay(   backStack = navigator.backStack,   onBack = { navigator.goBack() },   entryProvider = entryProvider(       fallback = { key ->           NavEntry(key = key) {               NavHost(...)           }       },   ) {       // No Nav3 entries yet   },) | - - -## Step 3. \[Single feature] Migrate routes +Example: -Goal: Routes are moved into their own :feature:api module and their properties are modelled outside of NavHost +``` +NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) { + NavHost(...) + } + }, + ) { + // No Nav3 entries yet + }, +) +``` +## Step 3. [Single feature] Migrate routes {:#step-3.} -## 3.1 Split feature module into api and impl +Goal: Routes are moved into their own :`feature:api` module and their properties are modelled outside of `NavHost` -Choose **a single feature module** that does not contain the start destination for your app. The feature module containing the start destination will be migrated last.  +### 3.1 Split feature module into api and impl {:#3.1-split} -Create the api module: +Choose **a single feature module** that does not contain the start destination for your app. The feature module containing the start destination will be migrated last. -- Create a new feature module named :\:api  +Create the `api` module: +- Create a new feature module named :`:api` - Move the routes into it +- Apply the KotlinX Serialization plugin to the module by updating the `build.gradle.kts` -- Apply the KotlinX Serialization plugin to the module by updating the build.gradle.kts - -Update the :core:navigation module: +Update the :`core:navigation` module: -- Add a dependency on :\:api - this allows Navigator to access the feature's routes. It is not good practice for :core modules to depend on :feature modules, however, this is necessary during migration. This dependency will be removed once migration is complete.  +- Add a dependency on :`:api` - this allows `Navigator` to access the feature's routes. It is not good practice for :`core` modules to depend on :`feature` modules, however, this is necessary during migration. This dependency will be removed once migration is complete. -Create the impl module: - -- Move the remaining contents of :\ into :\:impl +Create the `impl` module: +- Move the remaining contents of :`` into :`:impl` - Add the following dependencies: + - :`:api` so it has access to the routes + - :`core:navigation` so it has access to the Nav3 APIs and the `Navigator` class - - :\:api so it has access to the routes - - - :core:navigation so it has access to the Nav3 APIs and the Navigator class  - -Update :app dependencies: +Update :`app` dependencies: -- Update the :app module to depend on both :\:api and :\:impl.  +- Update the :`app` module to depend on both :`:api` and :`:impl`. +### 3.2 Model nested navigation graphs {:#3.2-model} -## 3.2 Model nested navigation graphs +Skip this section if you don't use nested navigation graphs. -Skip this section if you don't use nested navigation graphs.  +#### 3.2.1 Nested graph migration overview +In Nav2, you can define nested navigation graphs using the `navigation` builder function inside `NavHost. NavController` provides a back stack for each nested graph. This allows you to have several top level destinations, each with sub-destinations. You can also define shared destinations - ones that are accessible from more than one navigation graph - by duplicating the destination in multiple graphs. -### 3.2.1 Nested graph migration overview +For example, the following code defines two nested navigation graphs, each containing a shared destination defined by `RouteE`. -In Nav2, you can define nested navigation graphs using the navigation builder function inside NavHost. NavController provides a back stack for each nested graph. This allows you to have several top level destinations, each with sub-destinations. You can also define shared destinations - ones that are accessible from more than one navigation graph - by duplicating the destination in multiple graphs. +``` +@Serializable private data object BaseRouteA +@Serializable private data object RouteA +@Serializable private data object RouteA1 +@Serializable private data object BaseRouteB +@Serializable private data object RouteB +@Serializable private data object RouteB1 +@Serializable private data object RouteE -For example, the following code defines two nested navigation graphs, each containing a shared destination defined by RouteE.  +NavHost(startDestination = BaseRouteA){ + navigation(startDestination = RouteA) { + composable { ContentRed("Route A title") } + composable { ContentRed("Route A1 title") } + composable { SharedScreen() } + } + navigation(startDestination = RouteB) { + composable { ContentRed("Route B title") } + composable { ContentRed("Route B1 title") } + composable { SharedScreen() } + } +} +``` -| | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| @Serializable private data object BaseRouteA\@Serializable private data object RouteA\@Serializable private data object RouteA1\@Serializable private data object BaseRouteB\@Serializable private data object RouteB\@Serializable private data object RouteB1\@Serializable private data object RouteENavHost(startDestination = BaseRouteA){    navigation\(startDestination = RouteA) {        composable\ { ContentRed("Route A title") }        composable\ { ContentRed("Route A1 title") }        composable\ { SharedScreen() }    }    navigation\(startDestination = RouteB) {        composable\ { ContentRed("Route B title") }        composable\ { ContentRed("Route B1 title") }        composable\ { SharedScreen() }    }} | +In Nav3, how you model relationships between routes is up to you. In this migration guide, `NavHost` will be removed so it's important that the properties and relationships defined here are captured elsewhere. -In Nav3, how you model relationships between routes is up to you. In this migration guide, NavHost will be removed so it's important that the properties and relationships defined here are captured elsewhere.  +One possible way of modelling these properties (though by no means the only way), is to define marker interfaces for the top level and shared routes. -One possible way of modelling these properties (though by no means the only way), is to define marker interfaces for the top level and shared routes.  +``` +@Serializable private data object RouteA : Route.TopLevel +@Serializable private data object RouteA1 +@Serializable private data object RouteB : Route.TopLevel +@Serializable private data object RouteB1 +@Serializable private data object RouteE : Route.Shared -| | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| @Serializable private data object RouteA : Route.TopLevel\@Serializable private data object RouteA1\@Serializable private data object RouteB : Route.TopLevel\@Serializable private data object RouteB1\@Serializable private data object RouteE : Route.Sharedsealed interface Route {    interface TopLevel : Route    interface Shared : Route} | - -Once modelled, the nested navigation and shared destination behavior can be implemented as follows inside a class that provides a back stack, such as the provided Navigator.  +sealed interface Route { + interface TopLevel : Route + interface Shared : Route +} +``` +Once modelled, the nested navigation and shared destination behavior can be implemented as follows inside a class that provides a back stack, such as the provided `Navigator`. #### For nested navigation - Each top level route has its own back stack. - -- The first element in that back stack is the top level route - this approach means we no longer need the BaseRoute objects to identify each nested navigation graph, the first element is sufficient. - +- The first element in that back stack is the top level route - this approach means we no longer need the `BaseRoute` objects to identify each nested navigation graph, the first element is sufficient. - The current top level route is tracked and sub routes are added to its back stack - there is no explicit definition of parent-child relationships between routes - -- When the top level route changes, other top level stacks can be retained or discarded.  - -- The top level stacks can be flattened into a single list which is observed by NavDisplay.  - +- When the top level route changes, other top level stacks can be retained or discarded. +- The top level stacks can be flattened into a single list which is observed by `NavDisplay`. #### For shared routes -- When navigating to a route that implements Route.Shared, check whether it's already on a top level stack: - - - If so, move it to the current top level stack - - - If not, add it to the current top level stack - +- When navigating to a route that implements `Route.Shared`, check whether it's already on a top level stack: + - If so, move it to the current top level stack + - If not, add it to the current top level stack #### Example -Taking the code example from above. The starting route is A.  - -| | | | | | -| --------------- | --------------------------- | ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- | -| **User action** | **Current top level route** | **Top level stacks** | **Back stack** | **Notes** | -| Open app | A | A => \[A] | A | | -| Tap on A1 | A | A => \[A, A1] | A, A1 | | -| Tap on B | B | A => \[A, A1]B => \[B] | A, A1, B | | -| Tap on B1 | B | A => \[A, A1]B => \[B, B1] | A, A1, B, B1 | | -| Tap on E | B | A => \[A, A1]B => \[B, B1, E] | A, A1, B, B1, E | | -| Tap on A | A | A => \[A, A1] | A, A1 | We make the decision to pop all B's routes from the stack, this is similar to using popUpTo(A) when navigating using Nav2 | -| Tap on E | A | A => \[A, A1, E] | A, A1, E | | - - -#### Steps - -Review the provided Navigator class to ensure that it can model your app's current navigation behavior. In particular:  - -- Review the [add method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142) - -- Note that popUpTo in the [navigate method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121) will be ignored when switching to Nav3 in the final step. There is no equivalent to popUpTo in Nav3 because you control the back stack. The supplied Navigator class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using canTopLevelRoutesExistTogether.  - - -### 3.2.2 Update routes to implement marker interfaces +Taking the code example from above. The starting route is A. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

User action

Current top level route

Top level stacks

Back stack

Notes

Open app

A

A => [A]

A

Tap on A1

A

A => [A, A1]

A, A1

Tap on B

B

A => [A, A1]

B => [B]

A, A1, B

Tap on B1

B

A => [A, A1]

B => [B, B1]

A, A1, B, B1

Tap on E

B

A => [A, A1]

B => [B, B1, E]

A, A1, B, B1, E

Tap on A

A

A => [A, A1]

A, A1

We make the decision to pop all B's routes from the stack, this is similar to using popUpTo(A) when navigating using Nav2

Tap on E

A

A => [A, A1, E]

A, A1, E

+ +##### Steps + +Review the provided `Navigator` class to ensure that it can model your app's current navigation behavior. In particular: + +- Review the [`add`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142){:.external} [method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142){:.external} +- Note that `popUpTo` in the [`navigate`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121){:.external} [method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121){:.external} will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. + +#### 3.2.2 Update routes to implement marker interfaces Steps: -- Update each top level route so that it implements the Route.TopLevel interface provided by Navigator.kt - -- Update each shared route so that it implements the Route.Shared interface provided by Navigator.kt - - -## Step 4. \[Single feature] Move destinations from NavHost to entryProvider +- Update each top level route so that it implements the `Route.TopLevel` interface provided by `Navigator.kt` +- Update each shared route so that it implements the `Route.Shared` interface provided by `Navigator.kt` -Goal: When navigating to a route, it is provided using NavDisplay's entryProvider. +## Step 4. [Single feature] Move destinations from NavHost to entryProvider {:#step-4.} +Goal: When navigating to a route, it is provided using `NavDisplay's entryProvider`. -## 4.1 Move composable content from NavHost into entryProvider +### 4.1 Move composable content from NavHost into entryProvider {:#4.1-move} -Continue only with the feature module being migrated in the previous step.  +Continue only with the feature module being migrated in the previous step. +#### 4.1.1 Move directly defined destinations, such as composable -### 4.1.1 Move directly defined destinations, such as composable +For each destination inside `NavHost`, do the following based the destination type: -For each destination inside NavHost, do the following based the destination type: +- `navigation` - do nothing +- `composable` - Copy the function into `entryProvider` and rename `composable` to `entry`, retaining the type parameter. Remove the composable content from the old `composable` leaving it empty i.e., `composable`{}. +- `dialog` - Same as composable but add metadata to the entry as follows: entry(metadata `= DialogSceneStrategy.dialog()`) + - If you haven't already, add `DialogSceneStrategy` to `NavDisplay's sceneStrategy` parameter. +- [`bottomSheet`](https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/package-summary#(androidx.navigation.NavGraphBuilder).bottomSheet(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2)) - [Follow the bottom sheet recipe here](https://github.com/android/nav3-recipes/pull/67){:.external}. This essentially the same as the instructions for `dialog` except that `BottomSheetSceneStrategy` is not part of the core Nav3 library and so should be copied/modified to your individual requirements. -- navigation - do nothing +#### 4.1.2 Obtain navigation arguments -- composable\ - Copy the function into entryProvider and rename composable to entry, retaining the type parameter. Remove the composable content from the old composable\ leaving it empty i.e., composable\{}.    +In Nav2, when navigation arguments are passed using the route instance, you must first obtain the route instance from `NavBackStackEntry` by calling `toRoute`. In Nav3, the route instance is directly accessible with `entry`'s lambda parameter so there's no need to obtain the route instance. -- dialog\ -  Same as composable but add metadata to the entry as follows: entry\(metadata = DialogSceneStrategy.dialog()) +If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels](https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels){:.external} and apply the technique most appropriate to your codebase. - - If you haven't already, add DialogSceneStrategy to NavDisplay's sceneStrategy parameter.  - -- [bottomSheet](https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/package-summary#\(androidx.navigation.NavGraphBuilder\).bottomSheet\(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2\)) - [Follow the bottom sheet recipe here](https://github.com/android/nav3-recipes/pull/67). This essentially the same as the instructions for dialog except that BottomSheetSceneStrategy is not part of the core Nav3 library and so should be copied/modified to your individual requirements. - - -### 4.1.2 Obtain navigation arguments - -In Nav2, when navigation arguments are passed using the route instance, you must first obtain the route instance from NavBackStackEntry by calling toRoute. In Nav3, the route instance is directly accessible with entry's lambda parameter so there's no need to obtain the route instance.  - -If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels](https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels) and apply the technique most appropriate to your codebase. - - -### 4.1.3 Code example +#### 4.1.3 Code example Existing code: -| | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| NavHost(...){    navigation\(startDestination = RouteB) {        composable\{ entry ->             val id = entry.toRoute\().id            Text("Route B, id: $id")         }        dialog\ { Text ("Dialog D") }    }} | +``` +NavHost(...){ + navigation(startDestination = RouteB) { + composable{ entry -> + val id = entry.toRoute().id + Text("Route B, id: $id") + } + dialog { Text ("Dialog D") } + } +} +``` New code: -| | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NavHost(...){    navigation\(startDestination = RouteB) {        composable\{}        dialog\ {}    }}NavDisplay(...,     sceneStrategy = remember { DialogSceneStrategy() },    entryProvider = entryProvider {        entry\{ route -> Text("Route B, id: ${route.id}") }        entry\(metadata = DialogSceneStrategy.dialog()) { Text ("Dialog D") }    }) | - +``` +NavHost(...){ + navigation(startDestination = RouteB) { + composable{} + dialog {} + } +} -### 4.2.1 Move NavGraphBuilder extension functions +NavDisplay(..., + sceneStrategy = remember { DialogSceneStrategy() }, + entryProvider = entryProvider { + entry{ route -> Text("Route B, id: ${route.id}") } + entry(metadata = DialogSceneStrategy.dialog()) { Text ("Dialog D") } + } +) +``` -[NavGraphBuilder extension functions](https://developer.android.com/guide/navigation/design/encapsulate) can be refactored to EntryProviderBuilder extension functions. These functions can then be called inside entryProvider.  +#### 4.2.1 Move NavGraphBuilder extension functions -Refactoring NavHost:  +[`NavGraphBuilder`](https://developer.android.com/guide/navigation/design/encapsulate) [extension functions](https://developer.android.com/guide/navigation/design/encapsulate) can be refactored to `EntryProviderBuilder` extension functions. These functions can then be called inside `entryProvider`. -- Copy the function call into entryProvider +Refactoring `NavHost`: +- Copy the function call into `entryProvider` - Inline the original function reference and keep the existing function -![](data:image/png;base64,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U9PHmxLOX+NSsleIBhRBl7IhjmALlzWwAEPbxm1qEH3MmDFyySV/rJJuuql4cluD8E3GpXXr1tK+fXthktm8ub/zKb04FhtuueVmef75f8q1114rH330UdrcZPn0nT/PP/+CXHfdtXLHHXfIv//9r0W+5uowX+QLrOECdthhB+EdkPzucMioUaPkqaeekssu+7OccMLxcvPNN8nH+L4siN6byELVscceR9cM8dFEFv+onDVrlvzzn/+UY489Rvbaa0854ID95b777hWej7TzzsLjjzuebJOgcO60bdu26Hoef/wxFJEfk7/+9a9y6623FPVZWpX77befXHrpn2X11VdXCPjZK2ONIWAIGAKGgCFgCDQ6ArmQo2VmQp4W5WdUxz4pnSCb04QNrpK3FVGpB/NGZbRhsKwnNTQV+lHriXmyFbo8FtbWAQEbUk8EeAYWhAgnMi4VKTuLXM4Fm4hzTkmwpdwgVbWHy4L3qXocfT05uNMXU4ILO7URDyM9KWV9qIkIDtgjwXcYpowfk7XSBgRwSY307FJTOnE6Vhs6K7PoGibn77zzjlRFH3/88aJb4EKc+d1330WSfqu8/vq/F+I5YMOpAAAQAElEQVSs9ZuqefPmcYB33nk75o1pOAR2330Pcc6ft2+99aacccbpcu+998j//vc/+eGHH+TFF1+U884/T26//TaZF/0oySabbCKhqBVWst7662mciooKufPOO+S2226VESNGqHnGjBny5JNPykUXXSTjx/tXAwxcYQXho6nq0MQbFor5SOcDD9wv6bu7mviyF8ryfve7HbTAzn8LP/jgA7nmmqsXyrw2iSFgCBgChoAhYAgEBJwELqdZWi6IcU+98H/3YhMZKuBClgRW4BSzkt1Caud7jqVnDiNESbDRRgIb7fTzbPS/m/booofDWkNgESAQzsLU1PyfeC8mJytlSsHGYeRJtJFoZ59QLmEjLrkYFNoil1SHiOrmcBkTvagk4yXa6AA/7lwUtN6HehIM0OmuLHWUfB8NKbxTDGZ1p2sgKqDXiyd02kPWhaFxIKjjXe2x1DSZk046Sc488yzhnQqlVshHtOjD9xilfcJYvtOH+i222FKOP/4Euerqq+Wyyy6TI488Ut/zQ1tVtN5668kRRxyBwsDFctWVV8mpp54mvGMm3HUTxrLYwHWwD7oNNthA1089CxJBf9BBB6u+2N04wWfFFVfUl4+fc845SFivlT/96VL5/e+PEj62Fnzy+4Y65nRcHjvXvwKKIUG/33776/qpX3PNtYI602+77bbC47vssssVNx5HGpuMc0rgI3tHH320/OmSP8m1114nl6A/8cSTZLPNNkt5eZbxuAb2XiNSH8wPP/xwPS4ec4jHPnxehx9+BEXZfvvfqR8frzv33HNVl9/U9vgPPfRQ6dOnj4b58osv5NJLL5WpU6eqnN+w4PXMM8+omu9J2zzvBfXL9FlGbWPHjJFXX31V+fxm1Khf5I03XpeJEycKi1/hLqB8Pz4Kd8ABBwg/P7437FJ8D4lDr1698l0LZP4q55Ddd5dTTjlVrrrqaj2HeMcaz6l852OOOVYx7dKli5o6dOigMj9ffh9UiYY/iEAdiec0VAU7591jjz3ieS+7/HLlV1tttQLfoMj/jNdee20ZNmyY8FFKXjNOPOFEWX/99YN7k+2nTJkid999l1x44QUyc+bMBllnXfBMT8zPm+fURRdVfQ1Njwl8+jziZ3HsccfJdtttF8yZfrvtfht/Z5ZZpm/GFgS+H5HfndNPPz2otA9j+e8JFbyOHH/88XLdddfLDTfcQJVS/vekumsBsYvPAf7bg+8ir9NVfRdp5xoX1r9demCppi5rTg031hCoCgGzGQJLNAI+10Ly5ZM9PVbnnPbpxuXlZLENQ5V32qKhghSx6ETH5rQVbN41B447c1Kf4XFaT96DVr1rTLNWL7G1O7qIgpEh0IQRcA4nMcg59Fgnry8RC8nv4RLgJbbe15/0lEWcwwUicqQVolS50QkXDOeUwfhi3gjIHYvyXvQhR8LFCDZqEAad14GJ92COFWToxj6fiukRALMgPJiUvxOXkpomu8kmm2qBY/XV/KM4xVbJAghpzTXXzJjDWP5KGxMsJjbbb7+9rDJoFaFut92GaPFoq622zoxLCyeccIKcf/4FsvvuewiTtVVWXVW22morfZk3E3fGCf4sCHAdaR2TcupItAdfvtCdOiZTQZfu+W4vFrb48vGNN95EWPwZPHiw7LrrrnLLLbcKCw1p/8A3xDGHWKFncs+19u/fP6jkN7/5jX4u1Pftm00oWaxhceukk04WPoq3xhprCHHjcZx++hlatCtVJGESe8UVV8pOO+0sg1FoIH4sODCx5UvYzzknW1QiplxDQ2DOg1tvvfX1uDbccCOKMYXPa8MNN9RCJxNgzstftct/v1Vdj38TfNc5Ie98/MsTfyFbJT311JNaoKLTwIErsIuJd3JRaNW6NbuSdP/998vQoYco8a6xfMchKFKxuHDAAQcKPz9+D9caPFhYROKvHvJ7mj8myPze8BwZdsQw4a8jrrLKKnoO8QXy5513nhZtgy/78J0Kd5bxcVRiTEp/Hr1799HPiPrllluOQzPEz4jz8hwJ866x+hq6Bh7LBRdcKPwlyswgCOnPmMUM/rrokCG7C68rvGZs99vfoth3bo1+BADhFsn+5ptvotBzpvz9739vsPnrimdYQG2uoWEMez2PtCiUXEf4Wezwux2EhW/+kEL6/XMcM2jQyvF3g4/AUpdP/CEDfndYJE3/sSKM3XLLLXGd3U3OO+98LWjzDw4DBgyMw6S/J/yjR1XXgvXwRxJ+F+NzgP/24Lu47bbb4Y8tl2vxNQ4sCcdrAdfI69rC+LcrmVn0HK3LmtMxjDcEDAFDYGlFgPmWP/Ykx9KbLhJRzfQr1Ed5Wp6vMF/L6LwfW00/C2xegbTT3yhBRsJGGwnZLwNAbYUugGC7IdBUEHDOn6DJenim4pKROZGTEzjxK8Vl4zmXyAyZSKXGQw9HrgLVJAjpPRqNLhU2ctAREvReognO7CKiRIpE38EZu+ejVi+Y+cpoYNR5z8gHiHl5CW/XWmst/Z93Puo1YsQI+enHH2Xu3Ll61J06dZKhQ4cWTXx5RxF/EbG8vFz4Au9x48bJd999J9OnTdOxLHCcf/75MgjJCxV859G3334ro0aNoqg0evRooY40YcJE1VXX8C6SQw89TMI7iqZhPj62Fu7uYQFgdxQg6FcqVl2PuVi877//QY9h8uTJsfn7779THY9r6tQpsZ6JJwt0LG5RSZxHjhwpP//8c/yoHYslF154Ec0ZYsLIJLZZs2aq50v7v/rqK5ka3dXknEOxZeNMka+hMNcJa9B0795dmAjTlZ8LP+spU6ZSVKrP8Yc7mYjp+++/r/GqangX1n777Ss777yTHHro0Iwrvy9UdO3aVYszvEODcm3osMMOlyMOPyL+HvLOL37ukyb5X9lksWjo0ENlr732LgjLJJ13pPSK7vriu6J+/OEH+eWXn/VcatasOYoJu8oZZ5wRj+Vxk/hoIpX87lD+FufUjzhnqauOeGdfet7Zc2bLTz/9pI9o8vrIc5nFZRavS8XiZ7zXXnvhfw5z+miknvPTp6s7H99lkY/FV1U0sYaPqY4a9UuDraq+eNb2GhoWzvOI7xpjgZK6+fPn63eH3wN+L6jj++lYjCTf0HTwwQcL75ScPXu2fgcmTJhQMAW/J1VdC3gOnHXW2RLOgen4Dv3ww/cyduxYPQcYn4VYfl8LgkeKul7H64p7Q6w5Wrp1hoAhYAgslQg4cf64o46CslHuRTmQc7Ck9A5jc0wkUzqBToLOScGG9BP/v5JW0ykJwCk0hLokeopqA2OFLoBguyHQMAhkT7KqYwbf0HtvJiye8236JM+3eY9SbTauXkjUFZcZmLBHknalGzhiV3voVUg3MOg6ebFK65OrT0arAsbQHathpyptqOd1TIWkcYhF30QTuJSWi3BBLxiREmTJ3Fgw+uWXX+TCCy8UvpD7uOOPk4suukh+/XWsHjCTKt65oULU/O53vxPeUURxypQpcs0116DAcpicdNKJ8oej/yB8/w1tbdq0kZ132omsvPDCC3LyySfJ008/pTKbf/3rX6qjni+fp64qWm655YTFNeecLFgwXx555GF9efgJJxwvBx54gDz88EPCpM85J3wEJxTZ8mPW5ZjzYwT5qquu1GNIvzT/iiuuUB2PK30nEO+ECY9WDv9suOJ1zDFHy9HA7JxzzpEfUexgXBYJ6UuexLsstt56G7KaBPK4jzjicDnttFP1uO+8804J53b6EdCGwFwnrWHTokULYdHmnnvu0c/lqKN+L2eddWY8msdUl+PnY0wtW7bUOCyoKlOP5n//+29cWNx4443l1ltvw2dxktS0QMPPh+cAv2d8/I3vCRs69BA58cQT5ZBDDpYnnnhCv4dM1neKvv/p5e699z5x8ZjvGuOY4/Ed/sMf/iBXX32VhGLWBhtsGD+u+cc/XqzfKRYvGYvnHb9fpIsvvoiqamlvFN34GdHxf//7n+yNgtVxxx0rhx12qPz5z5cKY9LGAsK+++5LtoA4nuu75ZZb5Pe/PxK4nSjH45oxfPin6tsMhdj8x6TVsAQ2e9cDT35/ansNDRAefPAhwkISZRa3eB3gd4efw9lnn6XFJ9p4l+mOO+5ItkGJ5yKvLQcffJB+B/j9yZ+A35OqrgV7AbtWrVoJ7658+eWXZP/99xPe3TZs2BFyww3X47s4WUPyTkberatCXlOX63h9cG+INecdgomGgCFgCCxVCOSyGZseO9M21ZNRjfj8KyULNvXRPjToU/GYwlFTlOJYZFK5HUSOIwlmFd2gRO91Yu/oAha2GwINhICrRZzgG3o/lMlXSHqpoeyJkpRsslHoVqgRXlBw/juYSPQqTnCigR0cncMAyhmiEZctdjB7FzDqEykxX7jQqFob2sDQlaQXJupUEIocE0lS5QZHjqSP+vtFUEQYx9mVXxhNz5495d577ytJt912e6Msg4WhO+64XUKiyknIP/HEX8kq5T9+x8caaeCdXDfeeIPwXUaUSbzD6JZbbpZwhxMf5aK+IWj//Q8QFs8Y65ln/i6PPfYY2Zgef/xxFNKeVrlZs+YyZMgQ5fObuhxzfozayizSbbrppjqMd3GdfdZZeieXKtB89dWXcvU1V8fvDQp3Q8AkX3zxhdx+++3CO5n+8Y/C46ZuVHSnXLjzieMWBT2BIk+6mBnWUJ/j5+NRIU5DFLpYYOUL6JmIMy4f4+LjUnzf2YMPPoSi70US3v9Dez7xe8gkm/pHHnlEf/mRfKAHH3wA58QbKrIgsc8+SdFo1113kwEDBqiN5xnfNcbCkSrQ/N///Z+89NJL4ESLYXzHkQr1bHbffQ9ZbvnlNconH38sl132Z+VD89Zbb8m1116jhQfq+Agy+2L03HPPYo0vxibe0cNHNQOeoZgZOyyBTH3xrOs1lN+dcB3hNZaFre+//z5G+JtvvpGHHnow/hz5mF9sbCCGP7bBa3z6e1ssdKlrAQuhfKyaY1hwvfHGG8nG9Nprr+EYHtbifTMtnO4S29JMXa7jdcW9odacXr/xhoAhYAgstQgg/wrH7jTjcoJOwpbTDCwnaZ3o5kRTNadC1DBfE9Wnwgo3+mZcqURszWeVF4xzIIk2zCku4n23hNzR5Q/GWkNgcUYgFLic40maE+fY43TGmY89lr1WIEu85WKuFBON0g4XFQyIwhcZQCc60ITLFScnmyH6uHgNWRcHT4xHG+YIPVRF9sifQ0BeApPn6cRlNQgaNLF3tBCsOuvbyBL/As4EsSpqjCXwUZH03UhhjpdeelHvSqGcLp7wHUF8Pwz1n3/+mfAXEsmnicWIM888Q0455WQ5//zz0qZ68csu69+DxWLa3/6WFOLSQZ944i8S7kzhY4BpW+Bre8xhXH163iXDOxgY44UXnmdXQHx0lMUPGrp168ouJn4eF110odx9992xLs1MmuQf/eTjY+nCUNqnsXk+NvXkk38rOk19jr9z5y5xzClTJsd8fZhXXnlF10prUgAAEABJREFULrjgAvn3v/8t/D6FWPyu8/1ZRx31B7nrrrul2B0xy0cFIxYsWWQMY9P9448/pok6df379WOnxLvzyLBI/OSTT5ItoLvuulPPHZ4/fNdYgUMdFOFcyOH69iwKVcVCfPjhh1pUpa1v337C4iT5NPEOnGeffTatUn7UqF+E5z2FTp06smsQ4rvETjzxJClFBx10UIPMU9sg9cGzPtdQvoeLd1RxvfxVWj6iSz5N//nPf4DXCfoduummbBEp7VdXvtg1Pz9WVdeCcA6wUMW7IfPHUub1jtdp8j179mJXQLQvrH+7GmrNBQdhCkPAEFjECNj0CxMBF/Iw5F9hXuZbJK0/BWXo4+TMKxy7PB2yXGq1S4VVHf6Xx4fVgapCQ4HkWf5/kXdi4EgPE3dKVugiEkaGwEJFAJcEnr15czrHUzIoWYxK/JzzslojtyIh1FzY4ORXZw5M4qiq0DnSwDcMizSFHRygDHGwREjcvZ4ciVLwEV4koVAZvaQ3TEmzUtDThwQZaKBN7ZE+pVlkLO+GeO+996QU8Y6Lxlgc7wooFZfvYKGNf1VnT+Kvz/FdPuTDu47I5xPfv8W7C/gOoHxbXeVQ8GBBqFiCx7i8y4B28vxlOvb5VNtjzh9fF7lP9Et/HLveeuvrXUMXXniRXJhH/fr5Yl6zZs1lzSK/2MjH5vbccy856aST9BcXeTfEI488mvHlI3OcZ2ETH+MrNWd9jp93DIW4vEMq8PXteRfdNddcLXwM9Oabb5L//ve/kp6rd+/ecuSRvxfehZWeK7zTi3d15X9+QWahTP/nCQO7dE2KlnwUGCrhO4l4hx75YsRzh5QuwhXzq6kuzDt16hR5++23Sw7jnMGY/iXRoJs+fVqmMBj07MM5WV7ejGKDEN+LxB9bKEVbbrlVg8xT2yD1wbM+19A+0S+Pcr0ff/wxu6LE6y4/SxaDijrUQzkqunu0qhBVXQu6de+mQ3l+8JdnwzmT3/P8omOpwmltr+P1wb2h1szjWWzIFmoIGAKGQGMhkJd/OccELjuZQzKneVvKlzIp3zMrB8kPdBTJksj7qpbngi4zv1dyHDkrdClU1hgCCxMBJ865eEL+D2MspBjnXMbPOadWLRIpV9MG4+KxOcSs4Tgdhgbu0XBwYc8FRuhBe7Iu1Xh74uZlXqBgpn+kQJdyIkuCVnf4+glUShpM5i+WdIjU0EUchqT0QdmIPV9mzXftlCK+u6cxpq+sqCgZttj3iu99CQN+/XVcYBu9Z4EnJD7hjq1SkwY773zgoz75frU95vzxdZHTBRq+KJp3DRWjZZZZJg6/zDJ9Yp6P+lx++RVy4403yWGHHSZ81I7vlBowYKDwDpHYcREyxb4vYTn1Of6ffx4ZwgjveIyFBmJYHH3xxRfl8ssvk0MPHSq33XabfPnFFxqdd8gNHTpUQnFrmWX6Svg1Or7MvthnGHSh4NihfXuNxSbE4cv6KS8sSuadXuWU48cn53R4UXh6QEVFZVpsdJ7F9qqIfyBo9EXkTUCxPnjW5xravXsPTq/v6vv888+VX9hNZWX6H9jis1d1LegS3aHJu5jDuVKsD3+oaNu2XdFJansdrw/uDbXmogdiSkPAEDAElhIEfN7Fg83+O1Ls3wz6OmRj3DnCEzXOs2xTYVIsLPQhpdhIhAZ7Lg6r+WQq/5PIkhO/WaHL42CtIbDIEHAuffbi0oATlhcNUliU8tA7l/im2Oi0Dt7Fe8Zwjnd0iaCT0hsuD5jL28GDiUXwwmKVcB0+lvdQQ9RQQ/Ii56J3Ms7rk9ZbgwwEAut7hOLavRC1COoc5te1RLpUVxAjZVua2Xnz5seH36ZN65hvbIZ3i4TPkMWHquYL9srKSlnYBYVS6+IjX8H29ddfS00orJ1FvnPPPU94R0I4Nv665VdffyVvvfWm8PG2N9/8Xwi/qPoq563P8fPOlQULFmj83r16a1+Thr+Kt+OOO8nWW29dE/fY55//fE5OP+N0vcOLShZMN910M7Iyd+6c+JHEqVOn1uhzHDFyhI5lE3Bo0aI5xYVGYd5mzaq+24rHGhbFAlPgF1XPH2vYe++9pBTxhygWxdrqg2d9rqH8EQ4eL4uofMyW/OJGATs+uliT6+C3337bIIdYH9wX1Zob5MAtiCFgCBgCTQABp3lftBDkX/ifKRWctlGDfC3isl2sj5ioS4fkAM011aYNVX6aRISOM7pU9gcZu2iwjKNwmXUudE3EXw5JYpshYAjUC4FQAPBBHE5MT5Rpcy6S0QfZ29h6yp7aXufbyIKrh3MOtSYvQ/Tmoi38sPMqQj8Oo5i4JlKw0a+YnbPR5gtPHEdNvIxoiNepABfn0KgQNRCduEhIdalh/kqY2Bz8SYmmrlzjjeNnyejNmhdPmtdYY00JjxnmQ8JxdaFffvk5HtYYd9fEwfMYPqbCYhfV1SV4wc5CUfpRNI5dVDRx4oR46ief/Juceuop1RJf1MxB/CXFgPVPP/4oV199tex/wP5y2qmnCl9mfu+998qsWbPpWm+qqhDCl7ZzAuccu1pRfY6fE42MikXLDxgg/OU06qoiFgf5XqdjjjlG9t13v9iVd8Ztu+22QlpuueVifTGG70AK+kGDVlaW36fwPRw9ZnS1nyE/56uuukrHsgl3G3bo2HDvsWLc6ijMW93df/xRjBCrqkeTg8/S2tcHz/pcQydM8O/iI+6DBg1iV2Piv6PBuW3bNoHN9J06dYrl8G9HrGggZuqUKRpp7ty5NTp/zkDRWQfUs6kP7otqzfU8ZBtuCBgChkCTQYB5nENupQviP0jR/0uGVIz2YFYfNKqjg4MQ7apLycgI1UKVhiSjGg4UHzLWxYxwo6S5lLqyoYYWT1xmnQtdPoS1Sy0CduANhoBzqEzjbNSTldWlKLJzyQlLG4mm0JOvnqIY6HRcFDPqdDhM2oeLjRegTTnx8uH1bCkFoiyScpV0nESPeOHYMJR6dPDlDhuFiAAFlRnSC2PQqB81ZCIlAwriaM8VpGyRS1PrZs2apUviI1TK5DXrrLNOnqb+4ldffRW/pH6ttQaXDLjffvvLySefIscdd3xJH96VUNJYxDBp0iTVDkCxY6WVVlI+v+GL2FnMoH5y5E9+UdOoUaPjJfDRxVjIY1ic5ONxaXX6XUk33XyTpAswwa9nr56BrbIvhXko3rCYlX4PUAjGu8nSSXDQ17Svz/FzjldffY2d0u5DdtdfJFShRLP33vsIH42i+ZNPPmGntP76G8hJJ52stPfee6uuVJP+HKZNmx67sehKoV/fflLs8T7aSBtuuCG7DIVHA1u3ai37779/xhaElfDd5rlD2m673wZ1pncO16qMpmohzNu2bVvZe599SjoPHry22ubNmyfFXvStRmukPnjW5xr6yy+/xOhvttnmMZ/PsMDL788BBxwYm6ZNmxrzAwYOjPnAtGrVStLf+aBv6H78hPEako8Ab7HFlsoXa/g4I32K2eqiqw/ui2rNdTlOG2MIGAKGQFNFgJmXYHHFMizHHKxYAgf/kP6R9X7k0hRFjgO72KgqbagiE4iyiP7vlLqzoU0ymxW6MnCYYAgsTASSE9I5h5PVYXIS9LhYaGEKmvy7laiqPTlxOgix0SM8Wr97DXnvwTJRQtAnDhC4Bz/f05yOR4/4okYjFN4TTLR7fxojogOIkp87OKL3SjDRDj8hXkIm0mkHR+zKookum+Ca5s5Hp7gyvjR7jz32IBsTfyVqhx12iOWGYjjn8OHDNRzv/jjyyCOVTzdMXpjEb7PNNjJ48OC0SebOnRfL6fc2xcoqmPASbT6+N/SQoUU9D4Gedhrf/+ADdk2Cnn32HzJxor8bg/gUe9E8i0nnnnuu3HrrrXLzTTfH654xY2bMt2jRMuYDwxd2rzJolSAW9DXBPBQRWQgbOvTQTAzeBXTU748S5/LPl4xblUJ9jp+B+euGY8aMISvL9O0rV199jay22moq5zd8EfxWW22lahZsXnnlZeXZ8Nfc+E4u8uuuu54wmSafTyyW7rLLLrGaSXIQ3nnnHWWZhA8bVvj9p/H000+X88+/QB599DFJ/zLgSy+9LOExqO23/52waEv/NDEmzx1SeBdUsIdHONt3aB+/KyzYqurT8/4O8y633HIF7vzcQ5Hzi0X0/qeCRTVRRX3wrM81lI/VTpjg7w5de+3Bwsdz8yHi95+P7PL7M3DggNgczh8qttl664Lvz3HHHiel/mjCMQ1Fr7zySnwOHHDAAUXfMThkyBA9fx544EE5++xzGmTq+uC+qNbcIAduQRYbBGyhhsDSgoD+32Qq39LjViWaYnqo1QcNczMS2NTuHXRo0sR2VcUSfUk+W9R8MuOQEcQKXTFwxhgCCxsBf6L6WdMnJvTckZg657RmBNG7Ra1ziSbFRtYSXTJEUmwR58TqnJ+/0Ik+uFRh2XBJmaGgRDP7YgSbHwMmbcdQr/GtmlKsyqkGs6ckzwadwxGSvLZptvzVuLAyFniYEDCpPu200+Xii/8obdu2DeYG7Z977lkJCTd/kY7vj9pyy620qHX00UfLEUccET8y+dHHH2Xmfu+9d1Hsmqu6jTfeWE444QQ58MCDZGCROwzUKdX89a9PxMWitQYPlmuuuVZ22203Hct1XH3NNbL22mvrCP7q4wMP3K98U2lef/11XQrvnDj//PPl9ygerbfeevrurUMPPUxOPvlkTT75yNDUadPUlw3fUcWeRLz4GbNAwsIYY5xwwolS1SOHNcH8gw/e1xdccw4+KskX3/M7dfTRx8gNN9wofGSQtvpQXY8/zHn77bfF71xbbrnl5IILLhR+z4cNG6Z3KR1//PFyzz33CAtUzjk9nscff1zS7/jh3VihaMVCFc8VEh9lZPHxt7/dXu/2uvTSP0v4Zb3vv/9O3njDf3ZcCx89DYXBjTbaSL+HfJySa9pxxx3lrLPOls0334Kueg7yPUQqoPn0008kFIoZ/6KLLpb99ttPBqFQye/yH/94ibBIDVeZMWOGvJIq0lE3cqR/MT/vCOPYgw8+RHbeeWeaqqT0vCxQcyyL0ZyX7zA788yzZK+99tIYfKTs4UceUd6a4gjUF8/6XEPDedSsWXPh47l/+MMfhHeJbrHFlsLv8vbbb6+L5jsK//vf/ynPhr/yOS26rvTt20+/t8NQqD388CNwjt8gW0bFYfo2JvFOwc8++0ynWGaZZeT662/Q83fllVeWTTfdVI455lj9N4FFd74zbuzYserbEE1dcV+Ua26I47YYhoAhYAgsagSYU5EE+RXSNRHNTtFFu785AxYXKUp0DuNFSVJbTjUupRHV+Darl3ijnqQKrXiRizUUrNClKFhjCCxiBML56S8UXIyThIecPW8ztjAWXkX2HHQkXJJ8F106oC66R070UlablCfliNAhH0XglJnjlLwOLsqEXoWCBgdHB+3I0AECO1AoXoH1O13yDzqSw6iCMX5kk2offfRRCX/db9asmXqhDgsAABAASURBVLBAsd9++8uWW24prVu3lldffTX+y3l0eA2y/nfffVceeughLXY55+Q3v/kNEqzT5E9/ulR22mlnCe/IYoHhlpuTO5M4OZP38GthLMSxsMCEe5NNNqW5SuKdODfccL3wL/N0ZGJ05JG/R5J2I4pGv5dBKw+iWljMeOihB5VvSs19990rr7/+ui6Jn8+uu+4qF6HQwaISiww9e/ZS2/jx4+WRRx5Wng0fVfzuu+/ICu/e42fMX1/kOMZgrHHjkl/LU8dUUxPM//Of/8inn34aj2IRbZ999pGddtpJCz78LEORJXNdiUdUz9T1+EPkDz74QK677tr48+f3hwn+kCG7C+/w4x1SAUO+6Jp3kT3xxF/C8Li/9dZbJCTajLHllltqcevPf/6zFl5Z9GIRjAN4F96NN95INibieeONN0h4TxO/h3xE9+abb9Ekncm6c06vsfw1x/feey8eS+b666+TH3/4gayeKwcddLBcffXVwu9yeNyYhWQWavldVseoefvtt+JC8aBBg2TfffcVPqYZmavs0vOyyMYCM+c95ZRThXcFOueEd8A99dRTki6iVxl0KTbWB8/6XEPvv/8+eeONNxT5Fi1aoNC5ixZ8eRchv8vU0fjqq6/Iv//9L7JK/C698soryrNhkWnIkCHCu4EHDlxBz6v0dzXceUjfhiZex7///nsNyzt7ef5egz9csEjMYjGvaTTy34rHHnuUbINQfXBfVGtukAO3IIaAIWAILGIEmFeRkqQvyrhyfmGOuR/+P8RLqZZ2UkrlyGd0+H+uUDhTIx1IiZPmQSqyIfmVeA6+OndmMJRihS5FwRpDYKEjEE5N9jlxzukKnMPJrmezinGTr4JbbKuaYVyS9wpxcl4s0tKXVlIRs9AeETu6sY9doUhNkjHFPrg4BR/VYQwdtYuYcMGD3emcYNI7AHBpWXlgp71v/AXZ843V8q/ujF2X4gELPpdc8kckpV+h6JT8GiILQv/6179QALpek23Gz6cwb2UGx3yv0jLvauEdNiyAhFjBm/Mzybr00j8FVab/858vlXfeeVtmzkweyUv/9HvAIj8ug3z44Ydy1VVXCoseLGZQF4jzslhzzjlnCws3QR/6EK+uxxziFOtzucpi6gLd1VdfJX/5y19kVOpdO8GJd9K88847ws/0iy++CGrtzzvvXD1m+qgiaigzeeUdB5EqfodakNlXhzl9/vSnSxS39K/tMdkd/tlwLcQE/Oibplz0HSplT/vW9fhDDCbiJ598kjz77LPx3X3Bxn72nNny8UcfyQUXXCB33XUXVQXEu/3OOutM4WNgLCryGPOdWMx66aWXUAA7UUJCnvbh3TFXXHGFsOf3Lm0jP2rUKHnggQfktttupZghFqcvAdav//vfMj26wybt8NNPP+HcvUFeeOGFtFr5t956S2PyMbSANx9vDI8cVlZWqB+bigr/S5XkSWHef/3rNZk+PXnnGG0srLGQeeWVV2SKrLSRwmcceuqWJKqsxD8etTyg+uDJqepzDeU18G9/+6uMHTuWoTLEuw0fffQRyS/Q0onF5scff0ymTJlCMSZ+9vyupq/JsRFMGp/585PHz2HK7OH7UVlZ9fWQhfmLLrpQ+F2cMmVyJgYFru+FF1+QM888Q/LPrxC7rtfxuuJenzXzmIwMAUPAEDAE0ghE/+460SyNOVeO/z8ZqaXERr9CEwdFORzZlANFEtI+0Ym0waQiojrBRlHnpifk1G6PLqbAMNYQWHgI8KzkbOxxcvMEpQhyjjoRtrxosBcRITnnpZQ71TUm5zBXtd5+Di6A80RSahQvJCQUrKj1LDkQvLGDER0vIphSki1ljJXQZWLEhmiClBxYLKxwSE4QST0cOJIKjdgcdNCB+Iv8TnLMMUfXaRYm4aeddqoMGzZMrr32GmHywJjkGXDIkN00fn7Rad9991H9BRecT7eidOCBB6hPqV+94t0qLDqcg8LSXXfdqY+NsUjD+a+//vr4brP84ExcLrnkEuEauC4WYW66Kblrhr9Ut/POO8lhhx2aP1Tljz/+WC688AItQtx0003C5I1Fmr322lO4lp9/Tn4ZUgdEDedj3PoccxSqoLvuuusUK8ZnIaXAIaXg3WZH/eEo/az4qB3piisul6OO+r0WuYr92h0LLzxmfia8C4eJLO9MOumkE1EUuV5uAn6cm1RsfHWYc3n04ToOPvggufzyy5SOOOJwOfuss2TUqF/kuOOO1WP8/e+PpHtM1X1esWPE1OX4o6HaMeG8447bZejQQ4QFq1tuuVkon3baabL3XnvJeeefJ8OHf6q+VTW33XabfscOPXSonjssQFLH49lvv30VU94FUyoG5+D5xnP3Jv0e3qfvV2Nyzs+ShYhSY3kMV19ztRwJLHmnCL/DPA5iTErfiZMfg3dqHnnkMDn++ON03aeffpqE7xwLvPwOkB5+OLkrMMTgvNdee61eb6655ho9d3hnErHkcYT34AX/0BMTxiRWQZff87Ogz/7775dvapIy7+rjekmXXfbnOq2xrniGyep6DeX4+++/H9f9I4TXz3vvvUfuvPNOPR8OOeRg4d2+9ClG/F7wGs3rIL8Dxx57jH4f/vvf/6KgfZWe48SE15wwnt9N6kj8Nyfo8/vwPSl17U7789zid/Gggw7CvFcLj+Huu++Siy++SI8r/27gMLYhruN1xb2uaw5rt94QMAQMgaUVgfycKpcCgjztjjptyIhmYlLnzUctHE69J6SCiZnJZmpuGqhaEgpdPBYjQ2CxQYDFq/zFOpc+O3kCwyNSUXLOC8XGwrPqHVcCjnOOMRhNRFkptdGHvt5OyXNsKUU2sBonEmnNVKYiO+f2ejqilh/pvT9bKtgXJ4wQh//UClfPOhXzG5qp4xgS+cWBeHcB7+IqdYdJYx4DE8a///3v8vTTTwnvSGLBpKbz8Q6VN998Ux+bqemY4DdixAh56aUX5cknn5RSCXrwbYo9PytiRmKBgp9hdesktq+//m9NZJ9//nkpVdSrKk51mHMOJr2kmqypqrmqstXl+PPj8bvHO594h1ddH7dj8spzhwU43uWVfqdW/nzFZBY7/Pfwb/L88/8UPm5VzK+YjsUE3pHH7zCP46effirmVlTH7z/XXdv1MhiPmcU0zsvCGe8Opd6obgjUF09+j+t6DeX1k4+b8gcbGKemR8C7Y/kd4PeopmMay4/XNB7DM888I7xrk9egxporHZd41RX3RbXm9PqNNwQMgXohYIMXIgL5OZXzyZhP77AOb3exDJVQRwqu1DkIIVeDA1VKTls0MQM+cqAKqSwVKXKIFIkaUBsoQo+lgLVCFyCx3RBYmAg45/Kmw5moGlwO9Ez2drLOueREVh8R55zUbIviwt85jEFA7AJOtCdTECgaw4sLWOec+iduLmLRY2ccukbKqIMBHIbrPKIRqKPGSxxHjeRtQCCrgZPD+FjvsubiUo2cig81rSFgCBgChoAhYAgYAostArZwQ8AQMAQaHgGHfCxE1byMaZ0LGvRpHiJ3xzH0owDiOIc+f6dedbEvvUgoWMHgOTCpPXaNdfQiJRYrdMXgGGMILBoEWPTxMztxznk2ank3FE9X9pEKxSNqglRVH2Lh8sFJothhNFWFoznGE/04L/tCP6+lp+eCR6LhdJS8JetFHVbFLiF11ibRYViBXzEdRkCNlrvnnDgKRoaAIWAIGAKGgIhhYAgYAoaAIWAIGAJ1QqAgH8u/00ETS5+DhQl0TF46prrgoD0dXF7Wlo2jbnHjYi7LcAwpsTdKoWuNNdaUc8+7QH67/e/018OyizDJEDAE0gg45wqKVywwOefikx6sOOfSwwrkjDEWsid8rK6WySG+SHZGwZaLCB2slLI+1MCW6rJ22OI9ZYG/Xh/VltKrnGrgx9o+PUiJJSsleuMMAUOgOgTMbggYAoaAIWAIGAKGgCFgCFSHQJxx5eWlmqIhNwzjXeC9IaihdZ6POuZ1nkLrzUHiNBpCm8QWDwdTLIfkuEYpdPHnkQcOHCj77be/XHXVdXLEEUdawSt8LtYbAikEWNDiicyTMaVO2MiQnMCJyY9N5EKOVwSc/TBEYXBxEQm81GQrcGY8EgZjUTRzFkjRHtnQway6xA4lNVHH46YYyKsTb9V7pbLaqIzCIITYUyeKJVhEHP4r/IuB1HYzf0PAEDAEDAFDwBAwBAwBQ8AQMASWWgSYV4WDZ8blIOTnodRBHad3cR4WG9Qq1JPAeEVoM34USDBiQuabSO0gcIcCAltKjKN2Fdh4C9PDRil0hZ8P5lRt2raWTTbdVE47/Uzp0qUrVUaLPQJ2AHVHwJ98YbxzPIkD4drAsxJG56hLZKgK7vqirmryMWIfxObs6GJVIaMeUPux2YsYbTCF3bsEKdvDlWZSYoASOy9IXpeyplgctTej5fwOFzOwaXXQqFpSkhO/6QXUs9YaAoaAIWAIGAKGgCFgCBgChoAhYAjUGYHswJBzUeuQizHF02TNUZMiGkiRysGXFIlxx/zUBYlClDDWLKcLIzlR4EUapdD10UcfyoMP3C9jRo8Oy5Xll19eTj/9DOnbt1+sM8YQWPoQcDhknoTouOuJTAaXBvDO0U7Z+zgXZOpEnMvKUpMNcenGiM758VFHdYrUI5LJi3hvibasFClTHceQoIIrORKODIpoj/TooPBWMOrCC5krmNHhMhf5OfXUJtIon26C3uXFSfsYbwgYAoaAIWAIGAKGgCFgCDQIAhbEEFhaEYgSL+ZwCkGRBFNtDlb19XldxEIZdjpoOugVXvR8yOl0UKRKdaqOcl0JvuK3Ril0MfTrr/9bzj33bHnk4Ydk3rwFVEnPXr1kv/0PUN4aQ2DpRSB19vKCEJ2czqX0OFF5N5PENhHncHGIZKnxhtMf40ScOOdwBcmh104KN9hjJeeKhRST83zUeSG0qfGwczpanDh0JHTYqdeLHvj07uCHYYkqIyTqQs47upSB8R3ipVTGGgKGgCFgCBgChsBCRMCmMgQMAUPAEFj8EWBelX8Umn25PG1enuqQi5HUy7HVUWSQjPou3TJHlJQLbRwWh1UbNbR40jGxSh28AW2jFboQW/fXXntVXnzhn8qzWWWVVYQvqydvZAgsdQjEZ2rqyOOT0+u0wAXWn7jeyGHUqw622u888QsvUz568Whq0yZtpwKx2EHNdaGrcoc37FHrO8jcGYREvgjRRMozFTuKTNg8fxMNAUPAEGhiCNhyDAFDwBAwBAwBQ8AQWCwQcChYpRfKvMtRkZcIUk91oDhnyxicFM9nIyfH0dqQ0bpXLMVM5KseaCiSwKb3Ri90cbJnnnlKvv32W7I4MCc77rSz8tYYAksdAkXPbH/WspCVxiPv2qEm6pzz/qqosuEZX8w30dEjCRFJ2vlLE+dL7ORojMaDJUeixVMkoeNYdF4dtYlMDgH08uWN0YxeYJs1U6PVf+c41ovaRiLdVUbjxCFyWgOl7YtIWhNsAAAQAElEQVQBArZEQ8AQMAQMAUPAEDAEDAFDwBBoKggwR2NuVd161IcJYMqRY1MiWGiYojmw8U4FBHYkZHGQ4l1VsT+lWNDcEGmfKGlDu+i2UApdnInv7AqJ/MorryydO3em2sgQWOoQCOcBD9zz/oR0zp+0zvme9kAOOue83o8Jlqp6+jM2ibwIQ3C8lyRvi7R0iiyRJpJCl7pAwYHRg0WvNlSAYIouUxCCA5RF54eeLk4cOyXMon1+w/FpHeVklLeUGuut1hoChoAhYAgYAoaAIWAIGAKGgCFgCNQEgXRuxbxLs7tUzsgY3odWSp4cczsHXgeg1x0CdmXROPqAqCJBFe/xFDSQYksOIzTz9JocOzaOjNJCK3SNGvWLTJ40RSdl07//suzqTRbAEGj6CPCkS1bpXHICOkee5H1YtAmezjmh7JzvydPmHP3J1YQ4NvLDFHGRvWQIOEXunIYSe6+iRM5J0MXxqI7KWuIgRMQOEvaI0xARD228q54Xq4iBwTmsHTGdBoQimsw5ByHZnaNfIpNzGEMib2QIGAKGgCFgCBgChoAhYAgYAksGAnYUCx+BdF7FbM1xCVFuRtaF3MtR8uSg0+JXPMB5A/TcIwHZHh1EVUjrxG/0xegwB0WSGumfl//pwNgBXrnG+dVFRC66jxv/a6zv1at3zBtjCCzZCKRPuvSR8iRNyyLOwTec0CIqs8DlHPTiN8qeK9Vm48ZDI4aRUlPkBVFrRpf40kZTXnyqlLyd/iRctbirJd3QC5ettCriaSFFIjonvIiF+Rw0KIZpcGUpRIzAU+KN8UmxwhhDwBAwBAwBQ8AQMASWbATs6AwBQ8AQaBQEqsuraCflT+7yMjRvD7mdl0R98kfTx4moTZDzgYrsUXqrN4dkndzCLXSNHTtWwtate/fAWm8ILKUI8OTFKamFGxR0tIesaPDkxgkfdOid8/7O+V7dijb5dh87FMgYueiwdFmKTqQCR8YGRTZwkUekgMTlkVIaaCFhBxPtychk2ly4lHkQcuzQRCOC0QWGek7EHpTyhIeDxnZDwBAwBAwBQ4AIGBkChoAhYAgYAoZAXRFwyK7yx6ZzL9rUJ6VEJos0L6Wgk8bxuamK1TQOdpIOi0OpBhbs1IF8Skg9BKi5L7RHFznZ+HHj2Cm1bdtWe2sMgaUdAed4Uoo4xz4X9eRdxMMmKPqg2IUuqliTqwnl4JTTOM458FXttOe8A1lQ8SGRDzrs3l/gjEuZCpGSGqwaKiogYYdQuMd6XPRCDOpATuOmhjhGZLxIl2IjjXWGgCFQGwTM1xAwBAwBQ8AQMAQMAUPAEKgCARat8s1Iy/JVXk7lZy4/l/Me0LqIY8cBDjryWaJFNTFDKRGUc9Apg16jeGGhFroqKys5u5EhYAgQgahwRTYhnqmUcDlJ2Xm6OhdsIs4lvFS5BT9EiOJVPZT+oMg9GpKaAQZKDAI3sl7jWxEosQs2ahxl8CxPaefQkkJBCyJ3+rKX4E8FSfK2SKchaCJTuEha6k0WwBAwBAwBQ8AQMAQMAUPAEDAEDAFDIIsAUzJSVhtJzM8iFhltxIUuGkWfiM1YMrqcZoY5OJCE+adwIAnK9B6r6OmFhVroSq/F+MUWAVt4QyGgJ6sPFj9WGBdt/Anqrb4NPhwWeG8p0sZxgo13S4leGgpMkt54cQBF00dd2gE8tAiCXbgWKMThP/Za0MJwtXlF1Do1UaCNfZYwSBVRr+4Rr/rQ5HSmXBDZYxFOtRQ8FV5Uvd5aQ8AQMAQMAUPAEDAEDAFDwBAwBAyBGiOATMt55yiRo+QcW69mWzL/yrrRVaIwyvsmhznidNGroMkFTmNQInllZnqqNag6qoMVuhQGawyBRYNAKFg5l5yU+StxzuE0F3HOCTeewxFLsTgFBzpHHlTxGhCJ4qMFKd0nFvonEn0oQctgEEN4aCDR5rvILJkLHs3e0TuFFUDnwDto07uDLi17PinYqYyxxDAzDwzFx8JguyFgCBgChoAhYAgYAoaAIdAgCFgQQ2DpQCDOtaIkDykYilVsk+OP86+QIMKkuoybgzZSkIXkdy/4lposlwoJox9PnXpRJBOtLZTLrNAFqGw3BBYVAs7xrOTsPENFnAuyRBsuKziLvTVSoYMKbQ32OJ6P4FwS32vyY9CetRSVsIBUqPwguPB5lRPnGZS8lAmiClFk6MiRVJ1qcPReio2e8S1MGOviOSBHezwukq0zBAwBQ8AQMAQMgYWIgE1lCBgChoAhsMQgkJ9vORwZCV28x/lXKklUXcYxh8zNibrk4qFg1BN92Gkk+bKVo9qL5EpQcFDvhfuri+kX0FdUVJRYoKkNgcUVgXBy1WT93pd3I6W9C+XEmm9LLMU4H99bcLJHYvUx6Ah/P7B0W9SFY1ND4OM1YFJqz3pLqH95XRUtQ0RDMl6q0yajpuDEsTMyBAwBQ6BJIWCLMQQMAUPAEDAEDAFDYHFCoFQZKuSWcdYVM6mjY6pGilQaKyV7tas+c3P01IaMUhIG+kRQ20K9o6tX7946KZvJkyaxMzIEliAEcILV+Gi8r1azdUyQnYQLBtXOOXHOka0lhTF5Z3y1UTAul4yBJKRkWCTBJeWW8vF2Ltnb4ZgM9iV5lb1fGEj/lFE9eBF0cCCpQhunbdL4+Plah3Ecn/gZtxggYEs0BAwBQ8AQMAQMAUPAEDAEDIGmioBP8HR1ziHjAlFgRuYCk/KhSkmNymlDf6RryosyqpFk4wBSovFc4hdbyXDOaC0hp1yoha6ePXv69aEdN+5XtLYbAks5Asm5Ghe4nNOzVZxjj1M1552c83JALE8M6rw+GgNnnv80gmVXhDgPiA7sIg+wERc6xOQOCprEJ+KiTiQ4hT5o6JDowtokbDA7jGWxiqRqpy20vteWa4UG7iqGJh4TFNYbAoaAIWAIGAKGgCFgCBgChoAhYAjUGgGHfEsHae4lKunNGUziokTMd2hjHyelNnWBq3+6h4wDiz4eAh6awvGxQ2zlEnRBquE477NQC13duyeFrtGjRxWuu7Ya8zcEFksEUIbRMxKL17McPXbn/EkJFjtOdvjoBQQS9zTvZbaliCe5t3EcieFJCOsNBW1qfrCMQMq6FWoSOwZRgAt2cv6aE190oIILjh4M9+AlkZ8kW8YvUsM9GRvp0BXTQW27IWAIGAKGgCFgCBgChoAhYAgsSQjYsTQJBJCW+XUwuUTe5oVsm8nR4gGRD2WOI0UqQUaoeSptwi1ljNnYSAfJTJ81Lbx3dO2w407SqlULXdCMGbNkxIiRyltjCCx9CDiclC4+bBahYiHFOOdiP+dcylITNvHnUBJH6cWDTIbyrgqRjWNIkZjqcNnCEMbK2qGkF6YO+khDrRLHiMBBks3rEjlwDn6kIEPkrmUz1UXBHQQSunh36hmLxhgChoAhYAgYAoaAIbBEI2AHZwgYAoZAYyGA7M+HTiVumm/ly8zBohzNDxDkblC4IPk+jufFuNUcMs9XjQiRTJU4JDp45Q1eKHd0LbvscrLLLkMwu9//+583pKJigResNQSWcgScS05WvRTgjGXxixSgCXzaNc0Hv+I94/MOMZHiY2iXZNP5sRJcUHBlivQUyHpfxiHBlUrxWmWFOpKX2NIKQgiOoUZSI4rpwvHGF0GM1bUkzj4EJqJJ8rZ4XJ7eREPAEDAEDIGlDgE7YEPAEDAEDAFDwBCoIwIulbdJfi6Wipmff4VxzjkklilHsE4c2vTOjA6EPdF6IQxnLzou0ku0IRRSQgheD0b3hVLoOviQofHdXNOnzZDnn39OJ7fGEDAEcN77MzOCwolznqgIBR+oKGoRKc2rssrGn/CM45wvdlXpLk4EftiFmx9NDnp2vtqkHJtEm/KEEruQcHR0A8FOBToI2GMmcYE27A6jMxdLBwsJWDnYIPkdC3Xg4miwQ4SHUyJvZAgYAqUQML0hYAgYAoaAIWAIGAKGgCFQGgHmZMys8j2YX6Z1LhZ8ZhaP82JsJUMbe08uytuQq3pF1Drtmd4h5VPeJ46RXvNSqBHfOepIkCN9oxa6tthiS/nTpZfJgAEDOKPSK6++JDNmzFDeGkPAEBBxDic1zmB/scCZKn5zzp+s7GD2SrRpHmI1u49BJ8ZnLPKFxHnTJLouKdgYD5cmuHId6CIP6snyWPwliJII9YmXinrxoV78BhYRwWf9nIMB2nhXM+LreGi5AHTcY89ojI9HSx3JhhkChoAhYAgYAoaAIWAIGAKGgCFgCCD70kQMSV7UAxOniZ0D53e1UIzyMWo1J6OOQoqcg5IDSBpdGaE6cfM6ykz7SOSxCN8JYpBDxzw3X19GW0NTv3795Y+XXCpDDz1M+vTpo+ErKyvlmaefluee/YfK1iyeCNiqGxKB5OR1zolzDsFJ0ONM9icsTlmIMNRyTw/KaWyNnCsVhlZSZIdfmD/SZDouVSnWYkDEU0820VCKYquSvDI04ABFXPSfhI1mUpCL9WEi2Iq56oUVNtsNAUPAEDAEDAFDwBAwBAwBQ8AQMARqj0BmRCb/KpKBBVXoOTjNUwYh1RWkf54kbHDEjrpXUMS9A5dMTQmK1K42jk3pGqXQ1aNHD+nbt288zbx5C+ShBx+Qf/zjmVhnjCFgCKRP0vSZCT13nLHOgQFQvgUT7c7layJD3KXtER91sUtRhk4kEU5BkqIbfLBk7JEVMjletaCMJGpKUMoDLIbgmsY26+7EJYoUGys5X3qRlGF0GEcCa7shYAgYAoaAIWAIGAKGgCHQ0AhYPENgqUCAORVJDzbKtci70KR0VCmpUbmijZozqZ9qvG/MxozXx21moL7aR03pnBCKRil0Ia7uEydOlFdfeUX+ePEF8sYbr6vOGkPAEChEIFwfkruoHE7a1Emcd54nfoWxshrE0OA5xBOUf6TEBj+1RD0uFNEw1SZNZIcx4iJTJGFcdpJIjzJW5Fiio1/qIMFixRhFfTQELHWRJP6A6AhDUHJ+8Bk/yLYbAoaAIWAIGAKGwMJCwOYxBAwBQ8AQWFIQYF5Fyj+eOAOL8i9vhxZ5IpI4L4YWKVtgS/UOSSRGe3PMpMRY57wymsRPT11w8H2jFLq+/vorue3WW+T0006RRx99WEaPHhUtxjpDwBDwCPgTENUaiDlxjienaF+siMXrhaS2yD2lSbO5lIC42EW0iS4HUmTzdlE/jidJkS3ywwKwqz3SgCeHy2BmKHUwRXtiSjguysXzJo7UkSKNdk7bqOECFJiUVmVvx0o8Y60hYAgYAk0FAVuHIWAIGAKGgCFgCBgCiysCzL+w9lT2BSlvj3yCNs7JMukfhEwQ7xWrlIFPFERFbajI6pn+ZfNn79gohS6+bP69997lKowMAUOgKAL+BBQt8GTv3nLO29jypGUv0eacl3hCR6oinfdJDJT9BcE58okl4bw9kT1XXEsbLNgjjl1ETo+IgmOjlOISVi3aQOcvbSplmgJ93vr9EnyrAyO7wypIqrNmmWTRTQAAEABJREFUsUDAFmkIGAKGgCFgCBgChoAhYAgYAk0LgUxOFSWhcfYVM2HNzt/HgS7WMD+jX1qHXC0KFdxK9mE4b47IOiGHhoL2VGho/N4ohS4f2lpDwBAohgCLV/l659KnJ68E8PAqPaed80KxsfCsesdVBLs4hxhkinrDltHny8EYrQ0iuawXNSAo0eq64YadEjruyrKBE2USRQly1EcdzWnKP37n8h01GOZmiczz6fHGGwKGgCFgCBgChoAhYAgYAoaAIWAI1AwBZlWlPbP5lvoyPYvUjjkeeNWnglB2KZlsviwcK6ibIX/N2rISEj+JXAXeIL8vxoUufwDWGgKLGwLO5Z2cenbyKHDK40SW6Ewl65yLJIk3qGK+agZXFTpgAHZhkSjSUFuEYOWkagGPnuPQ5e1OZbbeiyIl9p6KSrEzrbGgA6hRJmARmV3B0UtWE69X/BaN84K1hoAhYAgYAoaAIWAIGAKGgCGwZCBgR7GoECiWk5VcC/Mx563IbpVxLlKkM7mgUo90iSpSxB0csSdDOUFsLMlYoaskNGYwBBYOAkmtxolzLjNpKE6xD4bEP2hK9SEWLjG4HuSFTg2CUSX4YxfRRrgVn8vHS7nRNUOMmIribYnCy1FLX8+mHCIWM3kTnWKdV4WWpsBL6iCduFi9tDBlZWXSsVNn6dtvWRm4wkoyaNXVZY01ByuRp442+tB3acHFjtMQMAQMAUPAEFiiEbCDMwQMAUOgERGIc7JUrlVsOsf8yxWxxAlbzOQ5pQbFLjHjq2ApMTOYQ2MbBW+1QpfHwVpDYJEh4JzTu63SC2BhyznHS4WqwYpzTvnQOJeVgz7b86yvzq/QXrzAlUQuNbWOw5RJRAiSSEmEhGMsf/Gkb6RPsaopEYJuGZMuQEcsVU3rNm1k+eUHymprrCXLLbe8dO3aVdq1ayctW7QQFrRI5KmjjT705RiOXarAsoM1BAyBpQoBO1hDwBAwBAwBQ8AQaEAEonwrzsEiOZ4hX44NCeOQHxa6MbODjwMp6+AFHnskgnOg7M44ao/VXrJCVwyIMYbAwkeABS2WqFnsKTp7ZOAJnG/3Y/O1aZknefpi4OKLRdqrKj6aPuXilOd6SCqkGvX3LtFDiJGQ8smwXCIpo0wEl7dil5iUc7BnhusCBFoUD6MVyBK8tUAha9n+y8mKK64sHTp2xHGLzJg5Q3/p9vvvvpWvvvxchn/6iRJ56vgruPRxwIVjOJYxGAsq25ceBOxIDQFDwBAwBAwBQ8AQMAQMgSoRcJphRC5MAKN8K9KIpGS9eSElS9hcYHxPvzyVN4RWjfTyikiEwMyPEnuI2DkdNSJsqWcvYoUusc0QWJgI8ORL5nPOQQiEkhcvHtSoPpGhKrjri7qqiXETDxbGsrMntiyXk2h6zJm25GKB9mz0YIIWbtiDAn0kocMOObXDnZITxy6hSEwub1ksEsfiXHpccY+qtIuHrX37DrLSoFWlU5cu+JycjBv3q3z++XD5/ttvZDz4GTOmy9y5c6WyskKJPHW00Ye+HJPLOWEMxmLMxePobZWGgCFgCBgChoAhYAgYAoaAIbCoECjI60osRPOyAmcke9iTIXTwihzZ2JASvDmypIXAp3zhZYUugGB7DREwtwZAgCdi6iRMncksRDlHO6fxPs4Fmbo6EuYIYZyrKh7nhJ0dqarpIju8s16Yi4pS03g9B6dGgqWG42IqUEhUCoOzpLY8ERUfNbrIW4UlsOnRo6cMGLiClJeVyZQpU+Srrz6TMaNHScWCBTU+WvpyDMcyRnlZmcZk7BoHMUdDwBAwBAwBQ8AQMAQMAUPAEFgyEajJUUV5mwu+lEmR7FzhkzbqSx9S5CfR0zhwjzVk1JdMCWIO7U1ZTyt0eVSsNQQWIgKpk5BnclwcSulRqNGTNraJOJe2Sw03XD10nMN4DEE8h674nrKk2MSXSsSDQluK4JMdCuwCwjTsYKInFOBUAdEFhjoSdOHCRlHJUaMGFbXBcehfBFSouqGf03mq9lscrSxE9e6zDGp6ORkzZoyM+OkHmT9vXp0PhWMZg7H4nWNszlHngDbQEDAEDAFDwBAwBAyBJRwBOzxDYGlBgHlVsWN1VCI/CykXMzenAjhHY0QU6ReJ7OKYaT+MhSvNEdHIIpkXmV96jq339B6QyWihjIy3WaELuNhuCCw0BLJnqJ+W56PntGWxgYxeD7RB0Qfna9DTVlviWE6NMHoJqGo8fQQXGsEWTQ8u7H6xQe99aYs4diSqYkoU5EixqTYMBrpoXfEwHlQsLPlMhw4dhIUofp4jR46Qcb+OabCDZizGZGzOwbkaLLgFMgSqQaBHjx6y0korVeNlZkPAEFgMELAlVoPAoEGrSOfOnavxMnNTQKBjx44yePBgJf6gT1NYk61h6USA14zB+C6uttpqCx2AgvwrWgFSM8/FTFERuWfWoVQ8h+EkdNHux1FHLuSfyIxhpxYddtqKpYRlsNluCBgCCwuB5AxNzehPVBYYUkopdsLSXjQEDQXE097HTptKj6c/id6+z66BOhJiosvaOAYEE1rhHHABSwUJLHZyJLDJrgptvM4P9HyqZeWfFHvqApy4lI9wYshOWP0vEQj2xXHny+L7LzdAlz52zBiZMnmS8g3ZMCZj/z971wFYRfH0Z9Mg9N5BxEKTYkdEwY6KiopKU0RAEOlgowgq2MCCvfeuoH+xV+z62bA3EJQmvZdAkvfNb/b2bu+9e8lL8hISuORmd9rO7s3d7t3O27uDTdSFOoEnC4499lg65ZRTqVOnTskySbVq1RKbsLvPPvv47E6cOJHuv/8BuuCCfj7+7ka0atXK9UH58uXd3cvLN67SLkZ69uxJjz76GD388CN066230axZs6lv3767uFVh9buLB+rVq+f2jWbN9Pi5u+xbuB9+D9jjXfPmzf3CUkAhkH/ttdfR7Nkv04wZM+jxx5+Q61MpaFqxNmHgwIGyn1deeVWx1lNcxgcPHkxTp06jq64aT/ECXeCffPLJMtYcddRRxdWU0O4e7oHOnTvLuXjDDTdS585dStQbEQ5VYW4Vt1LlSUTXmY95XD8mOjxXE641XbNQEekE2kR+k16FKAOZ5nDqzA+J/8JAFzsh3EIPJOiBpKjZAS2No4sSd2DunERuTtafUsrlS/+1ZPFRxSLYjnBZIlBsJm4AzdEg6JDzhzIOypmhvAFHcyKODLmOsXttBA/AKti4gFMalKNMxGxy/0BYRQxfKQh0EeGBZpZP1alY1yFau01Sv14DeSfXhg0baOXK/4ptv2AbdaSmpBDqTGZFAwcOoqFDh1KfPskLZLRufYDYhN1OnbwbzLPPPps6dDiCGjZsSKedfpoExJK5L6XJ1nHHHef6oGnTvd2mxfONq7CLkR49zpFzoXbt2qQUd2ZuT7ly5ei3335jLNxCDxTdA4cddrjbNw488MCiGwwtlFoP2OMdxv7S1FCsChozZgwddNBBZH5ASuFr7Npi+MGqNO33XnvtRd26dZPrcCf+gevEE08qTc3Lty0YM444oqPozZ07l/77L/beC/uFH2kuvXSYjDXnn3+B6IdJ6IFke+CVV16hf/75hzB2nHvuuck2n6+9oLmV3Llh7gVwLICn57cOgzNFiuefvhkbh86YViI0CefWPE8oV4HLs4yLCFsSj0D1muIURdg6VFKQFB1CC6EHQg/E9wB3OkuolPRA4SgFHKB17IFBKT0oKKVzI2NSyiaWoCw0OecMAwFn8bcoBbQKrdMFQAFTPFxxziRvjCgGjTFCaJ8BIsiI/ziHCsDlaTbImMGT1RUErGI2d/8NAzm3VyE34BCKywIMu6znmZkVqGr16jzIR2jp0sXFvjuoA/5Gnai72CsshgpwM5CTkyOWt27ZSqtXrxY8TEqPB7DCTyklDfr5559p9uzZNGfOHPr222+FFyahB4rqAef0KqqZsHwp8MD1199Azz33PN1xx52loDUFa8LRR3emRo0aS6H169fR+++/z2Pdq/TO2+8Ir6wmWGHy7LPPyXHBj0vR+7FixQrasGGjsHNzc2nVqpWCl5XkvPN6Unp6Ou/DBnryySd8zcYqrtGjx9C4cZdRgwYNfLI9hwj3tKQ9MGfOq1IlgsjnnXee4CWVKJ5bRdcl0zowfRdb1gTNczSIABEOPDEXqAtCuwZcRNcipGJdIAAimASQ/IEHuRCWDDwDEQoDXdo/YRp6oBg9gA4XZB6d1M9XinWtgUEpDlAxrRTzHVUmHSxeBrsALTdF3Vyzg1MoOUVNjQ7J+hYHKIC53qYZaJ8Bjr07YrbCYk6JM+YB4yzeFiDW5TyLKBqrprUwoAKgsztA3br1SCklN4l4eXxx7xPqwA2pUopQd3HXVxz2v/nmG7r//vvotdfm0PTpNxdHFaHNInoAK7lgYuXKlXTllVfQI488LMcMvBBCD4QeCD1ge6By5cry6FjFihVtdunEo1rVtGlTl/PGG2/SbbfdymPd/fThhx+4/LKIZGZmkjku6ekZMbuwfft2uvvuu+iNN16nW2+9lb7//vsYndLK2G+//ahFixbSvF9++Zk2b94sOBI8nnjbbbcTVlOnpaXRjh07KDs7G6IQQg8UqwfeeustWrt2rdRx5JFHSl5SSYSDVW5dmOgZgucKgrqTMkYgN3wRcqKnaIzks0EPIPUJIgVgUpCoxGhoOdct5aCkwkAXhX+hB3aZB3TXxMoZIh3QIv5DF9XhHB5SdK+VlTxKaX2dsmLcDRoAo6BtO6bc7m+kui5QXs1Q0hT40QB70TyPRs0AzQEGYMox6GTM0JvZf015Ke+9RwDj/YclAEiAYr8hd8HZyRi+q1D2ECxRrly1qjR8FQcEBCmBxNSFutGGEqgy6VW88cYbdN999xFWCyXdeGiwyB7ABAFGFi8u/lWKqCeEXe+BsAWhB/ZED2BVkNnvr7760qB7RP5///d/dM8999DcuR+Wqf3t2rUrmWvUp59+6mv7CSecSPXr1xfev//+SzfccD1t2rRJ6DAJPVDcHvjll1+kiqZN96b27dsLXhKJO7fi+RgBTKURRgCKc96AEjkExf9z53lSwOgzwRvmobokCC1Dlc40j0WahzksNKCvOTplBdnCFV3ihjAJPbDrPKCU7pRKIY+QUsg1KIWcCKkOCKFLUwH+IqwbIaUUA6OBm3K4yKHLJKO8xSkTYQXenIwx3qCtGZKCZK5urXCImMcbRf8pCGKZzFV+rjO6OdYcmZ8i3k9HsNtklatUoRTer81bNvMvhjtLbL+ys3cS6kTdaENxVoybxiuuuFIeAUA9eGl0r169aPLkKfwr8G0EGW46ISsIjBo1Ssr27NnTV6xv3/OFf9FFA4SP93AMHDiQ8GjM9BkzaOSIkXTooYeKLK8EL7/v3bs3jR8/nm655VaaNnUawWa9evXyKhYk8/GOOOIIGjt2HN883yB2r756Ml1yyVAqqRcsR/vnpJO6ir/wyNCECRMo+nYhawEAABAASURBVA9fAup+5pk0ZsxYgv9uuPFGgu+DvgyEd9TgeAJSU1PFVKNGjcQ+eP37XyS86OSQQw6hAQMG0JQp14hPkJ911llkv3zfLhN9Th122GE0fPhwwq/wM2fOpKC/gtYR7afCnkdYOWDOoxm33CLnU9++fQnnV1A7bd7xxx9PeDcMXk47/ebpUhaPE9k6QTgee7jkkktoMvexW/jcxUuyYQf8IP1EeDg/YXPqdVOl317H+ciRowirH4LK4+XcOOYA+A7n0WmnnU6XX36FlMcxxjgQ7xgbm1X5hwA8NnXZZZfRjBm30DXXXEvoz+AbnYLmhTl/Cnos+kaNQ0cffbSMPehD2Bf0O3vfO3bsKOPAzTfdTDfeeBPhJdkNGzbKc9fgU/QT6ZvTZxD6JvCgvglDGL9wPC6//PK4fQt6Z555lttn27RpC5YPUG/3BMcEX8EAYujQS6WuGjVqiLQKXxPRRgDON2EGJGjDqad2o3E8luIcx3l54YX9qU6dOgHaflZBj6W/tEdhzEI79913X5fZs2cv2R/w27Zt5/IxZoLXM+p65SowgsfkoIN+wqS7mbKnnXaa8Dp37sLj3Qg9Ht9wAw0aNIiaNm0qsrwSewzEeILr0Nln95CVdHY5jDFoB3LDxxgLHsBeaWLOc4wvRjc6xxjYp09fGb/kWPG19OKLB+d5rJK1z9FtMbQ5r9etW0cff/yxYbs5VnFhpdrQoZfQ119/7fKLiuDeA+cNxj/4Avk555yTkFmc826/4/6OsgMHDiIc1/wMQMfUm9exhx177Ma5Bl40IACDcwGA674tt48dPiKB/UNb77rzLkIfhW5hxmB7H4zvMP7Z4yhsGzDnJsY98HAdGliIe0GcvyV5DUfwGO3Fj9BdunQBWiLgBaZ47uXMyXTFTFtTNqCurlaIk7ImbwRApEq0mOBN88AAwfYZ9VVp67MM+loLBEBTYaALvggh9MCu8IC/xzotQIcGykOEJUd3VcrIiJTycMrzz+jBnlbMu6ijzxXyRlYTdGEnFRuOqmZBW2Mi0yinlpKjYnFYzpswHCGTsjHJLSYioUjGMzbMbIfhZUE8T1r2sSqVq8tObNqwQfKSTEydpg3FVXeLFs1lMowLNoI8N/FEDje9uOHDDRUmysOGDadJkyYVqAlHHtlJ7B7Q+gBfOdx0webhhx9OuNHBJL979zOpbdu21LJFSzrhxBP5hntCnl9rxM0kAmO9e/ehjh2PlCBUu/btCTdVd911N2Hi7as0AQLv+UCwbMKEiXTMMccQbrQRPMAE4tRTT5XJLepLwFSRVGz/YKKDABH8hQBk48b6PTOmAtxYTucb6oEDBhLeuQX/tTmgDR1//AkcqLtRgl9GF3mTJk3kmMAebtKI/+rWrevyDj74YOb4t+HDR/Cxv5rO5Mk16oNPkOPm9L777g+8ibfPqdNPP4MmTpxECBzghrRZs338FTBVmDpsPxXlPMIXvXBccR61aN5CzqeePBnGxPyUU07h1sVuOFcQ3Bo1ajTha19t2rShlq1aSdnLLrtcgoHxAq79+18kASEEAdDH4E/sC+xgcnA8B89ia8ybc+mwYYR+C5vtDzyQ0G8xaTjhhBMkcDV+/IQYA/XrN3CPO9pwMwfqELxBwAflcYwxDiB4heMWY4AZ6CM33XQTYZ8w4cKjRjiH0J9vv30m4bEqVivwVpDzp7DHAj5HP8A4hP2+nAN8GHvQh7Av6HcIeKHxCHDAhxgHWrVuTQcccAAh2DFt2jR5wTl0ogF20TfRT6RvtmxJ6JvAMXYhgB49Aaxfv74ck6OP7sznVfC5h3pwXqLtHTp0ILxzCjwDOG6oN9ExwZSLl+OagLpM4BKPy4EGHH54h8BiCKJPm3Y9BwYvoS48luL8wnnZo0cPGUcxpgYVLOyxDLIFHvoX2olxDzTA7A/4CPKDB4h3vYLMAMoAcK0yPOSmLPoDAgY4b0466STCuQTeGWd0l6+1HXPMsVAPhBEj/OMsxhNch/r37084nrBjCiIIj3bYPPRZ8ACQG11znsfzOa6VGAMR1MYYKMeqfXs6/fTT6e6775Efj4wtO0/GPtv2bBzBF1yXwFu2bBkyH/z080/8w9g0WanmExSRwA8DuFZFX+v69buQ8JXOvMZmnGs4Tm6/4/6Ovti9e3e+/k0kBA7jNa8gxx426ltjd9OmTcGKAdwr4FwARF9zzbFry4HeyfxDHvYPbW26995krlsFGYNR+Z50Df/ii8/lcVnsd5MmeyErWeD5GE9E49aJeZlSMrmLqwOBaEAZhAvM4M0l9QTQJf1moQjQYr9MrFMY6NK+KXtp2OKy7wGrR7qrtdzIku6g9k4aHfBsHHQMuHaMRNtDGiMyKpI7AwYUmXYyxuxNSQDMb8fTBB9glwDuWJYhC7QLRuAyGPHMMcEb6GijoNmHEAFYiwNi2pgvSCaCsptklEuXxm/dulXykkxMnaYNJVE3fvXFRGbNmjX0119/0apVq9xqMalJ5heN8I4oTHzQn3AzO3/+fDKPH6Snp0vQCpN1twEO0p8DBQMuGkDmXTFo64IF8933JpQvX55w49ajxzlOicQyTGbbtW8vynhxLx6J+PPPPwnvOQETberJv/bHmzBAJ5kA/yD4CJsbN26kpUuX0vr1XsAVN7BXXnkVmRtT+O7vvxcQvkyF9iOQhUk1ftGFDQDex4XjCgANWL9+vRxr8P799x+wXMCqIEzYMHHFxwWWL19Of//9N5n3pWBCgsAObpjdQlHI+eefL18p2rZtG+E4R3+YoKh1wE89eAJd0PPooosuIvs8QsAA5yB8hF3ASsohQy6R8xC0AewzJoYIboGXlZVFOFfwCChWGYCHySJWawG3AcGRM888k9DHwMdqBTza+88/2u/l+dxFHzPHFDr5AQIyJ3c92X3MBy+g/v333wlfb0VZpRQH4DrGnbBC50wOYiLIguO6YMECWrpkCeEcgqxp06aENgG3AcGviRMnui/5xr7DDzjGeF8OjstZZ51tFykUntf5U5RjYRqDFUannHKqrNjFccA+4FyCHGMego/oh1hlC5k5PyBH/b04KArcBqy0Qb8zx3Hb9m20aNEiGU9hG/0J48ikSVfbxejjjz9y6UMPPcTFbQTlcKzA+4vHJ5x3wAGFGRNQLi/AuAAw4yDOd9CAhQsXBhY97rjjqAkH1XENW8jjBfwG/0EZ/r7ggn5AfQBfFrZf+QxZxIIFf8vYhn5m2Av4WoG2AzZsWG/YScnbtWsngX/0BZxLi9g/8BeMV6tWjfr16xe4Ug9BdXwREecF+h3OMYxFm3jcR1kELfBDUwv+IQg0xmG0H9cE0AD0O/AAq1evAStfwOqZCy/s715LcZ3B+L7B+WEP4xTGK+jFM1bYfY5nD/zDDjuc4AvgS3gsQm7Diy+8QHgPqM0rKn799dcTfhhAveijuPdBn0Xfhe2aNWvS4CFD5Acl0Dag39n93Zz3S5YslnE0LS1dAoeXX365XUzwgh57KZSkBPdXezdrJm3EfRTOoS1bvHehmWryGoOhsyddw4l3GGOheb2IGYuZXeybIqXrwPxLY8xxeA6NLJZDWk9P0cj8RXhGGMVikWIuZ75Na/GtBM/zWCAkalHaLrOwSbMkAaUhDHRpP4Rp6IFd4gFczFCxUgpZICiluCMTKaXI/FmoYflzo2B1eJSWscHRBO2gcTPox+pFuC3RRSLM0JqoGsAM3sDnjDfwPIoZpPWBkeA2TbF/bCBGg/cPNgF2ASX2bE7ZxRHcQOt37iy5xxZRH8DUadoAXnEDHkt5+eXZfEN+AY0ePYr6979Qvk5l6sWEz+BFzTMyMiSIdPfdd/OvnYNo1KiRNHz4MPrppx/FdFpamqyaEMJJcMOPxyiVUrRlyxZ5gXq/fhfQyJEj6YILzqcX+AYYfkOQB6svnGL5Zueee56sgoEiJvt45wceiRgzZjQNGjSQPvxQv98Edk8+Of5KC5RPFsA/uGF++OGHqXfvXjR48MWEl8Yb+z04kIfACAJQ77zzNvXq1ZPwy/DAgQNo5szbOSi2TlSxgqF9+/aCf/7553JccWzhJzARzAMNuPnmm8ESwMTLlMPE6vrrp4kvRowYLm2BLSgi4IhVAcCDoFy5cvTmm29ysKSvHGecU0YvGXXAT7jxLOh5hBVmSimCH55//nnq27evnIMXXdSfXnrpRWkijvexxx4nuEn69j3ffaQHKwtw3uJcueSSITR+/HjCxB66OFehC9zAUZ06SdAPk/57771XfIJjeumlQ/ncfV7UMKEaNGiQ4PklrVq14omXbh8myE8//RQNGHARjRs3lvr06U0PPPAA/zCiR2j7caZouziG+Nomju3IkSN4QjeY4E/4FbqYzCKwBdxATw7woBzo337/jYYMGUzww8UXD6IpUyYTJus4NpAXBfI6f+BfBE5gv6DHAmUAGF8RJMa5j+OAfbjvvvsI/Qry5s2bEyb+N954o+wfzo9p06YSggKQt2jZMuarb+dw3zT7/tlnn9E5HIgdNuxSGU/Rj9avX4+iBL/aX+765JNPCIFqCPfbf3/Co1DAbcBqL0N/GfW+qcKMCcZWvPzaa6+RMQNjAHTQdowVgGuumQJWDGD11w8//CD9aTiPF/Ap/IeyUG7atKkEFYAbSMaxNLZMjg+hoJ32S9ixAhE8AI6N0U1Gjv6AwMzkyZMJ59Iwvp5NmTKFVqz4T8wjmNe9+5mCmwTXM6x2Aw3/3HLLLRyU7i++G8JjCvolZBUqVKBup54KVMZTtB/XamFw8sEHH8hxAh+P9DErzw3HAOOvUkqCvBg7cJ3BGICx46mnnpSxUSlF3bp1oxZOkC3aqNnnguxztI1oeu+993ZZCLy5RDEhp5xyCpkfa3Rfv0H6Kvos+i76JarOLJ/J1+I+QH1wzjnnugFMrPbBvQjO+yEcGJsxY7rc56AAAnhYtQgcUJhjj3LJAtw/ILiFMQn3URi777zzzhjzeY3BOIeKep+AsRLXGlxz0AZcUxO5F9wV13DjnOX/6T6NVctYTWn4xZlHAkNQuL4rt1qDRXh+5jIZCSrL7MDZmrFBIgUFIBKTGiWmBFA7I0LyUEEkCfGflqQwFm6hB0IP7CIPKGV6rO6QShnaNIiHBu7ZWmp43J+jGZ7Ij7n2dAGlPPua41cn8uTk/AXpcZPIMsWaVjkuADkzebP4oHwkKzKPhAccAAaDhTLFOyypf4h1GiDFtdhN2WsuXtaRtLQM2QVMTAUpwcTUadpQElVjQoDAil3X/fff707ea9asYYuKjOOrjG+//ZZrZ/Xq1YRHDxHgAdNMYoEDevXq7f76/PTTT9Ps2bPBduGJJx6njz76SGisKEEAS4h8knfffYeeeuop+vWXX+ihhx6kL774wi2B1QAvvPC83PSDCbvISwIQuLMnM6ZOrAwyj6dgsnbHHXcYkeTvv/8+PfnkU3xjEpGVPubdMSJMMOnevTsppQjHAjfrX31dG1svAAAQAElEQVT1lVsSkwHcHC9YsEB4mLCb9gjDSr7iyfjdd9/l3uxbIkpWHQU9j/CoIiZoaAvKPvnkE0BdeOyxx9yPKOC9WWYShMlhJw5WQRGrVK668kqyV9T8zgGfGbfMkCAsdKIDw3Xq1gWb1q1bT6+//prgJnniiScIfeGll14iBN4MP6/8119/lQ8+YHXDq6/+j5599lmfOnhm1Yd5x5JPwSEQlEJQALnDkrZ8/vlnQmKVw3777S84EgTY8IgicARmLhs3TgJboAHz5s0jBI7MGAZeYSHe+VPUY2G3B4FNE7gFH8cGq+KAAzA+fPml9xJzjA9GXynFQfLmUBM488yzqKkzUf9h3jxC0FwEToKyt956ixtIO+aYYxyJzuA7YJhUYzUlcBvM+70QnMMHP4ysJMYEU1d+OVbD3HzzTbKC0+jCf3YABsfPyIAXpV8ZO7s6R9D8/vvvc3+sQXvww80LL+jAOWj7cUnQeKwROQLVd9wxk69fc0EKYJzF2IlrEBjt2rdHlhTAtRTBMxh75ZXYseO5556jl19+GWK+hqTLWC1EVFKYfY4yEUNWqlTJ5f3333IXLy7kjNPPENMIbqNv4poqDCe56aYbCfdGIOvVq+fzxelctlmzZhDJcZ82bZrvWvfxxx/zWPq2yBFYOumkroIjOeOM7shkRVVJHnuplBMEl/CjGPomk3G3eGMwCuxp13DsM2Djxg3IBMxjtkIUY6JIaet8zdEIGU7MPE0pR5f0n/I0NYPpWJ4WRXTGKTAAo7wpBpkICgLCRUA4bTD6WhYGurRrwjT0QBI8YDpXIqa0bkzE24sQiRGbjNYVhbiJtq/F3NkdMn8bjqIuGDeNGr9YD+UAjHJ1nPIQRtS4USPq0vlY6n7m2XRez9507nm95HECyAVQBCCElTg2XA5o2xmuwBnXQEfJlbQAghDKkge+++7bwObiMQwI0tLS3V8+QRcFcFM5Z86cGBNLly5xJ83VqlX1yc0vvQgyYBLvEzrEc889KwEekE2i3mkFXhBgIoFyl19xOb333nsxKljlZVZw2DfhMYpJZOCRl1mzXgq0iEADBJhkPPLIw0BjAEETBCEgqFu3HrKEAfvYsGFD0f/mm6/pjz/+EDw6+fTTT4SVlpYm70kTIioxL271s0lesJyMOgp3HjWV5uC4I2AqRFSCyQ1W9I0dO4Z+/PEHkSKgh8kKiDfffANZDKCvYHILQa1aNZG5YI4HgqX9+l3orgIwCvg1/bHHHiWssjO8/HIcZ6ygeuihhwJV167VjzFh5VL0qixTAMcX57ihTW4HezDBM/xWrVrz5DdNSEzkBIlKEPT7+Wf9daooUYHIeOdPUY+FaQQeM3vllVcM6eYIuhvip59+MqibL1261MVr1vSOM1aAQYDr/ZzXYsc3yL777jtCkBJ4o0aNqWnTpkAFsDoT5zSIgw/yvzPv6KOPJpw7kP3888++CXWrVq3AloB8cYwJYjzBBOcTgjTR6l9ZwfKaNWu54mQdS9fgLkLQv01AxG4C+ijGavDsgDNWvpkVPr/88jMFnesIPl/B1yWMRZMmTYSJpMBeezUROzhOCPQKEZXgBx6sMgPbnNfAbSjoPttl4+F4ZNLI/vtvhUGLJccxqN+ggdj+7bffyKygE4aVzJnzqgSkwGrf/kBkAqbfIVA5a9Ys4UUnDz74AOH4AWbP1jqod1cde9M+jGG/8I97ho6XB52X0E3WfQLGuzkFvhfUY2ZJX8Ox3wA8UYAcUKWK/z4VvOKAoEUEmMIJX9k1MhE1JxMdqKAAco5YuajQXsKlrckd+JamCMGzwZFDJigQLS+zga70St5FXe9KmIYe2NUe8DpW/i3Rul7AyNDKnSDDhlKKlFJACwimjPR4KethQsZJUL8nghWAx9EYxi+AppBaWlxRamoanXnW2TRg0MV0/IknEG6WW/NNMKBatWoooMEppkhpGimXRxYElhYPgnrYBA9A8BOACyri/eBBlNEyv2Vn75B9SOMAjyDFnVj2TZ2mDZao2NCFCxcF2t6wcaPLz8ws7+JFQTZt2ki4yQ6yYSbdOJdtuXmUB6tx8A6kIBg8eIjbj2tYE1DbTl44XvDbp09fwrunbrjhBrrnnnvpgQceJDOZVUrlVTxpMvtGKtpordp6kojJNN6rFuQH8OAnlK1WrWA3Ym3btiWs4kHZJk32osmTp9DkADj00MOgIlCvXn3JoxPcTEfzQCerjsKdRzXQBELb8Ku2EFEJbqARcAIYUYMGDQ1KhxxyKE0O8Al4jRvrSST6cNu27dwydsAEX7p66KGHacKEiQQ8vy/4uUbiIHhU8uyze9CoUaMI70zBKr+nn37GF5jGo5hBxbECJ4iPSbbhI1Bm8Hr16hmU4gXHoYCgH/KiAI5RUPmiHgtj04w1hjY5+pbBTZDb0Mizs73H2ZXyxgQ8ngb5hg3rKa+VEvZ5ZX8VEHzzuNY+++5Ltq/NqifY/+gjb+UP6OIeE1BHomCfN3YZrADF+9vAS0/XgVLgyTqWsLUrAWNGvPrxjkLI0vhHAeQAfNTAjLPmmIMfDXi8DOcF3hkVLSssXb26HgPRR+P1AYyNkKOOKlWqIIuBgu5zjIEABh5lAxsBkKX8wxfw4gIcAzMuwsfx6kGwZ4Pz7rLq1b37aNPfN23alOd7w2AbYGyg3l117M0+os0GzytfagX1bb22SbpP2FSoe0F9/qJtOE/tdhkc5yZ8DjC8ZI01mzdvMSbdd266jOJGMAEEcD1KKZ5xMeLb9PzMxzKEMghynvD5aPBIz96EL4lmmpSLaAXN0Bqc8iZN4vZoC1Cksvcy+mrNj6T2l71Gh0z+hNqPe5Uya3vPUetdDtPQA8XjgWKxqvuhmDY3tUoppiOkFHLurtJzyaXJ+XPEDhUv0za4sKsQv1yEdSJaNcKos1mow1Gi47fjaCFTRHhM6ZBDD6X09HRS/J+SmqLHJSmkHDtOxqRvSGQayorLORo6k7IalZRpJQj7yMk5uiCYz55wym5ifoWFL0t6L0ydpg0lUT9WNwTXg5MrWFJYbk5OboGKIhCAXxBRCEGnQ/kcjwcpKfp3pCqVK0M9ITjmmGMJX5nCS2l79epFeKE0gl5NmjQp+RsZbrEZkxiN2Wo4kxRMCOL5AHwzOalY0XsUJMZYAKMJB7cMG6tNYCsIzK/Z0K1evTqyGMjNDT53klVHQc8jBIRMABA3wjENzoNhVtNABY/uBfkEPLNSDXoNGzZAJvD0008RVg+ZflatWjXCO9SwuguPKN18080Ub9WVGAhI9tlnH7rxxpvojjvupP79+8sXNw888EBq1mwfwqqBgCIxLEwoY5jMiHcOov+xWB6/w8oi4EFgVpMFyRLlxTt/inosTP3x9tHIC5qbfrBx46Y8i65atdKV28EsML/++mtkhP594oknCY7E9Lf//vuPPv30U7BcKO4xwa0oASTe+RSvaLKOZTz7JcXPzcmJW1XQedaEry2mwIoV3vlgeMWV22OgWbEVry4jx3uamjmP6Nm6Bd1nu2w8XCl9d6mUzuPpJYNvH4NV1sd3gmxvdH7wq2Kt4PH6u/djYFDZaJ5db0kee187nPmNjxdAxBuDmyTpPqEsXcONe1JT9T0m6BI4TVENz8qc/oAKAcx1xxXrWOKOS7E2i/2biiaZAWWAK4pYJSMOl/UcTIQWaTRQvWYbjqY8LxkDBc+LVGK/PtOp7ehZ1Hbki1Suar18bTXpOoIy6+hnkTPr7ksIfOVbqJAKCKJJ29C+AGgz4jlKq1CtkNbLVrEaNWrSdVOvD4Rrrp1KQy65lE466WT360dlZe8waa3LvwwDcENXMu2OEOq79rppdA2A/QccMHnyNeLLriefSvgSiTuAcMNsnEkT0wEaAKajcxCIe78pi3GJyQB9sPSgQBhFHNSzQvrPMEyuuU7KhXhLSUmldu0PFJ5SinJzc2QywiJuc0RoEZqEbSnUaWjkituNaBdwA9xwVjWUmxse3oV0bs9e7uMsrkIZR3Zk6V/tzbssSnJ3TJ2mDSVZd2msKytru5zDaBt+FcXjMfnBP1FfEUTZIOjS5Ri69NJLaa+99iKluAOwElYlYBL/8ccfEQIU8b4wxqolvpmJJIKg+fkAcnyJqyCNNKsuUAYvoYaN/ACTb+gnCiVRR1BbNm/e7J5HmLwF6cTjGb9Dnp8/jNxMjlAGgHfA4f1meMExvm5o/JCWlk6tWrema665ljp37gLVfAETVqwIw+oAExjfxJOx3//4nb744nPCYzLmPVv5GiuAws6deqVramqq+2L+oOKZmZlB7KTwknEsktKQKCOmXWnWyp0oFSHtc8+s9hEBJ3gs1vAQtGQWIeBVrZoOJn8/73uwfGDq3blzpzxqbM6/eHlBxwRfZUkmTNthNl57o/nR/Qplyxrs2KHvL9DuChWKr6/Avg32GGjGDVtu40aem5vrfoDBlhcHbs79FP7BKii4lsw67WNg98mgOkyf3rFDj3/QMeduRkY6yIRhR9GPfcJ1FZeiuXbBfnHdJ8B2NNjnb37HLLqsOV7gR48p8eigsQbzV9gAbNqU948a0Ekq8HzMZw/3rACbidtYM0FjviKl73ssnqBKhJxg0wT4/irAYTnEnHmb5qNqV6RZrsouD3RV3e8IqtigJVVo0Jyyt+d/oFRaObfx7DHatvJvj04yVrFhS2kb2hcEFertTzkJtDnJzdol5nAz2bBhQwoC3OgedthhdF7PnjSFb5C7ltAXwZLhCATobrjhJgK0bKnfL5EMu3nbUJSRnu76Ep+GbdCggdCNGjemQw45hPDlogkTJtFFFw0UU0q5XVjo/BNPH0UFuJB/4GCGbFGjghNgggWUExWTgMlylIAtIUUGDFySiTpumBQPargxUUrR/335Fd1zz900+epJ7guWpRgnEcceo74N5QEeU3koqpIGeLyqVatRjerVSSlF+PeUyza2cdM62YHKVatKXpKJqdO0oSTrLo114Z05uMFB25YtX0Z4d1J+MH36dKjnC3j3Tfny5UUPjxtNnDiB+39/whfx8FJtvOQb/UkUSkGyYf16aUVWVlZCfrj88stEP9FkyZLFrireJ5SfnyFHMNAtlABSEnUENQOruMx5ZH6ND9IL4q1Zs9plz5r1UkK+j36xMQzg5fF4B9jgIYMJX8l88sknCEEvyKpUqcJBjROB5gv4kqL5YMOihQtpxowZ1Kt3Lxo3dizhpciPPPIIbd26LV87BVVYs0a/9wvlWrZsiSwQzGM9gcIiMtck6VgUsRkxxc0KmPxW09kvMI5+bA3nqHmH1957701YVdmhQwepCxO1d995R3A7Ke4xwa4r2Xhyj2XhWmd+kEzj+8MgC1jdi3txyPg2B1mRwR4DTT8ustEEDOD8MmNgjRr6EbB4xYwck31cg+PpJZO/detW11xx+8U+BnXr1XXrDUKqVasm7LVr10qOxPT3KgW8R7TrLfg+4iYctRPFC7DZqySTvFqcKAAAEABJREFUdb7qGr3U3ofiuk/wavMw+/zdVdfwChUqug0y54DLKCYE87Vo0woMzMecUwI0ADEanoxBKoCySrGEN2FI4hQSHImmRc3VAwJgOYtRFU8bmQAPQFIVM0jqQ2Hy/lI8tOQxrOBKr6gHuB0bVlBOlve8abzWLP3wIdr099e0ceG3tGjOjbT+z8/jqRaZn5JejnZsWO6D7G0bXLtZ65ZRJDf+MmFXcTdDcDFewzeZBjZt3OzuIX79QJCm22mnu7zSjJTk1+T8ftCd0/BWrFhBWL2xbt0Gwi8UufzLFfx8ZKdOdPHgSwg4dO3+a+OQxQfUxZF0VgguAzkLnQ2DiABoHlSQ8TCiMxlFiGAH4IrJ+0NbcSOMQQ3czZu30WuvzyH82oIy4NmgSDmkk7NR2EB5gAjRIEaUcnSQMQ49ZrsWiHniOz0KQlTmAasjcnn/K1WsRGlpBfvFrig7j7pQJ+pGG4pia3cqixsc7E/jRo0p+nEf8A0cfvjhBk0oxw8GUMSN/NSp15H58hl4Bopz0m7qSDRftXqVqOJXxbxW/+AxOuiIcgESvJQXYyGK5PUoHfyG1UTQKyiURB3x2mQmKnvv3ZTitf+4446j0aPHCJhHxpYuXeaaxKOLLhGFYFKMR22j2EIiOIUfV4TgBOccvrI4dtxYMr8MN+PgBovy3ex3O9151500d+6HMWXcyVuMpPCMZcu8L6EdddTRcQ0dcECbuLKiCpJxLIrahqDyq5xHEvF47DnnnhukIrz2zsrrHTt2UNALzM2jiWlpaXTCCSeSCSgiKGa/c0aMcVLcYwJXIZtSuAEQNGlJaTiWJrhiHsuN3rmDDjoomlVkGh97wAo8GGrXrj2yQOjZs5eMQ8OGDQ+Ug4n7f+SJghkDsWJq//33DyyGsR+PRkO4zgrugC5O2OC8Cwt14GMNyIsL7GPQPo9jcPbZPQh9Gu0wfdzG8ZVUvPIAvGiAf821BH0Zcrvegh573M/DBqBunA/NNNtbP30FneKCPfUaDn+aADDmQXhPGHjFCYqUZx5jMM9LNMPhOxlP4TQ7KlUoHyNU3vTS1Wcl3lzSmc9JlcxEDlO6YESjzAeimxQB5cIuDXRVbOStoMlau8RtVF7I6u9eo5/v7Ue/3HM+Lf/kybxUiyxb+fXL9O3U43ywcPZ1rt3ta71fnF3mHoAsW7aMLhs3xoWRIy+lSRMn0O+/6a9i4WJ3xhndqXLlKnuANwq3ixiYTEn4c8L4K2n8VVfQ5ZeN5l/CR/NkYa4EvCKRXMJquWOPPU7U0YmlkzMFnLN8Nt3hI6yMcpzlo69IKYBW06WBKyQM4BicSXcDXxPr12+gFJUidlDvtm0IhEaYZnmEIWqLYbF5RcqvxW0CA/ZsiWI9xQLYAHBEUF5grYSvWFL2NwTuNjk3XbXr1CmxHTJ1oW60ocQqLuUVma92IXgzcOCgwNZedtllNGnS1fTMM89S3759A3VsJnAzyTG/2INnw6BBgyi/FRq2fnHj7777LiGgjXp69+4d2Lbu3buLHx5//Am66qrxUE0YMNH42fnSHG7SgybsOAZXXHGlvB/qkUcelXdNJVwBK5ZEHVxN4IZVexCkcfC6D58j5Z3VfOABEIjC+64Q7OrSpYv7dbs5c14l/MgEHQQY21ovmgcPcMABB9CECRPonnvuobvuvAssAbwD7vnnX5BjgQ8mCNNKEFjECj2wchL8EW+z9ULcjIxyKOqDo446ilq2aOnjJYP48MMPaP16vdoVj9YheBdtt2/f8ymvYHS0fkHpohyLgtZVEP23337H7ZtdT+pKTZs2jSmOd7LhHIPg1zhfPXv33XcIQVDoHH/88XxPp983+PXX/wdWDLxbzGMCzk9UWrlKZfliKvBkQWk4lhiPsD9Y5X/WWWcBdQGB7pNPPtmlk4WgTvOBCqzww3Um2jbGGQRQMBa1b9/eJ87K8h6hs1fw+JTiEGYMxKOJ/S7oF6h1AfMhh/Cbb79FViLwxx+/u/XgxwiXKAbEPgY49v37XxRTS9OmTckcf/SDjz/+2NWx+/tJ3N8ROHSFDoJ7FRw/gFmBZNdb0GOPQLe5VrRr345wfjpVSXb66WdQ23btBC/OBPtQ3PcJ8dpvzt+SvIbbbTHXNgSMFy8u/ngEFh4onlu5bTDzMicQZTIt14srNK5TlNeYncrMzWIoxp2yrgg8Dmsx7VTJOtjAhy4LQHKm5ZrPJcClFEl3UZJZdx+35u2r/3Hx0oxk1tnbbV7W6uI/sdzKSgDJyMig00/vTjNumUnxfgmO14ylS5fQ7bfPIKxMgg4ma/hcM/AQYj2gFDqi5sNXCOAA0DE3b95Mzzz9JOn3mmi9ffbdTytzaoJV/fsPoFGjx1LLPB+51OW5GGJAZFULlgU8QsgoZXLKUxdtAJD759Wzbt1a2rFTv/cBQc/MChW0FkyLmosIX7cJPICwiFhPKUXRf8yWVgpfGuCVgUylpMgNfvCAKqXKZLJixX98/CJUu3YdSs/IKPZ9SM/IkLpwTqLuYq+wDFWAx8VwY4Em41GeW265lbp27SqTyVNOOYWuvPIqOvrozhDLr69//KF/ABBGHsn8+fNFipvQm266mbpzkAiPE3To0IHGj59Ap5WyVbJYAYL3h6HReKT99ttnEoJRzZs3J3yZbejQSwlfjsQYUK5cOSro+7Ng91UO6uCmHvj5HLRAsAwv6MeNPOqaPGWK+B3ytLQ0MhM20IlCSdQR1JYXX3zBDVi1OaAN3XTTTdStWzeC/xCgGc+BwWrO+5BwbmAVjbEzd+5cQctzcGzSpEl08cWD5ZF3BLguvLA/jR49WgIBuLbYXyvFO7PMlzSxOmTs2HHUuXMXefn8+edfQHihvFk1+M8//0od+SX2ysMRI0ZIYBfHB21Bu0aMGEk4NvnZKagc10nzSCbOr1GjRtOAAQOoffv21LFjR8K+nZvHaqaC1hdPv7DHIp69ZPB//PEHty9gAjtlyjWEQEULDjgee+yxhOBwjx49pCpMVp96+mnBg5Iff/xR2GYlCd5d9PrrrwsvOinuMeHff/U5iZUr2Cecs+gz0e0oLL2rj+Xvv//mNh0Bnqt4DOjLQfBx4y6T9+aZY+AqJQl57bU58sMqzCFAMWHCROrS5RjpS5dccon0K4wlkEe/mw1BT5xDkKHfjeAxAOO+WYUFfjywx8B23G9xLT3jjDMIZdGOGbfcQghiozx+EH788ceAlgjgC4dmvwo6HypMA/Ux0PfNCHJeyfcRCEqhz6LvTp48hUxgAz7Ho+emHru/Y/xG3+jZsyehLPx57bXXuYEojJvvcgDblNX1ZgsJnxfk2JtrEvojftgbPnw4oU/iHY8DBw4kXPvFcDEne9I13LgS94Y41qCXLVuKrEQgYmZgMv/SVWLuJZiLCMXTOD9DMUdLvBQ8mcVJAr5G9LwQNEDzBGNUquacTFuMXcWcAH6xB7pqtjmBWg95jA6e+AF1uPkn+Vpii/53UYV6+1G5mk3QboFtq2IDXY1PHEYHDHs6LqRXriVl80tSy1WkRscPoVaDH6HDp31Lh137JbUc9KC0Ya9Txrj2q+3fMT9TVL7WXq7OtlULXTwRJCUtgxodN5jaDH2S/fE+dbjpRzpkyidSf8PjLk7EBFXd5zBqOfB+Omj8u1K+3bj/0d7dx1PFRq2p0QlDxRZ8Vr1Vl4TsQckEuG64cQZ1P/NMqlGjGinFZwyEBQAsf//JuSlCsf322x9ZIHQ66mgaO+5ywrux7rn3QUJw7arxE3midB6hPYGFmHnuuT1p8uRraDJDq1atmRO7HXf8CTSZ5YCu1vvCatSoSRMmXk2THRnyZs2augbOOfc8mmzJDH5qt9NcnWikeYsWNGrUGLr+hpvo/gceorvuuo+uvGoC9e7dly/W+0aruzQCCLJKhnsscqWU43OOTjMP8tfmzCHIgOMF1W5hB0nliV2rVq1oFE9qRnIbzGMFWiy9XaM8GCilBGfTkscmkANYgqIM8XWJ26qB3D8uILgSGVanoN1gZfJkjEiR/IkacEGExc1jqRLQDE5ZbMoz5WzMdDDJZJ/YX0LoRHFmLq4RGGZ6d9i2bdtKG9atI6UUB6EbF/suNWzYWOpCnai72CssQxXgRvGOO2bS+vXrpdUITAwbNpz7/t2E4E6nTp3Edzh/33rrLfra+XqZKOeRYIXKOj7GUGndujUNHDiIsEpp4sRJMnHH6imzggU6pQFmzrydFixYIE3Br/n4Vf4WDvxdyTfpp3DQz7wI/JdffqFnn31G9AqSYLLx5JNPEh6tQb/Gqp3LLrtcvu6HusxKoe3bt4t9HJuC2IduSdSBeqIBbcZ5hF+kIdtnn31pyJBLCP7DJKWp8+ggzrP7778PKi48+ugjNHfuXKHh49NPP52mcDADgSoEMMyjJKtWrZKPGIgiJ6jTBCmUUnTMMccQVh/edtvtdN5555F5DBF1JjqpxKOKCMSxecJqhJ49e8nxQVvQLrQPj+VDnmx49NFH6Yd588Qs6jnzzLNo6tRpEhjGvuGcmfd97EvTpUCSkkcLeSySVH1cM7fffhst/PtvkWNChOAD3p82ZsxYOuqoo2SMwj3b7NmzyQ6wSAEree+99+Q+xLDw3i5zzhqenRfnmPDll1+QCT604HsvnLPnnHOuXX2R8F19LJ955hl3BR2Cwxjv0J+6dOkiX93FscB1ADuZ1/0Z5AUBMwbiRwWllKyMHTdunPSlU0/txnOCGmIOHw+4+y5vhSiYGHMxvgOvWLEi4YMFCMwceWQnsPIEjEc4X8z5hGvpoEEX08yZd3Dw/mJq0byFlMd18cknnxC8pBK0bckS/aQRxrXych9bfLVHHwPcR4wePYbQZ9F3cX1F7ejTTzwR6wu7v9eoUYN/cDhfysKf+FEDZXF8Ma7Dn6AB0fUeccQRlOixx4dGcG2GncqVKxNWk6FP4pF6zF3ee+9diASSeb6KQSsx+4C2YMxHv0n2fYJVnYviHCnpaziRrh5BZewrKHMPBrzEgMcJU1fUzMxhO1wnAzNoTgaemMLkDUoCXEhvQumEGYxAzdMHxUxrE46oSiKSYg107dvzBtr/gtuoyj6HUUbVenxhTaX0SjWpeqtjqfmFd1HF2l6QYWvAS+Wr7teBKu91YCBUqL8/7dzkvZRV9iYgSckoT837zaTGJ42gqvt2oJSMTErNrELV9j+S9j//Vqq63xGu/Wx5xCrAiMUqX7ORS21dMd/F80Oq7HMoISjVuOtIqrT3weyP+qRS0ii9Yk2pv0nXUdTqksdIpabHNbVXt3HU8uKHqFrzo6hc9YaE8hXq7kf1juxLzfvfRdVbHi224LOcBN53hoASVnCZAFf16lWlblxId2brXxaEUYDE/FqMIliZgNwG3IyOHj2WLrpoAGEyh68Pli+fwRfSavKr8skcmLrmmusIASS7nMGb7LU37dW0qUAFs1LICJ28evUaIoceBnyHLcvu8UsR+AZwM4iKjb8AABAASURBVGHkWMZv+HYe730J55xzHv9yPlaW59arV49gq3xmOdmP4084gUaOGkutWh9gzPtypRT3B0WckP7zOqVSzGfmunVradu2LMYo5qtSSinKzcmWVT4pKamEgNdIDnaNGDmaWvCvtkTaBsmfjQsjj4R1eTMKXI1BY3OvySxzCuFqxvwsnngqpw3wS81a0UFpxWW8DYMdwOMQl1YC5P4pFxOE6yEOZrlcbmx2To74RElJJWq7S7L8v2WUk5srj4jVqVOv2HYLtvGIHOpCncmsCDc/sIcgEHIDublyMIXEVzoFSTCx9SORXF+pXPYXGNgX5AYiOE+ZMDmjBdrwaypW4CDHzU504aVLl9Ljjz9O9957T7QoLo3VUXh596JFi2RVoq2IiQBu9Fet0tc8jNG2PDeO//LyjV0+Gjd+yXX8Fy03NAIYU6ZMpg8+eJ8Df+sM283Xr19Pb771Jl1xxeXuo3eukJGIcxwYjbthBR0ewcPKuNj9zuVJ+u+Em/w333zTZyPX8slO5wt9PgWLKGwdpv0mt0wmhH777bc8GZlOeIkugg52oVz2PVbI4OuIeEzElgGfMWM64b1a5gXy4BlAMACP2F533bWEwIThI8e+zpw5kwOUsfcvmAihTTfeeAMF1YnyQYAPJ6Ac6rXloN99913Cfhj+Tme1L+jCnp8oC0DfmzBxAr3//vuEPgKeAdT99ttv07scqDG8nTv1ygVD55XnFuD8KeyxMOdNLh/roLbk8DXe8HP42mbwoDw76p5t9erVdN3U66Rvbor6IheOM1ZH3XzzTb5AaJDdH3/8gaBrZJ9++olBA/OijgmBRh3mF198IWMq3g9kfIb7TNy7QSXR88mUDfJpYY8l6s8LIlHXpiBdnMPos3h3kn08cZ5/8MEHNHPm7XJ/E1TW7BPeqRkkz4+HceG+++4lBLOMLVMG9SNoMW3aVMPy5RijvvrqS7Lv/5s08RYyRJxxPtoujGDsmz79ZsL4YY8NkKFerCgcP/4qwhdiwbPB2JN9tgVJwnF9hykE8LoW4LHRSJz+DFt5waxZs/j8vpfww4HxmdFHH8YxGD5iOAU9pmb6+9wPP6Sgd6ou4vuKmTzuR18nYX/WrJeoMMce/RHXXqy2s9u7jn+we+65Z/ka8hfMB4I5dtH3ZrZybgHGYOxDYe4TTLtNbtefCI7zFmMGzuOSuoajXYccfAgyQp1vvvmW4MWdKHtehT4N4EoVg2wOLbhJXKFhROesEInmaZqndBrhekmAov78Bd3qvYKinyJpMSQNOven2gefwZZ1FdvXLKY1P75N6379gLK3rqfyNRtLwIcVZNu69FfJ7QRBqZ1b1pKBHOsLh3gRvK0bD29+wUwOZumVWpHcbNq44Cta+9O7tHPzasqssw9hJRTKRnJ20JZlvwHNE8rVaCzySCSHtizNXx/K5avVp/163cT7rFeD5WZvp80Lv6V1v80l+AU6gKrNDqN6HXsBjYE6h55JDTpfSColTWRZ65fT2p/fJePPclXqUqXGbUWWX9viBbiys7Nl9cFUvjle8d9/YqugSYOGDd0i63iS4xIO0oODQ23a6naCtW7dBhnUly9b5l7AEfzq2/cCSk3V+wq9ZEAuX3y2bNnGF2MP7BudnTv5mEbJoY+bj+j6DzvscDrxpJPc1WdYwvvJxx8TntnGr+gYNCtVqsC/0F9KLeOsPFOKOzgbTklJ4X1nhDeU44yUUsyLyEqGCN8gQQd8AxHu0U8//TRh2TEuKtg3pZS81Hg0/2JrAl7QY0NcLMJApGukgD8tJw4ciZBtSW7YQngJV280HaajiAoYcI5BgHblsnKFzEyQwcD6WuAihIZGuAYAWX9OLQ4HlFWGuampqbJcOroci8r8hgvav4v0L/T16tenahzQTfZOwSZswy7qQp3AkwV9+/ahbt1OpaFDL/GZvPvuu4QPWbwJ9oMPPujqfPXVV2553ACjHCD6l87zzjtXykyefLWrDwRf6IP+hRf2AxkI+NohdHr16hko/+mnHwlBHuzLnXfeSY8++qi8EwlBncGDL6aXXnoxsFxeTKysGDbsUho0aKDceD711JN06623EOxh5cXo0aNkfy66qL/PTDz/5eUbn4Eowvinf/8LoySxJMafW2+9lX9B7kv49fmRRx6mhx56kK65Zgrha37RKwBsC2eddabsz7XXXmOzY/B3332H0CZ8uRE35I899pgEt4YPH8a/Po8l89Jsu6Dtk0R+8SxMHWgTzpGinEcIAl199SQaOXKEnD84j+BHHONJkybGBKrsfUTwE19NxHn48MMPE+Cmm26U8wUTZlyXbH2DY19HjhxJ6Bc4Vug3CG7heIOHoKvRTSTHqg6U69Ont5wDzzzzNO/L3TRq1EiZnN955x1ynOEru02JnJ+YSKAcIHplm2nbbbfdSqgbEzmcG6AvvXQood6PPprr1v3qq/8zRfLNC3r+FOZYmPMHfg9q0G233ea23fab0Z0zZ44rf+WVVwzbzRF0Qt/EGHXLLbfwGPWI9Jt+/S6QMRj3K65yHgjGJPgf8C4HLvNQFVFRxgQxkEeCVU0YH9H3MTZedtk4wkQbRRI5n6Bnxp3rr78eZAwU5ljGGIli2MfStDdKRUiMVePGjeWxc6CM/ejbuG5iX6HQvfsZcsyjg07mWoexBHpBgD6CY4hxNEiOFci4xiCw9OCDD8h4gnEE9d9+++3uarPostv5h83rrruO0Aa0C4Ev9D2jl995Pm/ePBmLMF7cKdfSRwgfZOnR42xCW4ICO7CN+rA/Rdln2IkHuL/G0wmQH3rIocjyhPPP7yvHBmNynop5CN9++y0ZN6+66kq6//775VqKewrch+AY5FFUPmg145YZNOjiQTLuPvroI4RxDP0XgFXj8coX9th/9NFHdDHXN2bMaBlb0Fb44bnnnqM33nhd/IFjFH0/ZI4drhvx2oS2oywA/SKenuG/W4j7BHNulqVrOH6I3r95c9lt3DMuXbpE8OJOItFzMmeeiJmY1O3QgnMCfS7CmN4UJnZK4yYF6ZZ3mIr1XJ6LaKGQSACsZ3FJqlfgiJARnacwlvQtLbMKNTpxKJm/ZR89QvNuPoX+fHI0/f7oMPr5rj6Erywa+c7Na2jHRv0FJ8ND/uNtZ9M3Uzq5sPBl79eELA6cQScvqLZ/R1n9BJ3c7Cz6g+v+5b7+9McTI7kNfWnHJq/OrHXLKZKT9yqm9Mq1ZEUa7O3YsJJytm8Gmi807T6BsKINiluX/0E/3dGTfrrnfPr9kaE0b3o3WvPDGxAJ1D7kDMntJCWjPO112uXMSmEg0Z83/VT64/GRFOTPeG1D8CFoBRcCPLjhufaaKXTvPXfRP/8sknoKmuArT+Z5epT9N8pOkyZ7yZJ5yABvvPEGjR0zgq6fdh1NmHAV3cOTXQSWIMM7X0455VSgSYPFi/+l4cOG+GDBgoWu/XvuvsMnM7r/e+VlV8cgZ53dgxBUQSDp7bfeoqnXXUOPPfYIPfTg/TT56omEX6Egq1gxkzp1OsoUc3PIEFRCjmCbUkpkSimOS/HwwMEhYXCiVIrwGHU3VqOsrO00h2/cJ/Ev2q/xDe/69RtJAku5OdSqZUueOI2ikaPGUAvGibR93e0p4E/LifV01fE1if9QP4BRLoEUoKhJk6Z0RvczOQhTjce3CCFAl5uTS6tWroQC8yTjxLLPqBIrjLBENgsVWpKIaAmKRBoQYUwxEKUwjbrgTzDYi8h2K8DntZcvW0pKwdd7UZ269ZO2f7CFPqqUItSBupJmfDc2hMkkbk5n8a+iuLEzj3EUZZdh87XXXiPcLOKXfAQSimKvpMrOnfshISD3yiuvyI8mmAAls26s6oJfcNOMCe8///xTWPNxy5VEHUGVL168WCYGOI/gR/xCH6QXxMPKg5dfnk0ATPYTLYsgEo7VCy88L8FCBCiC7CfKw/FG2/EIFq7v2KdEyyZDDxMdnBtY4VWYd8Ilow2FPRbJqDueDRxXTHJnzZpF6DdBP97FK1tUPs6H4hgT0PcxNqK/FrWN8crvymOJPoz9QxvQr+K1sTj4CHT/73//k/EEPyoVpH6s8vn8889jVlgm0k4cU30tnSU/GidSpjh10G/gf9TRokUL2meffYCWCOAYzJnzKmF8Lug9Be4X3uWANPo7VnAtWrQo4Taj3sIce6wExNhS0LYm3LACKGJMKO77hKDm4HqHe8BZfC+IcQ99OEgviIfzDNdvQH7X8DPO6E54ognzvXfeeTfIXPHzeJ6AShQSAGhMHjElA82gSHHqbe6czNIBD0U9LcyMySspJlAA4PDBA1gzSpBSvVYj/QcukY6caE7S0uqtj6XUjIpib9Oi7+if12ZQhCffwuAE77Za84P3mEFWgl8vLF9nby6tt+0JvAi+1kHdtDKn6375gNb9/jFjetu+5l9a++uHmuB0+9olnOa9VWrYylVI9IuLqeUrUdX9Oki53B3b6K9nLqOty/8UGgmCa4vfvhuoQGq5CpLbSfVWx1BaZlVh5WzfRP/MuZlyd2wXGkm0P6PbFi/AtSNrJ33+2Wc0ZfJEeuD+e2nJksRero9n1bsccywZwHuwBl08hIYNH0V4TA1tQgefO3cuUBf237+5K8dA9NKLz7syIN9++w2987Z3XuzdrBnYpQ5q1qxFeF4eQSrcTD///LO+NmZlZdEzTz9FCCBC0HQvvZIPuAHdsZWQJmAmhJVAijqUUm6nV0qJBjq0IJxkccDr9dfn0KSJV9KrfHOydu0GItZLSU2hlnxxHjV6LA0fMYpatGjJbF2eYv680cHW8LimgCOFgAEvyL55+i10080zGKbTpcOG0eGH6/NdKR20+4aP63ZuIywwC5kf2CQGOz8zDmUb4Pp5Y0UnZadgn5VSZP5ZuNttK1eukECUUkreibNX02aUnpFR6P1Mz8gg2Khfvz4ppcQ26ii0wbBg6IHQA6EHQg+EHgg9EHqgjHsAq6rxKCA+eNG7d58yvjdh88u6B6pXr04nnniC7MYPP/xACKgJUQIJ5lVuNTzfIgY9+2IuEJ6T8OSLCWyKE2YiYwybUkwwy9MhRjFPpOA/6FoSU9yKbzlStsEY5Jw5G9flYMUS6Kq2/xGOefIFk1wmI9lbeTLOObbta/IPMkEvs1YTZALbVuUdoVYpqVS9ZWfRxcFY9nHsy/tyt23Sck63r9Zfc2E07pZZ1wu87FiTWFCoBgf9UjJ08GrTou9p63/zY+zv2Lza4sUekhrNO7nylV+/TFkbVrq0QWx/RretU6ejqfuZZ1J15x1cWRzgQsR48pSJ9NBDD9Dy5cuMmYRyvLMKX4QxcO6558nLK9PTU6X8xo2b6fnnnqUc6/0SENSrVw+ZwALnC2NCWAneB2FI1GPwXZ5bDbB/1Vm+fLkl8dBVq1bS6tUrSSlFtevUkfcqGSmCV0TcMXmQUErJKiylvE5J/KcU07wR5YqcQDNfl2UkYMNjZm+88RpdPWnn65NCAAAQAElEQVQ8zZ79Eq1atYpUSoqUb9GiOV3Q70JCXwgoyiypjHOzRdMOn9vsYDLWlC+fyXV4urm5uaT4H8Ks7Vn04gvP05xXX9FFFGcycCEBwTQ2kCgD3IAlNixiHf/+R0gpTzFCvHuon3kInAGYtVtuCET9vWC+vLOrWrVq1KLFAVS/QUPCBwoS3WHoogzKwgbelQCbsJ2ojVAv9EDogdADoQdCD4QeCD2wO3pg2bJl9Pobb9D69esIX5NFoGF33M9wn8qGB4477nhpKOZ3CMIKUUJJzJyK51pe1TwD483Qogu5xcO8UPhGiXPQ3iyOGbxF00TgKJ6+RgQj9w98l+AJIFnyCJm/2KiKkSSYB6ll1vGWd26c/3WQCqVXqe3yEwkyQbmc/SL4//4CKy5UqL8/pVWoLvKt//1Jm//9QXA7waOIht6+Ou/AGfTK1W6KTGD7qsQemajUyHsZ+aZ/gr/+k1lrb7GJJHfnNmQ+KG8F2Nb+/J5PZgh7X7blEbTDoH3NNZPo0UceosK+h8vUGZTjhXzXXTuZsDorWl6lql6VBv46vmggj4Z//lkkJzP4lSt7+qBLC1TjiLpSuoNlZmbSqd1Oo1NO7ebLwYMGAjNpaWlU03oZu1K6w6ZwEAr7BB3k6KXATTnElFJS0uTxPy3XKRfXSJwUAcZ33n6bA16T6JVXXubyipRKoUguaohTSNg8MKBSBYJxzmLqEhkneqMIG41YL4zkIiT7xfL0jHQ64cSTaJ999wPbqpyFGPE0V1JwBDGJrp4U/xuWMaBcBmNor0trDeX41WLvluimTRvpz99/pfVr15JSEapTpy61bt2G9tlvfw6u1qVKlSoTfoVMSUnlY5IqOHi1WQ860EUZlIUN2IJNCv9CD4QeCD0QeiD0QOiB0AOhBwgBhb59+1L//hcSHmcMXaI9EKYl7wE8mm/ORTwZVdItUKQSrxLzM0tdgloxk0o2Z+kw5c0OfXxMCpnBm9cE8FDCAsgtEmgKkmRDuRr6heSRPF7wjpfRm3q3BXxx0cjsvHz1xkJGcrNpy7JfBY+XVKjnTK5ZYXuc1Vd2G4JWWnFR35ZZ01tRFvSVSJ+yQ9jBuW0rvfdBOWLJKtTzAoNZAavbytVoJHp6v38XPDopX1P7BvxtKxYgCwR8neaqKyfSOeeexxPhSoE6+TE3b95KLzz/nMDLs2fLiiGUifBJ/fZbb9KaNatB5gnRwZEgZUzAg/ilgZfrrBxq0aIFnXXW2XT22T0k79HjHMnBq9+gASmlg1rwjd1upRTlxnxFSbE+a7FMKcUIiW9RFvUJgxN2M6d5b/XrN6B+/S6kU07uxjZ4eHHaG1zKDBZcJ2+2TnBdbA9FWBfPpM/7YR79+MOPhGW0CxcuJKwsw0iVwgGnGtVr0GmnnqZNsr5G/ClMaY6l4KBckxaJkmYKCq4mURUoAUWKIryvIIAj350Bvv7n30X0119/0MYNG8QXlSpWogYNGhICjC1atqY2bdsJAAcPMujAjyiDsrABW7uzr8J9Cz0QeiD0QOiB0APF7IHQfOiB0AOhB3ZLD7hzMmeO6ttJ5VGK52IUpIOJh6eWN+bqAlFaFyhAU/4UKq4MhBYnPdCFIJd5nxS+DBiJ84L3ctV1MAzN2LIsOHgDmYFyVetRWsXqQu5Y/5/vHVXCjEoya3urpOIFutw28Gw+kS8olncCTqhqy5K8A23QAdhlsLIMvGgoX8t7h9O21f/4xFiplV6xpvB2bFwZ9wX45axA19aor0H+8uvP8mLg7OxssVO5SiU6+eRT6PobptN55/WiypWrCD/RZMOGdfQWB7QAc+b8j37/7TcpqpSik07qKvjunCDwhCAO9jE7e6e8i2vnzhwO8GTT9u3bJd+xI1vy7dt3iNwEX1AGIDZS9aOesAUafIlUMAJaKd1REeSCjlKaZrFsSvlpMBs1akQDBl5M4ydMpMM7dKC0tBR5af6atevp/ffjvbQQdtzRAWaIu4TkMYmjZqr+6qsv6emnnqSnn36SnmG4/7575UtB5lzLyc2hOvXqUrVquu/G2GMGbEVkxx3jzAOpSAHTABSgKTdFCcNGDl/Bd67CHoJs27qVFi5cQL/89AMtWrSQg81rCC8kzdqxgwOduQLAwVuzZo3oQBdlUHYPcVO4m6EHQg/sMg+EFYceCD0QeiD0QOiB0AO7hQeciSLmXrI/Di04J4nMxRTP86QYJnNcRm8OoZgSFAjjvHmkx2O2bLAjcqGQaCrpga6K9ZvDukDWmqWSByXlqtcXdk7WZtqWwIquCg1bij6SRF4cX956n9f2VbErqVIzK1NGlTowR1mbVlL21vWCx0tSMspTRrV6Is7euo6yNvwneH5JueoNRAUvoo+3aiyvtmZUriXlkSDAhzwa8HXJzNp7CRtt275+ueAmwSOK+Jri1Ouu9QW8KlWqQCd17coBr5upZ68+HIyoZooUKH/vPS+A0rZdO2rYUK9AK5CRMqSslJLAAToxvi4zZPAAAlwyZCANvWQwIQeAN/SSQSIL+uoJgjIA2GGT4gHdLQWVBI89IsgFHWFYic3ba6+mdPHgIRzgmkSHHnoopaenSxvXrttAs156ifDBgQ8+eI+HFMtAXNQbQEy7XFVHJANKdGNZCfrr1q2RQEtuTi6ZtuMLISyO3SLMAnAWtKmoFitbiRuhWG6KI09NTSGlwFUcKwPHLrD74zifNqxfR0sW/0ML5v9Jv3OQ+6cf5xEAOHiQQQe6u79HysAehk0MPRB6IPRA6IHQA6EHQg+EHgg9UEo9gJmV2zSef/FkyyUF4bmX5Jxg8YJPn3lCK0asTesxw+W7CDN5E9Kby3kkeKCQsx5vqB4cIk7RPuRElMKQ1M0EdmA0a13wS+Zrtj+ZUtIzoUJZ6xJ7EXrFut7jfdvW/Ctl80rSKtd0xUErumq1PYkIXiGiHWvjB+RYLFvFBq1IpaQJHv1VQ2EGJGmZVSjFeRH9jo0rAjQ0q4IVHNy8+GfNdFKV6n1NLSW9vMP1Zw26DGCGPpRZeXw98t9//6GggFfFipl04okn0tSpN1KfPudTQV+2OG/e94RH1rgRhMBM164nA40Be+VIpUrBj03Wrl2HD4uSstu3e1+WFAYnOdk7ONVbPBt4b5bWIMrhYIvBk5Vv3bpVAjiwl5lZAVkBQHdKpZTYSEnRx41I7zPJX4SUUpRZoQJlZpYTfB0HrOzAlqhxgi9TXjJ0GF1x5VV08MGHSICL2bR69Vp65eWXafLVE+idd95iP2QTykcgDITo+rWSjBUa5dQrzc0juwQLnY25rJaWnkYqRbGOknrXrltLHHnC5ug5mdK5Yk2NOakiAoZBEDkA7UfugfJQB1MqReqzyzmiMAs9EHog9EDogdADoQdCD4QeCD0QeiD0QOiBJHiAp3zBVqKmaDIvi1FmJd48A1DQjHjzT9Jip4hNGJxtGJS1zCyb0eRvudk7A4026NzP5QcFoVyhhWRYj/dlJfAi+Eicuo3Juh17GZS2JxA4K2+9CD9rbWLBuUgk160jHlKpSTsyj1nihfjRj3FGcrzATsWGLahmmxN8puoceiZV3e8Il7c94B1frtBB4gW8KnDA67jjj5eAFwJOjnpC2dwPP3D1Dj7kMKpRwws0GsGKlV6wr0FD79FVI0fevLm3InDN6tVg+WC1xWvYyHsvma1Uv75eLQjeiv+WI0sIsAoqEcV/Fi2SYAp07bpA29ChwxHUqdNRdNBBB1ts9D7uhMzBipoI92SlwOM4kINzJvY7d+4igUNWpcWLFyHzwRndz6QrrriKDjywvTyeCFsrV66k2bNmkR3gYmPkVMG5rstnyCXQLpYjA7h8G2E5SEfuUOBoQOMZq1ihIu8Qb0xv355F27dtYy5x/cR/KOyUdFBkLPC2GIYROeVAAgUAZ8D+40X8jJLif+QhhB4IPRB6IPRA6IHQA6EHQg+EHgg9EHqgDHugdDed53tooEICwDwOAJxB8bxMgl2Mm00BgQ4AuIAmzLxVWJxAV0uYCNgwB9RsaGqMZ6HJX9FlTCOvsu9hyHxQq/0pVKlRW5eX6BcXM613UOX1snVjOHentxqoxgHHG7bkNdt1pYoNWgqOJHdnFrK8wTmAUCpfozGlpGUAzRMisvpIB7vweGLVffz+SKtQjZqdPdm1sf6Pz1zcIAh8bV1hvjCZQvv1vYVaDXqI9j//Vmoz4jna59xpRlXyRP0J5XgBr8wK5eULbdBJFD755GP67z/9OGf58hkUtKpr0aJFrrmDDjqI2rTxzgMIqlWrJu8OAw5Yvjw2SLVsuRdkPKJDR8KLtaFr4NDDDic7WDZ//nwjCsw3b97o8tu1a+/ieSGLF/9LWzZvFZXGjRvTCSecJLid9DjnXHmU8ML+F1H/iwbZIsb1KidGZEPAC4hSCplAx45HUlfnfWfovH///Tcp5cmhhGBkamoq4li0Zs06emX2bLp60kR3BRd0RCjlFJdnDp/HirPgzZJYqKcLph5mJAXpCRljBm8Z5cpRRrkMSknBfuZSVpbTF1mGJV2KFOuKBc55E1QSJpyNVWIGRN6PaJ6jLVlqSgopBeB6uSJFSvhhEnog9EDogdADoQdCD4QeCD2wO3og3KfQA6EHitsD8eZfMtPi+RkBuBGYzSnS8zDOmONtSimPYMy16WOjLAvdDUKPx9NYV0I81wOhNRgDIjwguiUpzE7qtmH+lxTJ1S89r1B3P2oz/Bmqf3Q/qn/UBbRvz+sZbvDVF/3+rOqtulDzC++MgYrWO7rqH32BX95vJtmPTKKCnZu81UB1O/bkgNI1VL9TX2p21tXShqx13uOKtQ85Q4JHjY4bjKKBsGPTKpdfsVFrOmjCe9Si/12+duzTY4qrAySXA10bF3wDlCGFmrP+3meMp4bHDqKmp19B7cb9jwNuLVhGhEcOl37wgODRybIPHqJcJ3CnUtKo6v4dqWbbrlSpcVvatmohrfv9I7dIIu87c5UdJF7AyxEnnH3y8ceu7uEchKpQsaJLA/n1l5/pp59+Akp4xHHEyFE0bPhI6t27L1100UCacs11hC8VQmHTxs305ptvAPXBp598Qli1BCZWoF01fhL16XsBnXV2Dxp08RAaNOhiUgonONFPP/5IS5YshmpcWPyv9xjskZ060dRpN9CYMeN8cOih/gAljH344fvI5D1Y5/XsSZcOG06nnNqNEOAad9kVdOKJXvDru+/MOcBFrB6qlJKVWDVq1KIhl1wqMGr0WLr2uqk0cNDFVLFSJdkXtPHzzz4lBLzI+sML7leuXC0ruCZNvIreevtNMiuajBq6OXCURdWgAeDFAy3XPuQmRqn5+VoXKg7GWe3ataXdjMpws916BNXwUEJAmxM034QLK1J+NeyUxdH7yYoWL0RDD4QeCD0QeiD0wB7ngXCHQw+EHgg9EHog9EASPKDizL/cGVfUfCy6yojMCD1ujD1HpDgHcOZsugbD8+al4BuuDnkFNSHpJUQqYwAAEABJREFUgS68cH39717Ao1KT9tT0tCs4sHMl1T64O+GdXFuX/+E0ngj6LsEIVj3VaH0cRUNq+cos1VvV/Tr65QecoAVWuvS9e2nnZh3sUiqV6nY4h5pykKnuET3ZGxGa/9xVtOGvz6VESlp5CR5VaKCDTsKMSjb89SVtXvity02vVIuqtzrW144q+xzuyg2ybO7DlJutV4yllqtE9Tr1pSYnj6b6R/WjjMq1CX/Z2zbQX89eSTs2esE08A2s+m4O/f7wEAlo4THLnVvW0Po/PqXFb99Jvz8ylMpV8x7Vi/dlR2Mrr/xf5x1eEyeMp/wCREF28FW/9ev1CqnKlSvSiQErnZ579hlau1a/+B+rkbCy6/gTTqBORx1FVapUEbM7dmTT7Nkvst4aoe0Eq4NeeP45+aIh+BXxuOVxx1G3bqfREUccIQE08PFOq6effgponvDmm6/TsmXeKrEGDRrQAW3a+KB2nToxNl5+eRb9+ed8SklJEcB+9OhxDp1yyqnUsmVLaUdubi4tXbqU/vfKy155r4dK4Co3N4ewD4cccgjBRuvWral+vfoSQEMhrOSaOfM2WrduHUgBY+Lll2fT1ZPG09sBAS5R5B6vlBLUTgJYjjjCOYAzZ0BiEyAcgAzANjnzyxwViFiglCK8jB7HGIGvqlWriQKLCSCESYQhieawbY34UwySAFeT6yG2ZmgEuVJSQCnhQpfCv9ADoQdCD0R5ICRDD4QeCD0QeiD0QOiB0AOhBxLzAOZUmF252jzPc3EgFi26Fg1xNIgOz9aEb837LFREOoE2kd+kIvOHMpBpDqfO/BDypAe6YPSvZ66gNT+8SRFnZRd4gC1Lf6UFL06itEo1QBLePwWeEE6S4XzZ0CETyvDFRATQbOWsDStp4SvXk37sTz8+CPn2Nf/Qgpeupo1/f0P/vnE7bV78A5lAFIJI0IkHvz16Ka36ehZlrV0cs28os31N7Oqhdb9/Qr89OIh0AMprB/RzdmyhFf/3Iv14yxm0adF3YMWFDQv+j4Ndl9D3N3alb6YcRb89dDEt4WAeXnJfvkYjKZe7cxvXM1/woiQrrXdpGTs5OTmEQALonGy9Yg+4DTt27KDPP//UZR1+eGzgb/nyZTRl8gT69NNPacsW/d4mUwABrj///JNuvvl6+uijuYYdk3/33bd0041TJdCUy8EkW2Hnzhz68ssv6Lprr6ag/bB1gaPNt8y4mb74/HNau2adG2CCzED2zuD9RRte/d//aOPGzdz5UsQ/8BEAPHyN8tZbpscE7CBXSol54NgHpRTbUGJj5aqV9O2338pKrdtvv5U2bNggMqWUU0YysZuTk62JoBT60tkjXJ4IpV0WBf2JBkHHSMExOJGhvAFHcyJEIkNOtGrVakKQS3HQCXmKSqGhQ4fReT17U7fTTqdq1asTiT6RxNO4mLbDNDYQzANqg1IQ6CLCB80so5rD52gu7y9aBxCdMCmIB0Ld0AOhB0IPhB4IPRB6IPRA6IHQA6EHQg/4PBA0t+JpGE/MeCbG8y+jDB7mt4ZGrnjeF80TewpSgIvI1BAcDeADYqphMdfLKTZUrylORZ1zFhRLoCsnawv9+dRYDsh0koDMH48Nox9uOZ1+vL2HBJi+vbYzfXFZK/ryyvaUm+29bJ3bQ38+OUZkkCcKX0/uiKIxsOaHt+iHGWfQD7d0p7+eHkc/zjyH5t3cjVZ/95robl7yM/10Ry/66qoDpc5/37hN+PGS7G0baf4Lk+i7G06iL69oK2XsNiL4FFQWQTW04ZtrOnOwagjv4yiaN70b/d+EQ+nvFycTgnJB5RLhNewygFKcLztuWfobRXJzEilWYJ21a9fQgIsupIv696MpU66OW/6lF58XHehdddUVgXqbN2+mRx5+kIYPG0LQmXn7bTR16rU0ZPAAuvGGafT3ggWB5WzmwoULWfc6GjFiGN126y302GOP0g3XT6Ohl1xMD9x/H61fv95WzxPHaqkHH7yfxo0bRQMH9Hfbj30AvPPOW3HLv/LKbBo18lIaf9WV9NBDD9KDDz5AU6+7lsaOGUnPPfuMBKm4a/rKK6UI7/lCXYMGDqBBAy9i3/aTHDhW1N1379305puv0xb2lVKKMDgAYIhJZIkBK6PzEwYY4pbofs9Y9OYItLIrBFfGC+GAAqLYGudM8saIYtAYI7RzZxYt/285IcCVkpJCuZFcqlSpErVq1YoOPfRQamx/RABFGWSwQ2EDzFO6FsMRH4BQSAxwew39MJ9T9993D+VwIFZxWYBRC/PQA6EHQg+EHgg9EHog9EDogdADoQdCD4QeKLgHguZV7uyP55ueRdYEzXM0w8M8j7mGlFxo14CL8AyOxUIqBxGCYBLATN7Ag5xR3sAHEIFnIEJFC3RR3n8IDK3/41Na+8sHSVlplHdt8aV4PHL1vDdoy5JfqLgCQfFr9yQ7N6+hdb9/TGt+fIcK8y4tz5LGquxzKNU7srcmOF3320eclq1txX//0Q8/zEsouBW0Z1u3bKGffvqRPv5oLv3115+Uk9cKpyADSeL9x4GdLz7/jL784nNatGhhVDvQ4YIqQif185XSQS0OSYlAKU0r5dmwxg3RiU1gFwBJhExRNwc7HkApooWmRodkpsUBCmCut2kG2vf6a6/S9u07JMiVwjYjHJ9H0EtsiZpgZjc9EwZzxIZELsUYsUU2ziLetBbqAzAj3EIPhB4IPRB6IPRA6IHQA6EHQg+EHkiGB0Ibe6QHfPMqTPaMF3ieJ6g7KWMEcsMXISd6isZI1BbNBw3guSORIIQ/mEQeDUZDy7luKQctVbyBLgr/kuKBBp370359ZriALy4edNXb1HrI45RWobrUsW3lAlrx5YuCh0lZ8YDumnqllg5omZabzqplHA9ihlJaX6dGMyiHBgAy5No2mwDD7f5CSIJBAXrIuS7wGOUNWADAXgDbYcHSooWL6N5776Q//viDtm7bzgHmXMrNCVhtyMp6HxlxypvMN6CCyfsPLQBIgLIGQNDk7GQMX4S7d6IyqlNq/WMpo8UwKnfQjZR51NOU2WUWVTxprgBw8CCDDnRRZvf2Srh3oQdCD4QeCD0QeqBkPBDWEnog9EDogd3VA+7ciudjBDA7GmEEoDjnDSiRQ1D8P3eeJwWMPhO8eZNVEFqG1JnmsVFQnLEiNDhzajR8yCgMdGk3lO601oGnUq32p7hQs21XKlejsdtofEHyzydHE95V5jJDpMx4QCklbVUKASTprqQUeMrJiRRxAMrp3VqDGYlsUiZCSimGeAWUI0AOXSYZ5S1OmQgr8OZkjPEGbc3QKdGKFSvoySceo+unXUvTp99MeDz0wQfup/nz57O+tylSHmEwZqlovuwL+8HoSG5qE4KI95P2oD+VUYXSmpxF5TvcQxWOeZnKt72a0vfqQWm1O1BKhYaUUq6m6w3g4EEGHehKGS4LG7DlKodI6IHQA6EHkueB0FLogdADoQdCD4QeCD1Qhj3gBaZ47uXMyfTuMK00hhSoqwtGXGBN3giASJXoMcGb5oEBgu0zqlNGZDMU5MzgzHCY4k1TxfroItcSbknwQEbVujFWcrZtpK3Lf6cl795D82actksfDY1pXMhIzAO+QUIXUUqRUjrgpVc6aT66q1JKE5wq5eFMxtm4lKvHQw6TUHRZIGLAscu6vJkFUqwFijNnExuOqmZ5cpFpJqdaaePGDbRk8RJaumQJbdu6lfnWJipeeZEwyS0WVBKm2THuMCg8J4HIQfeYTHEAK6PFpZR59AtUruUISq3aqtD7jrKwAVuwCduFNhYWLKAHQvXQA6EHQg+EHgg9EHog9EDogdADZcQDmOgB4jQX8zKlZHIXR0OzRQPKmnRSZvDmEJyBEE3GCVNB8v4gA2iOv0pdJgx0ad+U6nTezafSN1OOdOHrqzvQ/zH8cOtZtPiduyh3x/ZS3f6wcXE8YPVIE9RCDlBKd1C7JPiGtnHD8+USRLNtaBypiHzKIMxA4eRQZLaT+TAiBOLICoIR/3masO8LUrEUm2M5NlhlBFAy4JnTHNAwrCmdgmY/QQQQJniMBNXP7LK/qXRKa9qTMo96itL3OodUavmk7RNswSZsow7iupJmPDQUeiD0QOiB0AOhB0IPhB4IPRB6IPRAmfSA4vmfNNyZawF3eSAcUE5uZwplo+Z7mKtFsbgIzzE59W9aS4EJFAB7DIoBbIA0SxJQGsJAl/ZDqU7xUv+dW9YRAAC6VDc4bFzCHjABK6WUW0YpDwdTKSXdWCkFUsBChY5JHAVjH3KUlrEBBANozpzNTzlMCUrFSiLkmDdqnEcYtCZkihTT2MBHTgS+RxH/sY7LYJwAzI63sYEYDR7QYAJgF1P52bKVywieUqERlT/iHirXfAip1MyYVkciuZS94Vfa8ffTlDXvatr2WX/aOvcs2vJ2FwHg4EEGHeiiTLQh2EYdqAt1RstDOvRA6IHQA6EHQg+EHgg9EHog9EDogZLxQGmoJSKzQn9LNE+5TINFeH7mMhnReoxEbUbfZns8YAZI1w5SlDHzs6wyqSCTBArM4CwMdLETwi30wK7ygFLolahdd0ilmJbBQdPo1hgsDAVNgKgAyQeUYnuioy0oZWhYFoGTaDkFBIi0RKfk/KF+yxRzPbsYiTxtiw8tH8laoAEoJMBK2FiEzAWHdjLNdhogxTXHTa2hz+WVZSS1zpFU7ogHKLXyfjG7kZu1mnb8+QBt//g8yvpyKO3860HKXvEx5W5eSJGsta4+cPAggw50UQZlc9mGq+ggqEvq5LodVpiFHgg9EHog9EDogdADoQdKiwfCdoQeCD1QQh5QZo7ozL9QrUICcCZoTkZKuRJISfG/IG4CjnIpGzE29EzVo0QHpFvMRUSkp5FQAKllYaALvggh9EBSPGA6VyLGtC6CWLa20DI46A6KgJKRi8wQ+ebavh4k2JZD5m/DUYyxzzYsnjTRonU9TllRjThDWsSn5R+EWAQxgFHfJjYsDmjbGZbILR4lV04LLNUyiaY1Oo3Ktb+OUtIq+Nqfu2MjZf16K237uDftXPgM5W5f5ZMnQqAMysIGbMGmXQ51om60weaHeOiB0AOhB0IPlGYPhG0LPRB6IPRA6IHQA8nzQNAiAszBhK/sepiImpOJDlRQADlPCF1UaC/h0npa6bIsTRG6Agdx5JAJCkSLwkCX9kOYhh5Igge8jpW/Ma3rBYwMrcgORimlSCmVv7kYDV3GHmek78foGYbWJ0L95P6BC3AZDgK7AIfkzNLiihTsMNe3MV/TSmdWqljfJV09l+MiysUY4QZAFTwAwU8AFini/eBBlNEyvaU16kblWo8lpfxDdfZ/H9D2z/pS9uJXiXJ3ePuYWo7S6h5NGQeMo/KH3k7lj3qKKhz/pgBw8CCDDrGuW5BtwJbYZNsunxHUjTagLUyGW+iBsu2BsPWhB0IPhB4IPRB6IPRA6IHQA4XzAM+/eLIqZZXCjEtQK3HDWiTP0rMAABAASURBVBbPQZWTS8azOB8tTD17E74kmmlSLqIVNENrcMobmkXcHhIFKBL5Z0+6TJiGHgg9UFIe0P1QakOAC6AUB2m4tyqlXD4QpTQNHBBFghUDSjllTM4aFsqUvaExEW+McEQRJ/cyJTp+O44WMqWHGK3PBBnwOBpzUhb7hkSmMUYpKefoIPNXSMS0Iv2HagVjvyH32QOjDAIeV8xoNcbX8kgkR1ZxZf1wLUV2bHRlKVX2pXIHTqUKx86hcu2vpfSG3Si1RntKrdCIVGqmAHDwIIOO6HIZlIUhAGzCNlZ3oS7wDKAtaJOhwzz0QOiB0AOhB0IPhB4IPRB6IPRA6IHd3wOKlN5JxTmAKcxbOeOJnzsTwxSONVlHBFYSxVKsJcpeUVaOgMs5tggSBsVAmg8UQPrPaGD6p9mGo6kw0KX9FKahB+J5oBj4EQ6EOx3RGShQiVKKeAPKuQ52uQMIc22cSbaBNB449lmMcgBG2a5vLALLAuXgnPMGwrMCisEwTM4sb+NCvMmg5TEZgzIDZAy898xzNqahr0g5DCdj0qcHNo9ibAWYD4J4PoUySOAl8BltJpCyVnJFcrIo6/sJehWXs08qsy5ltBlP5Ts8QGl1OpFKyXAk+WfQRRmUhQ3YMqWwugt1oU7DQ1syuE1om+GFeeiB0AOhB0IPhB4IPRB6IPRA6IHQA3uIB3g+5ttTxZM2gM1kFuZ3hqVI8byVZ2y8GZ6giikAZ8Q6APD9VYBDAX+aj6pdE5rl6EaKsqLLsRFmoQdCDxTQA4qUUm4ZE4QCw+7YSilXTykFcQHA6EfYBmmgeEGuCEvsTdOwEFMtmDxyQQNtFVKKAgOXCUa9cg6P2dhQhogVyPtDQMuvpWWK9QCaQqqQaEABGPMq0nwnVVzWQcteptIpo/1kwvuxTOMjkWzK+mEy5az60rAotdZhlNnxEUpvcCIpKyDmKiSIoCxswBZsmmKoC3WibsNDm9A24jYaXpiHHgg9EHog9EDogdADoQdCD+wJHgj3cU/1QITnf9H7rsDAfAzzMsZBAziqRSQIyR/KKsUM3oQhiVNIcCSaFjVXDwiA57Csgqp0M8ADMF8XI6kPhcn8qTDQReFf6IFd7AGldEc1zUDgy4DNA26r2jhk8QH2lYwLwWUg90pjEBEAywweUhoMrQs7AFcMkQNS1idAGa6feSjjqLmZkpEJpELCIxZvbASDIkCYTCNXytFBxjj8JHwkAOYhc8uBKGOQttfZMV9X3PHbHb4gV3rTc6ncQTeSSquYtL2DLdiEbWMUwS7UbWjk+Boj2gg8hNADoQdCD4QeCD0QeoCIQieEHgg9EHpgN/WAcudqvIOYaznzMjJ8RfLHUz3JoxMFvRih4glftCYr8eZxNYEqwZOci+mCEVgFm4DoJkXI/iv0o4s1a9chgG0sxEMPhB4ouAdMsAYllVKkFAAUd2Pda5lnaPLhlM+fU5wD6xEpZ+j4xVA3QGtEdMapYsAGjsFBGwBf49x8ggZAcyCLEPhuvEwLJI1IaiVcUJGyGIxKYe0PW6JYT7FY2+DU2UElfMWSsrWpcjUpY99+vkbjxfN4lNAwEYjKaD6UVBFWcRlb0TlswjbqMDLUjTYYGjnaiLYCDyH0QOiB0AN5eSCUhR4IPRB6IPRA6IHQA2XXA1hAoEh5O2DmZWZix1MwS2i4LgvlXcJFfIWYC/tKl3VF4GH+R+RUSfoPfOg6ipxpueZzCVErdKBLSodJ6IHQA0X2gFLcUTlAg4AXgKNSbFNxh1acE+fcXbkDk/PHqg6Wf6aUtgFNlLNIsCxABTaQ1EuBfzxcsSrseWJ/PSx2RB5fRi4hIRVEdHSbwAMIi4jFSnFC/j9wXC1pgEuxIkudMtxCpsveltb0PMLL403Lc3dspB2/3W5ISq11OKXvP8SliwtBHajL2Ecb0BZDo41oq6HDvFAeCAsVgwdatGhJ1atXLwbLocnQA6EHdkcPVKpUiVq3bk3ly5ffHXcv3KfQA6EHQg8kxQPu3ErmX9okz7yiEEO6EmEoTOwE8xLwZBYnCfgaUQq4Ac0DhWoBMp/UCbMdZc5EFsUPA13sonALPbBrPOB1XqUUKaWkGeAi4AUAQ3dcYAUBWDH6Ec92xPCic9QNYD50GPKqF00FsLazcQHBFNcliDvUaErpTNSAC+LyFOl/zeCUxWb/mXI2ZjqYZNIADhIKEZu4A3KsqFRyVHoVSm98uq9tO+c/TPgSIph4WXy5dleTKoaVXLBvA+qQujLrChttQFuEcBK0FW12yISyY489lk455VTq1KlTQvqJKNWqVUtswu4+++zjKzJx4kS6//4H6IIL/KvkfEpljOjQoYPs73HHHVfglrdp05Zuvnk63XXX3YRjUWADpbTA/vvvT9deex3Nnv0yzZgxgx5//Ak57qW0uWGzdqEH6tWrJ/0H40WzZs0SbkmrVq3ccmEgNTG3lXafde7cme684056+uln6KabbqbnnnueJk2alNjOlWGt3fG6WIYPR9j00ANlzwMy/9LNjpqZaaaZAVrCoDkZeGJKOcUk40J6E0onzNAIefq+QiIVjqhKIrww0CVuKCNJ2MzdzAPSJZ190p1SKcWdWAlPKeXhwvESpZRHBGK23MYDlZmp6ydiXd7I+cuzGlNEdJ1CiI4x36FEEpz4NTDYAWxdxW0BeDzlocC4HuLB1MdF/SxTMWWZWcq31PrHk0r1flGObF9F2UvfdFudvu+ApL6TyzUcB8E7u1CnEaMtaJOh0Va02dCJ5AMHDqKhQ4dSnz59E1FPSKd16wPEJux26nSUW+bss8+mDh2OoIYNG9Jpp59GCIi5wjKMnHvuebK/hQnenXbaaYTJZ9OmTal79+5l2Ate06tWrUpjxoyhgw46iDIyMkSQkpJCa9etFTxMQg/YHjjssMOl/2C8OPDAA21RnjgCyygDqFu3Xp66oVB7oDT7rH379nTppcNobw52pqamSoPT0tJo+fL/BN9dk931uri7Hq9wv0IPiAdKQeKbV2GuBeB2KQbZHFpwk7hCw4jOWQFzOUCUSLFIs4AANOWl/kJu9V5BUU2RNExCD4Qe2KUeMB3UrGJSSpHBpWFRfdwnE4XgRPTEuB4QoswEFNJ6xPWL0CEFtxKY9IscChUwOBSXMJjJmRW9sb5muQgRowh8Acj681sBxYqWnJx2R5ezVUorntbgeF/Tdi5+mSh3h/BSKu9HaRwIE6IEE9SJuqVKbou0SQidRLdZc0tH+s8//1BOTo40ZuuWrbR69WrBS3OCFQbPPvucrCzAhCTZbV22bJlrcuPGTS5elpGjj+5MjRo1ll1Yv34dvf/++zRnzqv0ztvvCC9MQg/YHnAuETYrxAvpgccee1zGqssvv7yQFnZdsRNPPIkqVKggDViyZDGPGXPo7bffog8+eF94ZTUZPHiwHBOsTsPqxej9KIvXxeh9sOkQDz0QeqBkPBAh/e/W5lxMMRMTnkMLzgm0uQhjelOkCBtZf8zRKkAcvmIl16aLOEJk4AFYDyRpCyTVK3BEyAjySPjVRfZEuIUe2AUeQAdEtcgj3EGld0qO4BQAUgMILBkcuXRoIIEQcblKsV3eiCRxhgMK+NNyYj1dl2eDAv7ErFPEyViLMS6myzMpG/Mk1wmLNWJaAgaD4nrNYCUKzJPcl0REy2WhEWJHuSyODrq4DLIuVboRlVGdUqu2dBsZieRSzrJ3XTp9nwtIlcAji26FDoI6UbdDSpvQNkOjzWi7oUtT/s0339D9999Hr702h6ZPv7k0NS1uWzIzM6ly5cqEd8akp+vVSXGVCyF47rlneRL0LL344ot0zz13F8JC6SvStGlTt1FvvPEm3XbbrXzc76cPP/zA5YdI6IE9zAMlsrtYTYmxqnz5zBKpL5mV1K9fX8zl5ubSrbdizLiP7rzzTvr777+FX1aTihUryfUDxwUrW6P3oyxeF6P3IaRDD4Qe2MUekPkXkTv7Ao3JX4TcP+VJhReR+Rqjlg54KMpcd4NYGUoQcAAOEzyAscdskFK9pUZSvwoDXRT+hR7YJR5At0TFyKNWb4HNAEmEey5yJmVTSlPMFjo40Tpahl4PGjmRUsAp4E/LIbA1PC4kAEcKAYBZTsYYbyzmjREinUOqMeK/wOpZjMGOxflvtgE2zRuX0SkjRI5ckf6nMvKXUvNAbqli0Fvuxt8pd/sqTaSWp9Tah2s8wTQtleicIzPo4WGV6MOpVQWAgwdZgmZETermNoBAm9A24BoU6bZTqfx744036L777qOff/65VLavpBu1fft2euqpp+jxxx8je3VXSbcjmfWlp6e75r766ksXD0ZCbuiB0AOhB4jwmCL8sHbtWvrzzz+B7jEQXhf3mEMd7mjogaR5QPG8yjWGSSiDO/sCgvmXMhpAmInMYSnFBLNsM4oJNuNb5+Cox/BQXGSwIYhJeA7NqCtnnNguOX8pTh5moQdCD5SQBxC8iq5KKeVjKcU0b2CiTyuliaCy0AkGKcmDBYeRGFWKbciIEqTNMh87mnaEVnk2aQ0lkIPDuVNUUyA0JsqCIgHf0QUpQqbN5ogNqXMezKz6ecdIqShFR857zLF+MayLlvI0tWorXwtz1nzv0mm1DiWVkvjqnlpVU+jREZVoXPdMOmCvVKpQjgSAgwcZdNwKgOQBqBttMCp228CLbjt4BYUTTjiRrrjiSho37jIpipdE9+rViyZPnsK/tt8msq5du4qsIMmoUaOkbM+ePX3F+vY9X/gXXTRA+HhXz8CBA+n662+g6TNm0MgRI+nQQw8VWV4JXn7fu3dvGj9+PN1yy600beo0gs2gR0bysoNHFrH/yI3eYYcdJm0E/8gjjzTsmLxt23bUv/9FNPW6qdKGsWPHUZcux8TogYGXtsMeoHPnLmDFAF7SjUeRbrzxJnlxPfYNvBjFfBh2XfDvfvvtJ+3ES5/vvPMu6hxQf0H8OWDAAPHPvvvu67akZ89ewsP+wS+uwEKOP/54eTfPDTfcSNNvni7Hzva7pSqoOYfwfrNatWrROeecQ1OmXEN38T5ceGF/0bETvKi8+5ln0pgxY+VcuuHGGwk28FU3W8/GIUebUQf48M3w4SN0+RtuoEGDBpG9cg06QWDvG87lS4cNoxNOOCFI1ccriN99BfMhmjdvTpdccomcm7feehtdx+foyJGj6KijjgosGX3OwJennXY6XX75FTIOwO8YF8rn83U8rDTCo7+XXXYZzZhxC11zzbWE/g1+YMVJYKLPj+O+h+MIwNc/o80Wxc/wRUHOq2hfwmcXXHABTXbG1Kk8VvXocY6s/oluZ150gwYN3D5m3m211157uTzYjFceenjHIF6GfttttxNyHKd4+oZf0H035YLyyy67XNpao0YNEVesWFFoHDMcP2FyYvuvc8BYxSqE93yhHADvCAQPYJfF2If2F+Y8hq1E+zT8inbY4yGuC+ABMHbBHsCMNz2jrouQGcC4gXeY3cAzBNWhAAAQAElEQVTjD8bJCRMmUOc4fkCZ4rqGw3YIoQdCD+x6D2Be5WuFsudfPN/izchFF3KLx5My3mwGCS1WJNGlLVQzCJzo+R9E4CN3gE17HCaEHT66KG4Ik9AD8TxQHHylvK6o7XsdEoEsSJEjZqOUki6u9XTKLI3kl4pZTrgAbyQ28yzDulIplBjnDOU48zYFlBO98SAFGsAMZDEAO44MqMhBu4TLEcQkjlj59l4zldGBDO116bKLqIr6HUNmDyIb/zAopdQ6wsXzQ7Ba67aLKtD+DVLjqkIGHejGVYoS2G2w2wa16LaDV1Bo0aK5TH67dOlCRxxxhHwBCy+sR7AJkwZMjIcNG17gL2IdeWQnsXtA6wN8TcKkBDYPP/xwQtALX+zr3v1Matu2LbVs0ZJOOPFEDoBMyPNrjZh0IpjQu3cf6tjxSMKkvl379nTWWWfJVw0TmcCZRmECjPbgq4iGZ/YbfMgN384xqZw6dSqhrvYHHihtOOaYYzjIMoZGjx5tqwpev34D8QdsNm3aVHgmQXARASi8bBvvvTrggAPkxfXYN/AQGDK6ieR2Xe3atZevIqKdCPjsvffeVL16NZ+ZgvoT5wb2o0mTJq4dnDvgARo1auTygWCCjn0YNWo0nXzyydSmTRtq2aqVHDtMfhGoRLACujaYc6gtBxQnXz2Z+vW7kA455BBqyvsQrQ/+9OkzaOCAgfJVS5xLbQ5oQ8cffwKhbgS/bNsGN3Xg+COYgwDNSSedRFK+TVs644zuNJUDE8ccc6wp4stl3ySg5u1bWz6XT+56MiGwhEBPLQ7S+Qo5REH97hTLN0OQDUHNU0/tRjg3cT5j0o8JNAJX48dPiLFR3zo/0Z/whVC8c+joo48mlId/MS4geIXAaYwBZsCHN910E/Xn4C8m5i1atKCDDz6Yunc/k26/faY8GsxqSd3q1KnDQZtJ1IX7Hs69ChUq0O+//+aroyh+xn4X9LyyfdmyZUvZdwRD0G/gy/bt29OFF15I+CptpwJ8BbdmzVruGGIejatbt67Lw3lHAX8NGzaQwDmCbfhICI4f8v58nPDjQnRfMiYKs++mbFCOcwnHyAQ98bg4aEAnKwBr+69p06ZBpqhx48bufjdr5n3x1y5b2PO4oH26fft20pZ446EJ7GFHzHhzQNR1ETLsE37kwLihx0m+JvI4ecQRHQnjEq4ROHYU9Vdc1/CoakIy9EDogV3oAYV5V6L1Y36mPGUEv5SyGEYElp7eCcdFwRcOEnAVSXEFGgAecgtcmeGpQj+6SOFf6IHQA8nxAMYCbUk5nRi5EpYJTiEXBieePhN5be6IwMMLjwdCBuqzUPhcJ2+COklwXdoeRek6RdxMi5E69oG6Ug9xpMywFByUa2I+b6KkmYIyy9Tv0uBZoIyCxSutaEoF/6Q8d8tit6kpFRq4eH7ImR0y8gxymfL7cyAMuobOL7fbYLcN5aLbDl5RAL8iY/KxZs0a+uuvv2jVKucRTjZ6+OEd6PzzL2AsOVvt2rWpR48eEgTGo3zz58+nTZs2iXE8EoegFSbnwrASTM4GXDSAsBoAbLR1wYL5tHat/tIfVk8gINKjxzkQ5wvLly+XfV26dKmri/Zg/wGrV69x+QZB3b179yalFP33339Sft26dSLGBPS4446nUznIIIwEkjGjxxACUFDduXMnLVq4kH755RfavHkzWBIYwqoYIQqYdOvWTQIMsLtixX+0YsUKysrKcq0Uxp8LFvxN8I3ZZxjDMQAPsGHDerAEEORBoAjBLTBQ97///kuLFy+mHTt2gCVBQqx2ESIgwXmAL7ThnT443jg+W7Zo30AdE+Urr7yKzIQd59Hffy+QY4MyOCbHHnusrB6BfhC0a9dOgmhoE14ajWOAtkK3WrVq1K9fPyoftZoJ+zZt2vWEgBr04GO8XHshHz9TFoEeBHMht6EwfrfLx8OHDx9OCLKZx8NwvH///XfasGGDFFFKcYCxo6x+FEZAcuaZZ1H9+vXl/FuwYAEtXbKE4EeoIvAQNA5gAo5VQo2cjxPAjzjOOFbZ2dmE/n7WWWfDRNIA/p80cRKhTTD6/fff0+TJVwN1oSh+TsZ5dfLJp1AjDvzi4xwYKxYtWkTbtm+T9iHgM2LESEo02LVp00Z51A99TAxwsn79eumL4NljGIvcDStdMWahv2KcxZhnhAjo4gcHQ5s8GftubJn89z9+l7biMW7w0EfQbgDaBV4yoTDnMc6pgvZpjBfYB/jXtH8BX5PAA2zbpo+3kQXlCNhi1SV+5IAcfQbHE30vO3snWHKNwDgX78cXKJXkNRz1hVCiHggr24M9EDHLG/gaHuMG5XEUKaIgnfgTNor5c3WBsD1WkDkpSMZjNqi4MhBaI3x0UfshTEuJB/Br4dlnn0MTJvpvFEtJ84qlGUopmWiLcaeTIrCllCIlTCJGGQxF8qeUnxZmVAI7RPnpQe5UTPpPBhON+lNHLV7VUs7R0QVBwL6mglLY0oMndB0NRpXdbsV8AGf2xmq2lhmCbZWygadX8rUzssMLbKhyNXyyvIiuB2XkJfbJCqJrt8FumxiMarvwipBUqVKFXn55Nk/qL6DRo0dR//4XEr6iZ0x26dLFoEXOMzIyCBOeu+++my6+eBCNGjWShg8fRj/99KPYxkQdj5wI4ST4xbtr166klKItW7bQI488LG0dOXIkXXDB+fTCCy8Qgg0IbJx66qlOqbyzN998U/YV+200P/jgA+HBB2+88bphuzkCHqgHL9wfOHCA6A4aNJA++ugjV+fEE0908bwQPCbZdO+9ReWPP/6gwYMvpmHshyuuuJzGjBktgSkI8QijmQSBThTQ1h9//EHaOGDAABow4CLCPqN8Yf2JDwzANwgswA4AK3nAA3z22WdgCWASjUkciJ9+/kmO89Chl9Allwyh8ePH00LnBdRoC3ShFw3YBwRMrr9+mhxvnC94ebXRQ1ATOggmvPPO29SrV08aMWIE4djMnHk74YuQ0MWqM6ymAR4NCAQs4YDO5MmT6dJLh8oxmDJlCvv/P1HFBLh79zMFNwkCPgjggEZwa9y4sTRkyBA5j6+66kr3XWxY6XHKKadATQD7muzzGIZbtWpFxx57HFBCYOrpp5+S44129enTmx544AHS1yWivB7JhS++/fZb9uFwGjlyBA0eMpjQT9FfYRxBQQS2gBvo2bOXG3z+7fff2A+DCccZx2rKlMm0cuVKQp83+kXNq1evLqtMEQCFrXnz5jE9EagLRfVzMs4rtBPn30033Sjn47Bhl1L/Cy8k+BcNrVChAiUaAESQDGMC+hjGH5THO65AAzAegRcNGNfxYZDzz+8r/Q9j1aOPPuJ+GRf9Av3HLpeMfbftAb9s3DgZh0ygDUE6tBuAcxQ6hYPgUoU5jwvTp++//37Zr3jjIYL6wS30uKgXYww4CLLjWohrAfrecA5em3ESK/h69+4DtUDAsca1rF+/4r+GBzYgZIYeCD1Q/B6QCR+ROzVzaHL+IlG0w/ZlikuLGiZzrsQhFDMEBcK42YSUxHAkhx1RFwqJpsJAF3wRwi73QD3+5XbU6LF0/Q0306n8639evxbt8sYmsQF6IIgQz5nFakRSK3EE6MAWV1BdVtDABHKl7MFAkQrUjGZ6Wr7iUHNEaA8ALBtEn3V4c4JOwGyNKBw7DIhiG1JFtVgZAXJugGK5XVwpBQlzOXjotEAYpTxRqZm+Fkayt3t0uVoeng/WrG5qPhqeuCC6ZLXB1zY2F912ZhVpw436ww8/7LOBm3hzk12zZuKBP5+ROAQmX2+//ZYrXb16tTx6uHXrVuGZAIkQnPTq1dudTD/99NM0e/Zs5nrbE0887gabEIDA40KeNLnY66+/Rq+99pprFEEABIAwoQfTTFqA5wXNm7dwxd99950EBAwDwR1MSBFAw4v9C7PqAasCrr32WsIk2dg1eXH7s2nTpu5qFazuuerKK8me9OERsxm3zJCgJdrUpUsXZDEA3yJg9eWXsS+8RzDUXLMQYLvjjjt85d9//3168smnJMCjg6en+eSGQODg/vvvcwOt4CPo+sILLwIVwMocQThp1qyZu29YyYHA1oIFC1iiNwQgnnzyCTeYcOSRnbSA0+Ly+6+//iofgMDX3V599X/07LPPcm3eBh7OB3Dsx6lA24Bz2D6XIUM//fxzHcDE+6H2229/sAUQYMPKNRBYtYSABmyABszjINTNN99MZmUKeEUBrIS6+urJtM8++4oZBHInTpwguJ0Uxc/JOq9wL3DPPffQ559/7jYNKzUnT76azPmCoGHHjh1debIRjOsYP2y7s2bNIow34JUrV45at24NVCBZ+y7GdmGCc7Ag53FR+nRRdhPj15HOuyBxDZzA57I9TgKfOGmiu8IaK1wxtgbViWNdktfwoDaEvNADoQeS6wHFMyvXIs+/yJlvuTyLjvD8y6fPSkIrRqxN6zHD5bsIM3kT0p7lMU9IJBAiZx5vqB4cIk7RPuRE4aOL7INw28Ue2Hff/Wjc2Cvk/Tjp6XqijhuzXdysYqre65SoQCnFmQFGZYuQUuCRTIyExUlBfeKY4JJ6Q/mIRgNSXZ8WRLh+B4voXKceAdt2CS1HylxW4w2EAw7FGW8Oz8lYHZgihcwDh8QgaJhov8F17ihpwpfa5XyCkCj1Hvjuu28D24hHMyBIS0vnsaId0CIDVt/MmTMnxs7SpUvcYE+1alV9cvN4H4ImmLT7hA7x3HPPun23SePGDtefFZVC2//3v/8FmsGkBILKlSvHPOoGfjQg2GN4Rx3VKca/n376KWGyhpVKCPgY3UTz3377TVbOBekXtz+x8sesFHnzzTeCmkA4txBQgrBWrZrIYmDp0qXyKGeMgBkIsnAmK/mwwg94NCBIgwAM+HXr1kMWA5BjkhgtQFkEwcC3g0N4HxICBODPnfuhPOYH3IZPPvlEVkRhFc6dd3oBuOL0O9qLFVQPPfSQ3RQXX7tWr1jF48EIsLgCC8HKQgRjLJageARSEE7MY6KMUqtWrd0v6X388cdgxQDO859//iWGX1BGWloqIchl2o5zB4HcIDtF8XOrVvojJTj2RTmvEMyyg1x2O9977z0hlVLUrl17wYsj+e777wLNom1GgNVvBk/Wvht7uyov6HlclD5dlH3EY91mtSOC9eYxY9smeJ999qmwoGsHzoXpJCV5DXeqDLPQA6EHdpEHYuZ1ph1RUzSZl8UosxJvpgjPehnVDIlVMaU3q6AWa7Zv7mgErGtQ1gpXdLETimtrcdphdNRlZxUYGh/evLialDS76ZkZVK5yJmVUyiySzfbtD6SRo8ZSjZrVXTt4n8AdM2936d0LQe/jTmh2yurJCOQopXiCzF3d4SsFfaNcyJxtGTNK5WUP7WI5MkBgdSwH35E7FDgauC4gMXwwGXT1KOxoOCgyFmPTEMPQbLIHNZgAkPOHugFMKluP6dK+RXL8789QaeW9Jmet9vB8sL9X5OSj4z67WAAAEABJREFU4YkLoktWG3xtY3PRbWdWkbaFCxcFlt+wcaPLz8y0/ONyC47gfTO4eQ8qaSbZqalpPjEeAwIDj6RMnjyFJgfA4MFDuB/rk7hGzeDACWwUBfJuu37PGB6frFTJ/1hsUJ1ff/21+0t9o0aNaerUqfKVu0suGSrvUgoqUxAeHpuKp1/c/mzQoKFb9SGHHEqTA44XeI0b65faxwukbnLe3eYas5BatfWqS4zheD8N7AUBzhkUqxYVPAUPgFVZyIPAvGMnLc07Hxs08N7fhxVLQeXAW7RokbxXCYE00IDi9jvqQODi7LN70KhRo+SLi1jp9vTTz/gCqThHoRsN9rv5bBlWyBgagTKD20GveBNt6CKoibwogP7dvLm+T/v77wV0zTXXxA3kFsXPyTqvlixeHHd3P/zwA8IjplComeTVsrBp4O8FfxvUl9vnfEZGOVeWrH13De4ipKDncVH6dFF20a73q6++imvKXtFa2xn3opVL8hoeXXdIhx4IPbCLPODOv5z6cQsMcEjMyyTY5dDIFBLoAIALaELPF4UhiegKFpzg/ktLbM3wq4vaJ8WUVqxdlartVafAUK5qhYAWlS7WMZN60ok39KNjr+5Z6IZlZGRQn779qGJFHSxbt24D3X3XnXTD9VPphx/mFdpu6S9odUL0ZDM4AHcar5TSE2VXRqSUVY4S+WN9lJdyistzGaYVZ8GbJbFQTxdMPQBJCtITMsYM3ogBcs6Y52HgE5PKICyVjXkEgRBOosARgcMgUop9Eq1H1h/LDYXBVJEyZOnPd272tVFleMGRSNZanywv4q3vduQl9skKomu3wW6bGIxqu/CKkOxwXg4ea8J/PsTKC87JycktUKGGDRuRCRzV5AAWvmAWD8wEvkrlygWqI1HlvNrO3TxRM67erbfeSgiIgIG248tseMfY+PET6IknnpSvU0JWGIjXnpLwZ+3atd0m49G2eMerYUMvINawYQO3jIvE2wlWqFG9Bqck73+KZx98vLsGihUrBgcfc3NyIA4E7ybOE9euXUcIBCrw4QAhEkiK2+94DApfbrvjjjupf//+8tVJPOrUrNk+hEf+Emii+7hltG6QH6CD/ogcKx1//vlnoIFgVpMFChNkmlVaUMfqPPsRSvAMFNXPyTqvNm3WgW/TLjtHQB/vGgSvWjXvB0fQyYR443q845msfU/mPhTGFs7HoHLx9ruwfTqojoLwTL1oLx7DjVcWfQsvqYe8ujPuAbch3rHGXZ2tF+KhB0IPJOKB0qGDeVVQS2SmhfkXgBVwp654/iX6ihnWppSfITqQ+9iY64FpAEKP578VQ23EtWkQROaJKAOZCh9dpGL8y9q0nbau2RQDpspcnmQFybO3Jz5ZNbZKOk9JSy1ylSee1JVqOiu5cKP+7DNP0rffflNku6XagL+H6qaiP2rMl8p4IAnfHnB/jXdj5CsURXAx4aAsqgYNEGacRMt1o5zqLU0/X+tC7GDIAGC54DGAAVyRNueSeSJcUOlRzFPDTnlUmcVyty7xtT2love4W+7WZT5ZXsTLX+6gP5fFnyybstCBrqHzy+022G1Duei2g7e7QlbWdh2A5h3ESjA8lpIf/PPvP6xd+jc8foWXVL/wwvOE9yxttFbQ4XG5nj170qRJVyd1R0rCn5i4mUbnd6yM3N53Uzav3NSBR8yMjbxyrFrOy16iMvO+KQQmcYwSLVecfscqrgkTJhI+WmBWXG3icwlfu/vii89p9uxZ9Lnznq1E25uI3s6d+r4J7+6Kfq+eXT4zU/+wZvMKiuN6ikdZUQ6r9IYNG0Zm5RZ4Borq52SdV2lp6aZJgbk5TlnWl1ADFUuQmax9L8EmJ6WqwvbpolZu15vXux1xnqOPob5dfr6gESGEHgg9UCIeiDf/4qmZrj+f+Zgb1NLaPJtTDubPwAV4XF2D4XnzUvANl+fJXCCoCeGji+yY4tp+fvETen/y0z74cOpzbnVbV2/yyYzuoo+L/g4Jt5JSipQrV56OOeZ4t3WffvIJffPN1y692yJeD7V2UXdU3DzrrqpFQR0WkkATEEQB7CmlbduiAJYjxqABAKlzfxvAA7BNzvwylGFgEac8gJk9AQMALgnfo0j/CUMSTbNtjfhTDJIAV1MaoMSmq+nsHLjQdfmlHIls8T9aoqrox2LQ7NzVXyBLCLI5xjX6ka15Brv+5EAYdKCbkFFWsttgt41FFN128HZXwEt6sQIC+7ds+TIaO3ZMvjB9+nSolxl44okn6PLLL6PevXvR1VdP4qDE52R+oT/88MOpTZu2SduXkvDnmjWr3fbOmvVSvscLx/Qz64uNbuE8kA3r14sUEz+Uzw/gXylQxGT1av2uK5hp0aIFsoRg9erV7vu8kn0e44XWJtCEL7fNmDGDevG5NG7sWJo2bRo98sgjtHWr/1HthBqdj9KaNZ4vWrZsGVc7r0l83EJRglmzZsl5tNh5JLBhw4Y0evSYKC2iovq5sOdVdENq1Ii/UgvvGTPvsEN7o8vuKjpZ+1749ns3IhkZwYFCe7Woc+tR+OqckqsL2aed4oXOTL1KKTLvRwsyBplSSkQrV66QPExCD4Qe2P09gDmVsmdczjjg7rlFi65FuzoWIjrGnjfcynosS81BoU3kN6nI/KE4ZJrDqTM/hDwMdMELIZS4B/AISfXqVaXe9evX07PPPiP4npAgAGX2U+PoosQdmDsnKVJKcZRI88j5U0ppPtPSfznPb1NKOXYiXJaIKXJZFPQnGqJjpOAYnMhQ3oCjOREikSHnKkkDZ7yBB2AUGxdwSoPSiixmtqaRgmAeUBuUgkAXET5oZvlUHefoOkSrTCQ5G371tTO15oEunb36a4rk6tUKLjMPZPWGXOp/x2aa8co2+vmfHNqaRQLAwYMMOnmY8IlQN9pgmHbbwItuO3i7M5h3yjRu1Jjs9wJF7zOCQtG8gtBYpVMQ/aLqYiXOEUcc4TODL6Jdf/00evfdd11+x45+HVdQSKS4/bl0qbsiknDdiddMBPDwqFk8eV78VatXiRiPtXbu3EXwoASPL0InSFYY3pIl3krQo446Oq6JoUOHSiCmd+8+rk5x+X3fffd167jzrjsJL8l3GQ5St15dB0tetmzZctdYXr444IA2rl5hEbynCAFvvNzfvLvtoIMOooEDB1H0X1H8nKzzqkWLlu4j19HtO+WUU13WihWFC1wUx1iVrH13d66AyPLl3vmEx1ODijfbu1kQu0i8ovTp6IrNSr1ofhBt13v00Z2DVITXpUsXyZEsXuyNP6BDCD0QemD39kDQ3IqnYTwx45mYM/+CB8DT81tQGhTPE6N5Yk9pObGcnD+25mDIoACIqYaFniaq1xSnos45a4SBLnZCWdkyKpanA3p0ok7jzqSuN/enk28dSEeOPoNandmRau7nvV8ken/a9e5MHUedIbDfSQdFi126bS9Pr1V3bzJTY996UtbYQJ5eoZyUSy+XHiODHFCtifduFFG2kjp1vBvdZUuXUlbWdku6u6G6s5m9Ukp6oJBKAQdoHXcQYL5SikArpXPgKMQkssSAldH5iQcQ1KBxCviDlNlRCuCidSzhDRRnbEt4TPLGDFAaY4K4SgIHOQlG/MccqABcnmaDlMGOSXdjdQWBy8AAJ4X9XG6vsnSMUDECsEWlGc9d8z03T+8fI5RSpQWllHf6T852ylkV/+Ww0I8GrNZ68bMdNOCuzXTMxA0CwMGDzK+fNyV1cxughTahbcA1REi3XVN7Qmpe1IuARdDEFj647LLL5DG/Z555lvr27QtWQpCV5QU07dUCCRUugtK0adfT3XffQ5dddjkdcsghMZa2bPHeIbdzZ3aMvCiM4vQn2jVnzqtkVvsgCNW2bTuwfXDAAQfQhAkT6J577qG77rzLJ0uEQCDQPGrVu3fvwPdQde/eXc6Jxx9/gq66anwiZvPVef3112TVEBQPPLA9de4cO0EdPHgIIZhx3HHH0T77NIOqQHH5ffPmLWIfSYb1cnHQgKOOOopacuAFeDIBL1Vfv36dmDzwwAMJK8uEsJK+fc/PMzhtqSaE4hHfxx57jMyx79atG51wwgm+skXxc7LOK7wXrd+FF/raBaJ9+/Zkgtv42MFnzhf1IEsEsnP0WFCtWrVE1Aukk6x9L1CllvKff/7J96X8KxHz2rVvF7PK6fTTz6C27dqxNLlbUfo0WmIeQQRuB51B5wX+eg8MHEvQdw866GAxs3r1airo+SIFwyT0QOiBMuuBoHmVO3PRkz5n31gTNM/RHAZF+J+5hpRcaNeAi/AMjsVCKgcRgmASwEzewIOcUd7ABxCBZyASvqOLyshfnVaNqfP4c2nvLgdQ9aZ1CYGmtIw0qrFPfdrnuLbUYdip1Oiw/QP3Zs1fy6jmvvUFWpxyCJfXL7C1lRsf3pz2OrKl6NRg+8u+X+CKK9WtLnxjA7krTE2JkUEOSMvMcNWikVq1arks+0tQLrM0IElrAzpckDF0Uj9fKR3U4rCOCJTStFKeDWvcEJ3YBHYBkETIFHVzsOMBlCJaaGp0SGZaHKAA5nqbZqB9KIPc7IfkLAafMy4CzMsY82+O2GbqcmLJZceqaS0MqABXsZQjkR3rKGfDb24rlUqh1AYnuPTOBU9w0DPXpUsKiURyCXWb+tAmtM3QaDPabug9IZ816yVau1Z/IKBDhw50yy23UteuXalp06YcUDiFrrzyKjK/iOP9PXhXU6J++frr/3MnVx07dqQRI0ZQnz59OUCxT6ImCqWHCXtKSoq8TP3iiwcTgjXYn+OPP57GjBlDp51+utjFuxTnzUNQVsikJMXpT9PAuXPnClq+fHkONk0i7CMCeghwXXhhfxo9erSseMG7Z+yve0qhBJLvv/+e8JJmqOIxtttvn0nnnHsu4ct8nTp1oqFDL5XjCB+XK1eOknnNM/uWlpZOI0eOoiFDhsjKtc6du9C4cZfRSSedhGbJl/U+/fQzwZEUl9/trz/i/O3Lgd5mzZrJO7vg9xEjRlKa9eVItCUZsHnzZp546/2Dj0eNGk0DBgyg9u3by5dDx44dR+fyMUlGXbaNt99+i95443VhYb/6979IjrswOCmKn5N5Xp3c9WQJ5uK8aN26NZ1//gV0xRVXynnPzaRPPvmYCvpFyuXOKjoc3/Hjx8u4ERRghP2CQjL3vaB1G/2///5b0MzymTxuXE3Dhw8Xv11zzbU0cOBAQn8WhSQnhe3TaMbvv/+BTKBXr97czkHUq1cvofNLzOpL9J/hw0fQ4MGDCatQMVai72J8gQx25syZ4z7+DDqE0AOhB3Z/D/jmVXqSp3cac0dg7qSMEcgNHzKAQhIA0XzQAA6OEQlC+INJ5NFgNLSc65Zy0FKFC3RR+FeiHsiolEntzz+WyletIPVuXrGBFs79mea/O49W/6GXDqekplD7vscQAlaiZCVLvv6Lln23QHNYr03Po0mlmNOCqFzlTGrZvYOWc/rXO9/R+hvPk5IAABAASURBVH9WMqa33B3ZlLVpmw8i+mwShWiZ0Bu30s4t+tcwUYpKatT0viq3dKnehyiVPYDUx0D7UnEgA51T77Z2b8TlQUcpra9TrRecQgMAKXJtW9v0B4qgoTnQ0/VLyglvWhyTwl4M02XAEkAzgAGYcgw6GTN4YxH2jayBjJw/3nsHczLef1b3aSofxXrOTsbwWVTat+xl7/mamN74TKIUHSzO3fQXZS/3y33KxUSgTtQt5rkt0iYhdBLdZs3dvVNMqO+4YybhkWvsKYIZw4YNp7vuulsCGghsKIU+EqG33nqLvv76a6glBLBtvp6HINmJJ54kk5Qjj+yUUPnCKj399FO0dOlSKd6gQQOesPaR/Rk1ajQde+xxhIkehFhlgccZgScLsM/F5U/TxkcffYTmzp0rZGZmJp3OgbspU64hfBmwR48eZB5NWrVqFcEXoljAZObM22nBggVSCqvx+l3QT4KgV3Lg85RTTiHUCyGObzIf1X/ssUfpo48+gmkJVHbrdhphIo5VhV26dBEehO+99y5h1RNwQHH5HZPl+fPnowqqX78+9ezZi/D1RfgafocfVq707i9EMUnJo48+Sj/MmyfWUM+ZZ55FU6dOo/HjJ9AxxxxDKRzMncdBSVFIYnL//fe79eLLmgjmYcUnqiiqn5NxXplg+xFHdCScFzfddDOdd955VNn5IizO22eeeYYK+vfNN9/IPQr82rHjkTJudOWAWkHtxNNPxr7Hs50IHx9O2Llzp6jCVyed1FX8hkegEfRHnxIhJ86tB2NF3wrbp1Hzxx9/RBjHgOPR+u7du0uQvUWLlmDlCVid+NFHc0UHPwqcdtrpNHnyFJrCYyX6Lni4X/vss88IAVxRDJM9ygPhzu7ZHlBmzsX3uAQw7ogwAlCc8waUyCEo/p87z5MCRp8J3txYlSBahtQba0HBtmOFy2iOTiEBpCAJoXR7oEW3QyUYhVb+98NC+ujGF+jnlz6l3/73JX1x52v00wufQESKg1d7H9NG8OgEOts36EcKqjaqRfuecKCr0vrsjq59BLj+fOtbVwYEgbJ3rnqcbMjeph+x2bk1y8d3dcY/QRuWeC8Bhh0bKvBkw9BmgmXoPS1XSndKpfTkGPuvFHiKlFIgCSluMEBwX0aWGMiIECGlFEO8IsoRIIcuk4zyFqdMhBV4czLGeIO2ZuiUWbKBAjDBKrwx4t8UKT8DFLNUNF/2hWTIg4oGx7YmiHg/qYz+5XAgK+I8IohdUOVrU1rDk4EK7Jz/MEWydR8WRjEnqAt1mmrQFrTJ0Ggr2mzoRHJMDqBnzmXggNxc7zjm5uaAlTDY+pFIrq9cbq6mc5zcCCPmXHJyw080xwTvpptuIuTbt8c+do0x7fHHH6d7770nUZOuHt6J9dVXX9KWLd6xbtKkiStPpO05OdqH2H8zUYMB21c5zmNH4AOuuWYKYeJm1ws+ABOnZ599lvBOItCJQF51RZeHHwvrz0jUMY+2begZM6bT888/T0ut91oZWVZWFn311Vd03XXXyhcnDR85fIg8+hwCzwYEb6ZMmUwffPA+mUfobPn69evpzbfepCuuuJyizxlTR24hz8fp02+ml156kYJWimH14TPPPM3Bpjvs5gheFL+LgTjJxIkT6Ntvv3VXJxo1+BnBUqzWMbx452ckweNq7CCHXydw3e+//z7hq6jgGUDdb7/9Nr37nveDQUEew821xqidzhcejW3kt91+G5n3Ou211140ZMglYAsUxc9FOa+kck5+/PFHeuWVl2nr1q1MeRvouR9+SCNHjnAfgfWk+WNPPPE4vfzyy2TeQ4YSCK4gB9g+s8cDyAxkZ2cblOzH7sBMxr7DThAkcn598cUXdDsf12XLlklAz9jB/j733LP0559/GZYvt/c1kXp8hR2isH0afQDXkL/++sv9iAhMtmnrzQ1yneth0Jg2ffp0euGFFyj6fW0RHpvwuOJjjz1GN9xwPUz6INfqH/b++5RCIvRA6IEy7QEnpMQTMb5n5zHB2xmmlUcBdXU9dgDGmrwRwJ3dMcGb5qEICLbPqE4Zkc1QkDODM8NhijdNhYEudkVp36rvXVeaGMnOpZ9e/JRyd+pJjDA5wVca1y1cwRhRlQY1KT2znOB2smPzdvrpOR0QA3/fkw6iinWrUd0D9qKGh+wHFmXvyKYfnp5LEeuCJYJiTsx7Hoq5mtJn3jdI6OYppUgpHfDCjYXm8pjCiFKKU70p5eGaE5RyJ3f1eMhhElouC0QMOHZZlzfymgjKUxYbjqrmenKRaSanlpKjYnFYzpswHCGTsjHJLRZUEqbZMe4wKDwngchBy3QW2bmRdi5+1bcP6fsOIJVRRXiRbSso64dr+Zjo4I0wiymJ8CRT6uI6UQXagLYAN4C2os2GTiTv27cPdet2Kg0d6k0CUe7uu+8SPmR//vknWDHw4IMPujoIShiFTz75xOXji4GGj/y8884V2eTJV4N0YezYMcK/8MJ+Li8aufLKK0SnV6+e0SKhf/rpR/6le7Lsy5133klYTYJ3PCGQMXjwxRJ4EMUCJpioXHfddYS2T5s2lTBpufPOO1wribT9tttulbaffvppvgm/7aunnnrKtQkEk7nbb79dJr0zZ86kJ598ggN199K4ceOof/8LC7zSKa+6UF80FNaft912m+wrzh3sQ7Rdm8Y+DR4yWI7bww8/TICbbrqRcLyu4yCXeVTJLoPjANvR55CtY3BMgG+99VZ5Lxu+NvjIIw/TQw89SAgiDhw4gO6+6y6j6stNHfjKpU9gEX369Jb9jPfFRkxAUQfOF9T7wAMPEM7hCy44n/JarVNYv1tNi0Gxign+6tOnN8EPCLTdc8/dNGrUSJo583YJmMKnANvn9jkT3ZdNJQigoRzg/vvvM2xffhuf//DXTD6P4RfQl146VOr96KO54keUf/XV//nK5UXYYxRWQEXrIggwaNBA1zYCq7ZOUfxc2PPKrv+hhx6SsQqBDPgW5+S5555DM26ZYasVGMe5dv75femqq64i2J4yZYprw/ZZvHH9nXfedn02e/Zst6xBkrHvxpadjxgxQuodMOAimx2Df/TRR3TxxYNozJjRhKAXxnfs73PPPSePrOI8AiDQbAon6zzGuVuYPo0g1+jRo2TcRv9DX3yRg1emfWa8Ad/w7BwBTPhl6tTr6KGHH5LrAK7ZuF7OmvWSreriiRzreNdw10iIhB4IPVA2PICJHiBOazEvU0omd3E0NFs0oKxJJ2UGbw7BGQjRZJwwFSTvDzKA5vir1GXCQJf2TalNlVJUobb+OuHWtZtp+3rvV3670ev/XS0kVnXV3L+B4NHJfz8ton8//03YaRlp1LbHkYTVXMLg5K/Xv6aNy9YyFm4l4gE+tqaeiBNRQg5QSndQI0cOPnKAjYOOAbFn29A4UhHFFnA4zoABReY4mQ8jUhxs4eCbo0ry52nCfiQgJGXUTS7FkMQwmOmZY4I30DDMqLuBZj9BBBA+eIwE1c/sUr9lL3qeIjnb3HamcJAro+Uol85Z/RXt/DN4cucqJQFBHajLmEIb0BZDo41oq6H35ByrDt5++y15lAPv6sGjafn6I0EFrCj4/PPPfcGqBIsWWg2rgt599x1Z/YQXFP/+u75mFNpgAQsWpz9NU7DC5uWXZxMAk1IEKYwsWfncuR8SJu6vvPKKPL6KAGaybOdlB+cL6kUQx7w3LC99IysOv2Of4QcE2t544w1avHixqa5EcpzHCEBghRfO6xKpNJ9Kiupn+BPHtzDnFc7zjzjQ98ILz8s5mU9TCyRGIA+2lxbjqyiKsu8F2pkAZQSP3nvvPUrm+B5QTSCrsH0aqxrhMwSHAw3nw8TXRV95+WXCdaCk+24+TQvFoQdCD+wCDyie/0m1zlwLuMsD4YBycjtTKBs138NcLYrFRXiOyal/01oKTKAA2GNQDGADpFmSgNIQBrq0H0ptml6xPCEohQYiuNHkyJYUBOUql4eKgHmXlxBRyS+zv6CtqzcKt1bLxlTRCaKt+WsZzX//B+GHScl5AMcUtSmlkAko5eFgKKWkGyulQApYqNAxiaNg7EOO0jI2gGAAzZmz+SmHKeGqWEmEHPNGjfMIg9aETJFiGhv4yInA9yjiP9ZxGYyTImbG39gAtHwKPKDBBMDmK1I2WWbwSNYa2jH/cV970+odS2mNT3d5Oxe9QDv+uIeDjclf2RWJ5Ipt1GEqRN1og6GRo41oK/AQQg+EHgg9EHog9EDogdADoQdCD4Qe2H09gMBU9N5pnjfnMliE52e2rtazORo3+prSqccDZoBkTupN7zDzs6wyydNEIkmI/5jBaRjoYieUgU2aWKluVWrXq3MgNDhoH9HJL8nevoN+eOZjn5o8svjMRz5eSJSMB5RCB0ZdukMqxbQMDppGt8ZgYShoAkQFSD6gFNsTHW1BKUPDsgicRMuJPDk5f1qiU4fFQRYiyxQRWeVYlTfSfxafGf4yrAUxQIYvpllHNgu1aR/bMSbFRclLrKHPY5YRLPufWZSz6S9fazNajqDU2h1cHgJRWd9dSXiPlsssIgJbsAnbxhTqRN2GRo62oY3AQwg9EHog9EDogdADoQdCD4QeCD0QeiDpHihVBpWZ6znzLzROIQE4EzQnI6VcCaSk+F8QNwFHuZSNGBt6pupRogPSLeYiIpKppE6Y1rIw0MWuKCsbAh47s3ZSfpCbk/dKj/LVKvh2OTUlhdIzM6gk/3KclyWjzqpV9KOZwMs2oPclugdaF8fULiG0DA66g9oBLZHZynni2r4eJNiWQ+Zvw1GMsc02LJ400aJ1PU5ZUY04Q1rEp6XHH4sHFODXIqcwuX+waTvDFeiahYySqxgjolX6k8hO2jHvGsrN3uq2Vak0KtfuGl+wK2f1/9G2zy+incve4cBjrqtbUCQSyRUbsAWbpjyCXKgTdRse2oS2EbfR8MI89EDogdADoQdCD4QeCD1Qch4Iawo9EHqgpD0Q0ZM4X7WYwglf2WwmouZkogMVFEDOtlxUaC/h0tbkDnxLU4Tg2eDIIRMUiJaHgS7thzKRrl3wH7019uF84d/Pfou7P5k1KvveywVFlZZC7fp0oZS0VJAlAus3bHDraWx9UcxllknE61j5N1/regEjQysOWkgvFRNKKVJKCV6wRJexxxnPapAlrU+E+sn9AxfgMhwEdgEOyZmlxRUp2GGub2O+ppXOrFSxvku6ei7HRZSLMcINgCp4AIKfACxSxPvBgyijZXLL3bqEdvw0jc8FL4ClUstRuQOn+R5jxAvqd/x0PW3/8mLKXvkpRXJ3JLy/0EUZlIUN2DKF8bgi6kKdhoeAGNqEthlemIceCD0QeiD0QCnygNOU+fPny9fz8AW9b7752uGGWeiB0AOhB0IPhB4oogd4/kUANqMUZlyM+DY3rOXjCqEkdRKexflozWYu8TSOSCfk+4MQ4DB1cU55kyZxe3SUTCuFgS7HUaU1w6OG5KzD+egXAAAQAElEQVTQSq9QrsjNbNe7M2VU1O/zWvrNfNqweKXYrNKwJrU47XDBSyJZu2aNW02DBg1dfI9DdD+U3Y5wDwUoxUEaxpXiXssS8DgjpTQNHBBFghUDSjllTM4aFsqUvaExEa6HeREGZ7NQh6NEx2/H0UKm9BCjlZkgAx5HY07KYt+QyDRiVErKOTrI/BUSMa1I/6FawdhvyH32wCiDkLPyM9rx662+liuVSuVajaFy7a4mlVGFzF/uxvmU9f1E2vrBaZQ172raufQ1ylk7j3I4YIYXxwOAgwcZdLZCl8ugrLEDm7CNOlCX4SNHW9Am4CGEHihrHgjbG3pgT/IAXgqPr+cBdsUL1PckX4f7Gnog9EDogT3BA4qU3k2efxGAKTNHNYEvZmEKR4r/gftA+SjWYAYmcABXFGG+ISIOwnqMSYoEwDQ2o4Hpn2YbjqbCQBe8VIohNzuHtqzdJC2sUKsKpZUPfsSw2l51qE7rJgIpqcGHde8ubah2i0Zia8fm7fTry5/Tz7M+p0iuPimaHdOGau5XwKAT16WUPpnEcILJqlWrXM26deq4+J6BcBgGPRI7a/lOKUW8gcu5IgweAGFwYuNMshxpPNDHFFKUAwCHfVM1aD8oh+ScNxCeFVAMhmFyZnkbF+JNRjiPyRiUGSBj4L1nnrMxDX1FymE4GZM+PbC54WwFmA+CeD6FMkxkL3mNsn65hY+1t7ILu4OXw5c/8im9uivFGhNysih7xce04+cZtP3rUbT9k7609b2TBYCDBxl0iHWJCOaI2AZWcYnNesdqnpNGIrnSBrTFYYVZ6IHQA6EHQg+EHgg9EHog9EDogdADe5oHeD7m22VMLgE2UzFhTdAUz/MiKGfxBFWsB+CMWAcAPlTJ/QPHJSxE81G1a0KzHJ0IBUdEHHGYlQ4PbFq+ThqSlpFGrc70XkgtTE5qNKtHnUafQYdfcopA5fo1mOvfKtWrTi1PO8xl/vryF7R9w1ZaO/8/WvTxL8JXKYra9ekcN5gmSk6StWm7YOnl0qnOAU0EL0iyYMF8ys3NlSKNGjemtm3bCV56kuJsiSKllFuBdHyHsju2UsrVU0o5GolmRj/CNkgDEQdMOInZIlEcTcNCTLVgcmQKGmirkFIaGLhMMOqVc3jMxoYyRKxA3h8CWn4tLVOsB9AUUoVEAwrAmFeR5jup4rIOWuaz7CVzKGveJN87u7BTKRlVZHVX5tHPUPrevSmlfG2wCwQog7KwgVVcsGkbwDu5UDfaYPNDPPRA6IHQA6EHQg+EHgg9EHog9EDogT3DA5ivRe+pAgPzMczLGAcNkAmnIMzkDWWVYgZvTDqbU8iheJYqmKi5ekAAWoqqeBrKeuABmG/MgERhlupNFSLQReFfSXvgzze/oUi2DgrtdWQrOmLEadT06Na011GtqP35x9ChF59Eynm/1rqFK2jDktW+JiKA1b5vF0rloBQE//38Dy3+6g+gAr+9+iVtWaXfmVWxVhVqfdYRws8r2bDEW5F12MCT6IhLu9HB/Y/3gXlEMsgOAl2//KIDbKmpqdS7T1+qULFikOpuz1MKPdPbTQS+DBguaOC2qo1DFh9gX8m4EFwGcq80BhEBsMzgIaXB0LqwA3DFEDkgZX0ClOH6mYcyjpqbKTcopTSP9bC/GBQBwoRRRpRydJAxDj1muxaIeaDdciB2A8Ajg1lfXBzzNUbsWkq5WpSx/8VU/ujnqVyHeyh9v0GUVvdoSqm0N6lyXtAbOHiQQQe6KIOyKWwDtmzA1xWlzpWf2ewQDz0QeiD0QOiB0AOhB0IPhB7YkzwQ7use7QFFytt/zLWceRkZviPmKRwF/SnoxQgVR6mitVmJN4+rCVQJnuRcTBeMwCrYBEQ3KUL2X4pNhHjp9MCGxavpDwS79BGkWvs3pDbnHkVtzzuaGh/enDIqZUrDszZupR+f+1hwO9mv68FUvWldYe3cmkU/P/+J4CbJ2ZFNPzHPBA2adGxJ9do0NeLA/Pc5/0c7tzkvvk5NoVotG1GDg/f1QWpGWmBZw3z9tTnuqq46depQn959jWiPyo3fsdNKKVIKAIq7sXPMmSUMkDYuzDwS6EOMOlDO0OAFA+oGaKk3XCjNkICXwR2WZJYmi3kjwP+zdx0AdhVV+zvb+6ZX0ggE2AVBFAs2rChiL78CFlBUQFTsgogVAQV77wULYK8oCooKKl16J4FASEiyqbub7L7/+6bce9/bt8kmZDcJmZs5M+d858yZuV/uvdmZve/FuVyfEjS+Uz2Y1aVMCwo7GiwYoXGdPR9FjzHOGOJzsA4naA43eh45RV8C33vZ8ei75avQd25VnplZDeo6u9Cw+5FoPOCjaH7Sd9ByyM/ReuglTqQLk08xilUfVBzKrTE0lsascCczMZAYSAwkBhIDiYHEQGIgMZAY2EUYKHEBZ7D8bOO6jLgDuQRzrassos5Spf5qy6WsE13KH/pmLmFa/wFhSPhDuGJDIBvv9zh7uLC00eVoGPNqiwe87cKrcPkXf4tVi5dDmxbFBBu5UXXPP27EP87+JVbdl3/Ju2JaJ3diwXMOlOrkpt/8G+tXrHF6sVp6871Y+K+bMmjf/3sKLyhdLBlUpqxbtgp//9TPcP81d2H9yrVlvmgMbhyIatX21ltvwRVXXJH5nnjwwXj/B07F/vsfkGG7gmLGG5UbNPp7lfAvmKdtGf90e4ioCkPVjEjMLItTv4KZ4V7hE8I9lmILjo9hDj6uGKZ8eUD5OHQHV4679M6U1ykuxs9JmMRBAN1mrFB+CMmi3AQyi4H0hj6cIe1HYCltwMa7f4L1lx6FDfeczw0v/xHibXGmpYFel1O5NQY41rbIm3IkBhIDiYHEQGIgMZAYSAwkBnZxBnbq08/WVm795U+FK68KJZqZxwGmhZ3T8kqYW8W5SrhXwlJOAMVjVNxa2A3tIFcRNgoLG+dzi03aYby00SUuxlAGNwzgN2/9qpOLP/bjLRp52S334W+nn4cL3/sd/POzv8R/vvoHXPKJnzpbb3Kte2jVkHz6SOJv3/F1N57GvefSG4fEROC6H/89i7vogz/gBRUvohhR3q57sAdXfPNCKFa5K6Vv9fryDlWsb3z9a7j88sszz4IFe+Btb38H3vvekzPskavk/JoZzMydqlBteEkE+BtX2paIssT4Up67FLHKVmNLiCuGsqlxNVUJo0NhB6cZx3JK9qjxlvnGhUl3SoYZ/B8PsKY7nj+tUAgGzTVuAtwkdMbQKnsgD3Xt9Eip7yH03/wlrP/7K9F30+cx0DP8fb25k1Vf5VAu5VTuzfVJ/sRAYiAxkBhIDCQGEgPbhoGUJTGQGNhpGHDrLz/bipWZB+MKsOCstiYT5lJZ6OYadvLFWb4i4BXk8WWdnNchLtRVDksbXY6GnavSRwb1JfJLrr8H+qL6zb05tSOf3cDARnz9a1/BhRdemG2smRn23mevHXna22hu7pYMufxNaWa8ic1hZpbrDskrM8uNqlrRX9SrBhP04wOMZUE4NjlM7OJiQyftjhEPlvNUr8oj9LCTFGONc5HkmOWqNI6jV1PLUI1Pnw3pS/ARWEr9q7Bx4c/Re/nxWHfxS9B73Uex4Z4LsHHp5Rhcdx8GuSEWT1u6MPkUo1jXh32VQ7libGoTA4mBxEBiYAdgIE0hMZAYSAwkBhID25mBsnWV1loSzskorgTb6bHKnBGobBlQIiZhUyz5+pMxXNMVfV4v75QNn3d0YWmjy9GQqu3NwE9/8iOcdeYn8a9//hNr1qzb3tMZ8/HjDRrfYjKzbOPPTUb3uVN8FeO8NXzt4lxy/0CoSFOlo48Dx3fOYDq9UClluStYGoASLPaIWmwJVRbGeyhTAKra+JKgcJRnkcXAgh9h3pX9iiGPVL3UvwID9/8V/Td/EX1XvR/rLz0S6y95GdZeeIgT6cLkU4xi1eeRykc6r0c2A+nsEgOJgcRAYiAxkBhIDCQGRp8Brask2UjZeisgwQ4WXKyWaQEwGFRQOIgwjoAUNirGoKxbpsgTRJiEcR5xBtzwJsTbehFCkja6xEmSHYKBW265Bd/85tfxnnefhG9/65s7xJxGbxLlN6KZuzt5o/oNLrdBVRhcG0sFk3FFq1KPucE45mWhBh25R1ZRXBABjc/GP3qkVBVNVyJn7AlQ4wDlcyWG/KA7GEFTQzH1LY5JLAQWmpKLygA3gRJNo4RSGNw9ZAO8CzXpVBMDiYHEQGIgMZAYSAwkBhIDiYHEwLZnwK2/kK/JZGv9pSUZ/GG51wHZmqwQI0xdXUCo5Lag+xRCJAGUU1JYM8p0wxfC4Dob0kYX0rGjMdDX14t//OPSbTytHS2dbkvNSa02l8ruTjncLaoNL0U4gJWZt3RD0xym+BjvVF7ZagEz6ahyeL8cxYgclUcSvHJICIWGGgvdLFQA38rrNfCoOjzdetjRvflSTMDULOzjaypA8Bv8H6QjMZAYSAwkBhIDiYHEQGIgMZAYSAwkBraKAa2qso5ahFKy1ZcUrb8sRkghqCZAZjQIcXkWEFDV+hd68YpVRVFsAVJ3Z1bgYBZBmR86OJYaSg1YpZIYSAyMHQPavKoczSy/KeUzo80i3d/A3qjWVzHDC/vpYcQkZl6vHktfmaPSDk7mCprbSy+P4iByBtBbMrzGZ1F4mMkWzmA1Mp2TdizCo561eiC64ICUYFYRGOanjTNJCExNYiAxkBhIDCQGEgOJgcRAYiAxIAaSJAa2gIEha6qy9VcprO98QhcrP2GPsKbucKqxyHarOFd5tKB6AEL8+k9aANmUW1qU5ggHY4Qmld7ockSkKjEwdgyY5beiHzW/IbWRJa9a7dmYmbvFfZyvCXlls7XyUtiBxX3nF61N9KLXDaoQ6mzUj01eTCorX/RcEUAhwDqW3FKeYEl1AbIzI0OcEqvgtrKz96DFGPk038xOSmIgMZAYSAwkBhIDiYGtZyD1TAwkBhIDiYGhDJjWXUPh6ojWZ5a73KbWkEUl/Yrxyzsa2ppyDcqHUgADWXJcGMoP+csQSx9dRDoSA9uZAT0L/BQM7hnAyswc5Da8qKll40oe78xNVMoh4eOFz4OQsko8nQ5lLItTQ1V9LJ8PFbGhi2uU0btVyyIslU1lCV7ChYCgciTiLC7Ig04lFMfPbGEFsRhQwJKaGEgMJAYSA1vFQOqUGEgMJAYSA4mBxMAuykC2Jqu2oLScFNP6q1rM8Au2vHPUslgp5lGpEm+V1wrJfDK8O73R5XlIdWJguzFg5l/JdBMIN6k2tsxMjwoHU4WZOT1WZuV2xIut8gCbi5M/DAx/VN/goi+EDTe068cYZWQ0C43NjK9c/uGpWHZRoWrFfkZQwqZYGFaMKrxhVoxKemJgNBlIuRMDiYHEQGIgMZAYSAwkBhIDuwgDbsGHfA0WbITDrz+DMUxj7O26aTGXxQTDCDhVCnWW3Mwxwq4oj/M7S5W30kaXuEiSGNhODPgHQQna7NEUSqqKS5MoCAAAEABJREFUEhy6gYuwdN9X2nBSYt7iw8Bgw4WWefKoMHzeK7g0H0nu8JqLjzEOCobTq1QlYhI21YqVzQvlFicgf7G7mUGHMdJvnslKkhhIDCQGEgOJgcRAYiAxkBhIDCQGEgNbyoDWVVkfrr8Q1lsZVrC1/iqLZ5CzjUqh+DgCGZ4pBFmcma/yclOYLLWMY9HwQgDWmp9aIH10kRyMeUkD7soM5DelWDAzNlGoulKCmTC479VyEKvNb2wxqKz4HBFS/1I0NtmWOL4PcM8Kr7IuUXzR9MqzexwgyjAW5Eew2LDksDSG+yYoMiTB1ENQpkTzV5tLCMqBTCv2y8CkJAYSA4mBxEBiIDGQGEgMJAYSA4mBMWbgkTjckHVdPMmKJZpblw0JZhBL7MJVL1UPDLf+1DKTQaH4WG9EnYNElY70RhdJSCUxMHYM6O7jTRgHLNzJ2sgx08cYeasH3EzxMXgrW+aKacw2lU/zol+NpOpw9AsP/mAJ8cKxpAw3jMfVudCTqhD1y2QIED0MLqoFk7uCIs55rfxJ6LBUJQYSA4mBxEBiIDGQGEgM7FAMpMkkBhIDOzsDcf0Xz0PrOEmwtS5zm13BVmOqFCOR7sQbfr3oAFe5WKdVr7SG9p7yyLTR5VlJdWJgDBko3IS6k+PDQXqYhZk2vHizZz7ArNAPIzzU3/Uz9mcf2sameil4CmoeK5BzIuBqmdTzQoAFFA6jhi5FEqDmAJoWFWESYtyhkpaLCXGODDMjJ5v6Fi76Y7AepubGiUhqEwOJgcRAYiAxsDMxkOaaGEgMJAYSA4mB7c+A1lXVZmECtf6SUNfKzbj+cvFGoFDMygEXI38ZrLWewChy5pjWl9GjlaJ0H0FNilsnStFMkD66SFpSSQyMHQPld6gf13xTWbvngat4K/N+zXerKyOHt9nNOdVXQ8uWOHCYyvv9pMLwhchy3MfKHTQ1EkGZ5IA0SebaEoUdjQ/Psi46qTIgGYmBxMAjnoF0gomBxEBiIDGQGEgMJAYSA2PCwHDrLy7N/PibWY9lm1o+mqs5C1p5I1SSo34EYdLydamzsjBZ1aaQ3ujKKNo6ZeLkKZBsXe/Ua5djIL9DC6eu21ebWbpNc7jaDStv1RRyDJESzHzuoqsKFNwlthI2bkdcc5IeRT4Jc7KpOj+6FK0xGEJVgIQqizQJ1bw4wFUe8x29Xqj1kJRkkW4CBivEQAPTNmj3f5hE9D9SSzqvxEBiIDGQGEgMJAYSA4mBxEBiIDGwrRjw6y/L04X1VgYUbBdbsLOYguJiuFZzUGG5VlCdy1eKBspT5nNRH/k8wjqsD8EjbXSRhFQe8QzsUCeot6vihLyuWxS8gXlzAr51Nymyw8w8TqTCRWS4YnQod4l9AVlM477KClUPFwHFRLeQqAPRyh84HikBzqeWm2OgeFVaEDYq7BB6y2IgG8YSphKKDGLByhozOXwXB8omVBYayPFjuKhUJQYSA4mBxEBiIDGQGEgMJAYSA4mBxMBWMlBtbcVlGBdmXImF9ZdSC/PrW1lejOvESszlM/ol9FNzhdlc6ys5JUOGoTuP1PDeYu3C2QLpo4tkKZXEwCgz4G+2OIiZuwOdaSZd4mOyhwBxM+OmVAlmvo0+mq7vyCr1VSRbNnoQsBm+VASUGKnZsWGRxQbGP2xpslAxiteoQPOLAsgHHmwVIskwD8t0DzuaWWG4yZEBesC5zuUo52uFmOg0KpKiK+mJgcRAYiAxkBhIDCQGEgOJgV2bgXT2iYEtZ6DausqvzJhLCz82vjBSNtdo3uYaDiW3Mou2WkbJIZVSovhiapwpTYoEUEoJ3CFMfmcUfMKilNJGl6cn1YmB0WRAN1y1/LpJy3EzxroHg/eZcYOKthnxEEozaMM16ivx/tg1az1cvVZQ6BpHDCbjC4hUCdG8eEDzi5I/wZiFbtZgwy7S2AxXqrh9vzyjug4N81HaOJMoJkliIDGQGEgMJAYSA4mBzTKQAhIDiYHEQGKgKgNl6yot9GKU1o7Ss0UZFfkjLp/EL9GkbVoUJ+HmGMKqETyUks2Q4kKJej/Hdv0IsG/66KJ4SJIY2C4M+FvTv6nlN7Q0Dd2iarWl433UePea+Xhf+4jqtSIk0etzM4UD8vzOZBUR37qaFQt91YryVcM9ppElQ6yQMDTezdqfY96DkCtlD1QhPH9FSWRKjA8xtZmEkxyCZwFJSQwkBhIDiYEtZSDFJwYSA4mBxEBiIDGw6zKQra24HoMkUqGFncQ8IBUIBoY/snWe6xDjabBke1VO8T4NGZZ5TOoxrpBdhCqP+JoBrqSNLkdDqhID248BM39TmqktwUytFzO1gGq/IaRbGltwlBhbgplRqFYtFlC1iqVJlWWYPiUGsISGGouiPeBqmUT9bB0CEGNB5WFyDAWJWjkanm4hW/CVW+B5BkdqEgNjwUAaIzGQGEgMJAYSA4mBxEBiIDHwiGYg35ji2iusyfwJ0y4s2aRmsT5gmJqRLJBop8pF0WDxmAAZzE+1bMhiPH2K91EyJN5KG13iIkliYHswUH7HhhnohpbKR0TBr9vVLPoAs1zHJo8Yp3w+cNNdQzwHZEFhCr5zqF2OEOohRXvN+eB1oBAUQgoI3OGA4HQAK5qcMZVQaIOJ1QQka6phmTMpiYHEQGIgMZAYSAwkBhIDiYHEQGIgMfDwGeB6TGuy4RJpXWbmFnfDhTjcRSjYWbEiwBIt/8KEi3RQeVoFSpyrYkq+T9ro8tyMXZ1GSgxEBgp3a/a2Vraz5G/QGKo2xlTqsodIlid6fD7VQ1wxxLXhgaFA2qGhViz+o4vlefJI4ZJiD+khc7YHL8xJdDgjVHk6D8iuTCqbHMolcYHCqJRtktFOJTGQGEgMJAYSA4mBxEBiIDGQGEgMjDkDj4ABDebPIqy1ZFjEZASx0BYbU1zFek9rtQqIXbjGZF1efBSXfH7fy5nGEGNWY+uLm5arvK06bXSJhSSJge3EQNy8Mstv1MqpmBlvZMDMEI+CGqHyNgYUbnj1ds+GECk7qMM2ih8aV+JcKruUCPhIDS0hwCKcDYuw3CIAHy8NTi/aGHowwZAInp9ySoodzOUrIklPDCQGEgOJgcRAYiAxkBjYkRhIc0kMJAZ2Dga0MVU5U49ZBkctrm+jw8dFK29jfI6gsIKTNwr3uLTYkwkdMgpZaXKZCLgKPAiwThtdJCGVxMD2YsAs3rH+hjSLdpwRb+KwmRMRtYTUbF6yfEPze6QyReX4fLBUhtDW+Flq2kChHxPLD3cUcNrlfRhIzHeVLhFAKai0skmUwSFZ+QguGmTNK6lODCQGEgOJgcTAzsdAmnFiIDGQGEgMJAZ2GAbML9iAsP4CD6O4EhZooWFI5nFug7k2r4yI5WZBizn84i+3XLRMp6hDpsjw4VwBesP70kaXZyPViYFtwIDuvpGm8bFDdrzzHSKXqGhWxrqAYSuf37t5swdz8zlCoO84bF14xoUY9ZPQ5HCs+QBTHTCpEme6SpZ/KBVMD7IOOaj5IrtIhkddnXWv8FuYgQtKVWIgMfAIYSCdRmIgMZAYSAwkBhIDiYHEwFgyUO0lAq3BHG7FmdCoWJO5GIWog1puSGWqs/OKvf36MIMKkc6ZOYIS/PI5VYp3pY0uz0OqEwPbgAFDfUfnCPP4mzDfMIq2obgZZWYwsxHm9GE1DQ2obW7zBh8kQSloEanWavwc18iSHPGanl8Sb6kuRPEhoymzkSOXDCjEBtVgVeJyKGqFKD4E/WNTmAQaVMJgA89jhGfM8EdGSWeRGEgMJAYSA4mBxEBiIDGQGEgMJAZGiwEtACXMb6YVF5Wy4tdnZVA0LCpquTAss4VxeafG4a6SlQu7FJd3PoI1i5sS5+MzKBBIG105dUl7hDIwFqc16QlPxaM/8x0c+NnvYd8PfRp1be0jG9bfhy42bnCZGe0SzNTydnV3LjIb4QjuYPlm9suOwqPP/hYOOOebmHfMCQR9Dnam7ku1ft5TYlPyoSWqoRTUgJiLKc8TotQYw9SyAWREgTtkOSVWBMoeibT1EDPXNwaxLR8QoG3wRzZc4Kosnw9JdWIgMZAY2CUZaGhoxKRJUzBr9lzM230PzN9jQZJdmANdA7oWdE3o2tjeN0VdXR3a2zvdNTp16nRMmzYjSeJgs9eArhVdw7p2dA1t7+u4dsqT0PTEb6Dl2X9G66GXJEkcPOxrQNeSrildW9v7+tb4BlMDcP3lBPkaFWH9RUhLOBj/SC8TK7MYQUALOEnmKhGPRikojAuacxbMGKHhPRwRg7rUqEqSGEgMlDOw+xvfjv0+9nns95HPoHHilHJnFWvaoS9i3GTU1Naiff5emHTwM6pERYjbMLojZephoZZiZpj0pGdgzxPeh25ulnV/+DPoPu0c7PvhcziPz2L681/KqLzEFBHR5tqUZ78Adc0tqK2tw6QnHIKWWXP57MnH4xC0Y4/K1j8ioKdIUOPjAvGIQGwj7lp2YtETrtwtiyIfhbNx0VnlXHRkABWaQ+OGIAzkQ9bVqUoMJAYSA4mBIgNmhkmTp3KDaw46x41DQ0MDamrSj31FjnZFXdeAroVOXhOzZs9x14gZ/9EdczIMHR2d0GZFa2srtFlhtj3mMeYnngbcBgyYmbtmdO3oGtK1BP38ijE+aprQdPC30fToT6C2Y09YTf0YT2CLh0sddhIGdC3pmtK1pWsMvNZ2iKlXLkCNz21JcXKEtB6MkPHeLKkf13wRc6rRkrABYyTCFYrsEEIji6Puisc1dObykPOqSj/xiIUkiYEKBlr427TWObujdd6eqOMPYhXuIebGNauBwUGHl3jHlQY2OL16ZTCzzOVufFp7nvB+7MENtokHPQntu++F9rm7o233PdHGebRRbxg/kVHDl8G+XgyuWwcmh3GjC3zCDG7sl+kFRCoeAIRYKkFva4amihFZcbbfcNJDyJnOKc33A9W8X8BcTByfAcFWo2zlUULBNOYE2WGZxlPzyfKBch81Y082qSQGEgOJgV2SATPD9Bm7obPTf5x+YGAAy5c/hEWL7sFdd96OO26/NckuyIH+7nUN6FrQNaGbQ9eIrhUzkzkmYmaYMGECWlpa3XiD/PlpDX+OWrZsKZYsuR8PPLB4O0gac2fhXdeIrhVdM7p2dBHpWtI1ZTZ21zF/s4zmQ85HbfvumkKSxMCoMaBrTNearrlRG2QzibVeqwxxd5sWhGEhJ1vi3qpwiu+hvmYEWDyiOnSS6sTbLiyLkyJhAN0ayq0B3TrP4w6j20MekylJG11iIUli4GEycO8vf4yHrrwMa+65A/df+As8+Lc/jTijmbk3uSYedLDrU+IPfAP9/eh7aBk2PLQU/Vyc9C5dgoG1a8FQF6OqqMse3LABC8/7NnpuvA6rb7keC3/6PfTev5gu3fT6ziqU9Ud2yJ8Z7tmkhwafJ9xMirizaPhYjS2JKB1ZcX3LHOrD8YmpTxYYFINlmlMYp80/PRQlHnAfeNgAABAASURBVCNIxSzEqqGuOMJZBhCTnfWTkSQxkBhIDOxiDEycNAXNzc3urNeuWYOF99yFFfy3pL+vj7+T8b+Ucc6RVCnmEcOANgV0Deha0DWha0Mnp2tF14z0sZD29g40NDS6oXp7e7GUP+No02Ljxg38GcT/e++cqUoMVGFAP/vpWtE1o2tH15DCdE3p2pI+FtL0uC+hpr59LIZKYyQG3LWma257UGGwfFittbTYc0jAQzPc09vUf4jTCutMl4wVg1iohOINNyQRtUrlO5a8SlyKn1JJViZpoyujIimJga1nYM0dt+C2L3wS//vQO3DPud9CaeNGjPTQP9gde+/nwq2mBiuvuwJXv+toXPXOY3DlSWzf9QZc855jsejn5/IHQMDd5OAtXn4vEwGWXX4pbj77w7jxrFOx5C+/I+aDNIb6+YcA4WGLMb/EB/je0k0VRUjUaWZFuDc0jiIkHpGvxLy0SpSKMgRiR4OVRykpEXcebGMxxhkNn4N1OEFzuNGTSmJg9BhImRMDOyIDWuzpLR3NTRsZektDGxyykyQGIgO6JnRt6BoRpmtG14700RR9RFFv32gMbVCsXLmcP9vw328BSRIDW8iAfi7UNaRrSV11bekakz6aou9N0ls2ozlGyp0YqGRA15yuvUp8tG29QGBcW2XjxHWZf72Ki9LMQ8UiSt0X9fdasa587hudoW/mEsb0tMOQjFERrlg6ZLLxfo+zh1CkjS5HQ6oSA9uPATODvl9Lb3JJHvzHX7Fx9WqY6WYFW96uvIERjrCXE6zNNT6HotQvpJRZIRqgKHDjourBxxVDlS93l41TeMDluAOdyc5wiuvu5yRM4iDIbZbHIBxCsig3gcxiBL2hD2dIe+cqNdzkbG1tg36rPn36TMyeMw9z583PvjRaujD5FKNY9dm5zjLNNjGQGBhtBvx31QD6aNqDDz4w2sOl/Ds5A7pGdK3oNOK1I320pLm51aXWRltPzwqnpyox8HAZ0LWka0p54jUmfbSkfv7rRyt1ypsY2CQD2+vay9ZWbv3lp8iVV4USzczjANPCzml5Jcyt4lwl3CthKSeA4jEq/IVIWA87yFWEjcLCxk+rHE8bXeRm7MquO1LL7HnoPvVT0JesT3nqs7HgxJNx0DcuwP5nfAUzDn+ZI2bOkW/Eoz/zbTzumz/Dvh88Ey27zXF4tcq4KTDjBa/APu/9GA749Ddx0NfOc7n2eueHMOngp1frMgSb+ISncZyz8JgvnYvHffdXeMxnv4vd3/B26Mvn9RuiIR0KwO5Hv9Wdi85H59XFc5NEuya8kl/oUkWNNyNdPJ+a2loqwGDveuhujnPwN65zDam63n86uk85A10f+CS6TqaQN7X7vP8TmPeGt4b4Esz4BKA1XC6rqcX0578Me7/rw9j/k1/Goz/3A3SffCbmvOZNmFyFT6WTMCVa587Hnid+gHIypj37hWieMRPzXvtmdJ16FnN9Cd2c2/w3vxvt++zH81IPzaUkxQtVg//jAdbE4vnTCoVg0FzjJmBu/8zZFVVpWE9F4HY0zQxt7R3Q96Pof8KaNn0Gxo0bh5bWVtTX16M2XBOaonRh8ilGseqjvsphZgpLkhhIDOziDDS3tDgGenpWpo8pOiZStSkGtDmga0Ux8dqRPlrS2NjoUq9bt5Y/6lT8u+48qUoMbDkD+plR15R6xmtM+mhJTdvwa5TRGjPl3VkZ2Lbz3u7XXmG9Uf0JHtDQ6OyrrcmEuVRlyxd28kXdghCgprA8XhbBQnGIC3WV89S4OlWJgVFmoGnyNLTvuQ/a99gbu73sKEw46GDUNjahecYszHrF6zHvdW/B9ENf7DaZtEnUtqAbC7hpVcPFfuXUtAG270c+i9mveB069300mqZMQ21zi8s1/oDHYY+3vIsbNqehrqWtsmtmzzniDdjjuHejbUEX6ts7UVNTi/oJkzDlac/G3u/5CKyuPot1N1VmeaWZm3Bt8/dC++4LoPPq4Ll18tza9eXxbFGtk+9aqC3XuQOlt7lK3PByKCszYxpzMb52qqvMPNI6bw+07+F51f/22DZnD7RxTh2cQ+tu81ws4GMxzNE0fTdulJ2Omc9/OXPtjfqO8aiprUXTjN0w5YlPx+xXHwNtQg7pHp4jjZOmoH3uHmifMx8ts+Zi/hvfgXH7PQYN5FUbaPWd49HOec498k2Y8oznhTTlc9LDThKcrjHOW+IMV5mrs8qNX2IU3HxreQ3UNjU7txGVOGMHrMwMnePGY87c3TF16jS0cGGqH9LWr1/vvjD6gfsXY9HCu3H3XXcifmm0dGHy6YuEFas+6qscyqWcZrYDnnGaUmIgMTBWDNTV1bmh1q5d49pUJQY2x0C8VuK1s7n4h+Ov5c8X6h8/aiY9yS7KwDY+7XhNxWtsG6cvS2c1+TqhzJGMxMAoM7A9rj0rrqu4ZuVvKdxZmqtZCWNTVjJnGVowGFAqmAU1X8owhmMXXEEt75gNn3d0cWmjy9GQqrFkoGH8RDx4yYVY+q9LeJ+UYGaY+szDseaOW7D49z9D/8rlbjpNk6ZiYpW3iXZ//QnQ/4ioIC301917D1bdeB36luYf0Ri3/0GY9crXKGSItO3VjenPeZEbV84NHG/5FZdh+X//hQ3Ll7kNszZuYsk3nGxcuxobVq3EBrWre9DfsxzaqOKOS5Z3uL6Nk6dgr3d8EHu9/RQseNvJTm+ZPRfsCAwOuI3Avd5xKvSWlPwLTvwAFjB2yiGHIh46b+kDXMj0cx59q1agf/UqDPSug3GzLPqht5rc3V9SOPS4cEqhmnfksWieORtmNdiwZg0e+u+lWHrxH7Di6v9iYMMGgP0nP/EQzDnq2KwXIWX2NlPr3Nmgs2t/NHSOR++S+7Hi2v+g58arsYFzLJUGYWZuI7GJ5+87hjqbVKYAVEscQYLCoTFyUxYDCbRyo3H+G9/OTba3o7ax0fUkvEOWlpZWzJo9F5MmTXZvbPX1bcDSBx/E3XfdgcX3LXJfGK1FR39/PwYG8u96ky5MPn2RsGLVR32VQz/YKadya4wd8uTTpBIDiYFRZ6CG/wZokI16fktJstMxMNYTjtdKvHZGc3wz/++2/k0bzXFS7l2PgXhNmflrbHQZGIsxRvcMUvadlYGxv/a0HpNkjIV7TCsxhwXb6axcbOYEl3WcMwsKh8xCiPMYIzMsU5yLazu2wiSMo8XiDLjhjaaPouLxtNFFKlIZWwZ6brgGd377C7jjq5/G+vsWusFL3Dm5/aufwsKffAcP/OlXDlPVMmOWmkwmP+057i0sAQPr1+HWz30C1518Am4842Rc/a434p5zv8F9GX9xT3nac7khNh+Vx8znvRQIC4FVN12Ha99/PG79/Cdw6xdOx7UnvxU9119d2WWIfcs5H8VVJ74GV55wpJOrTnwtepctAQYHKQND4ouA3jQbz424cQc+HhMe/XhIb544hSEl3qg17qOAwibIf+AToHb8AY9Dy26zGeOLu6Gp6gvrr3r763DNScfg6ne8Htd/+CSUNmp8o1eFLQvgquz2RzgmPenpaN19Aay21s3/prNOwZ3f+TIW/uwHuOObn8VtX/wkBsP/gjTxsU9CXds419OYTpIb1GoMJW7ULf3HRbj5nI/g7nO/hbu+9zXcRl77HlrKAMBq6zD+wIOB4kxK4OyYsAJDlUNRGWyy2Jm9hZnVcPxBzndAJrPJ59QdojIzTJ48FdNnzER9fT36ucF1/+L7cO+iu7Bq1dZ9xGiQ15v6KodyKadyawyNZSaOdojTT5NIDGwLBlKOLWBAz4ctCE+huzAD2+Na0c99uzDl6dRHgYF0TY0CqSllYqCSgbC2yFYYwS6GmWVeB7uNL2mFpZmwijCu3YCsp1PyDs5UJXGRcIdMbiNA4gBXCQXSRpcjI1VjycDau+/Ihltzj9c3rngIvUsecPjqW250raraio8f6iOCwiX3//EXWHHV5VIzuf/CX2HFFf9ytjZv2vfqdnqxapo2IzPv+dG3sHHdmsyWftf3vsTNkg0ZtkWK20CzzXTRrc2tHt67+kdZH1ccHODmjGx2Nd7iihikLZwNb17VgJlBR/nNLCSI/BQWMBj+UJ/y/h4H2nbfCzW1tShx/Pv/8Av0LX0Qio7+1bfdhGWX/82ZxnPr2Gdfp7vni0/pT4S9jJPasGYV7vvtBdCGX8zTv3IFlv39ItevhhtdDRMmOD2rGFhyCTPEKcacTilW7sRywE+hhD5uMq687kr03HgtSBZ7qrflgdtZq+V5z+RGZUdnJ6dXwrJlS3HvvXcjfp/Ew58eXC7lVG5dVxpLY2rsbZE/5UgMJAYSA4mBxEBiIDGQGEgMJAZ2LQaMK6vsjLnek+7XYNQyhborxrUYFTasXTGjoTg2DmBlzBlS0aooii1AsfvQ5aI5SP483DI1bXRlVCRlzBgYHMyGsqAPlnJMmy5ZQIXSNDXfpFr5v+pvXq265YasV1MhPoINEyc7dbCvF2vDRpsDQqUNN234BHPkDe9WbfaY5TdYtc5r7r4T/z76RfjP61+Ifx/zYvz7dS/ACm7S8H5HDaubzv4w/S/Gf495kfcf/WL85w0vwd0//IbbJKmWM8M0B46vjQ59nNDhxFhgxnlJcaCvmqdOR2lwgL4arL415w1gLPyx9q7bYebtlrm7e5C1nkEOdRWfaQR6778PpY0b3UOHJqNUSli7eBGstgYl/j3rO9GA0Ak8XGDBJlR0y4xSqpi/me/Xz42jJZf8EQ9SdD7aOJPEftuz1RtWM3ebBX056oYNG7jBtRA93PyrPJdtMUflVO57710IjaUxNbbmsC3ypxyJgcRAYiAxkBhIDCQGEgOJgcTArsPAptdUbiGXkeFitTwrwtQdnkVx3cjVosIKUJXln4/Q+sZrMbrcYqpC3xIQwmpCm5rEwE7BQF2H/+icJtu7ZLGaIdK/fFmGNYyreHuInprwRfMb162lVb0MrO7JHBV7KxleTdF2XSlsvlTzCzOruDl5d1oNMT4E9AaXYiQa18wKN65QgBA2dViNbmvLQ9iBhZtMlY8YoLatgzhDGdC574HQR0MnH3Koa6c+7TmYdshz0bLbXAb40tAu/g3whTOHnlRgdyqA3uiSQreaIOa+O8xtvPGkrFZflMyTDV415fFEgttgNMpLGcJ8Zd7Qrwzbjobeppo+Yzf3UcW+3n7cxw2o/r6+UZ+RxtBYGlObXJqD5jLqA6cBEgOJgcRAYiAxkBhIDCQGdkgG0qQSA1vLgFVZkw2bS+sxK/eaVQByV0DqJnjoUAxkyfEs0oW7Sn6n5JVWxLmVtMTAzsTAgLaVqk24cPFXueir9RiKFXIMdQ6LmBmscvNl2GjvcOEcTh9hdBteHna1drDp4maUagdR9+1wtdtQ4haUWby9ucHF7pza0C4O9M45rzoac/7v9V5e+XrMesVrsdvLj8LUZx4GnzN29/lg3mZvr7jaW6qDm2gJG1auxJ3f+jz03WxWRyvdAAAQAElEQVT3/vqnxPKiWG/lPfLcwasmuKX6eF+X2e58PG4xiTfHvDaz7Pu4tOG0ePFCDAwMjNk8NJbG1Nh+s2smzGzMxk8DJQYSA4mBxEBiYCdhIE0zMZAYSAwkBjbBAFd/3ruZtYTBoILKo2zBVumUzX5qJFlspoBLWy/yV4q6ZqEyfEBcCXsr1YmBxMDWM6D7ihsZg+5OHHkaM3MbSfFjnEqjDS4zy54TVGFmZUnNym05dY/7B1H0CYm6IoaK1eg7ujZi4/r1GOjrw0B/Hzb2Ut/Q7/RB4qUNGyAZ3ODfRioOrex6i81h2rXjkML8SDTA89vYjzV33oo1d9ya/QcE3g+oX8lxplj4o6A6IE/ozFgpTK76cRMwbr8D0dl9AMy90RYjtl87adKU7OOK99+/CIPhY7ojmdHs2bNx1FGvxemfOBNf+crX8M1vfhtnnfVpvOXNJ6Crq3skKVyMxtTY8WOMmpNzpCoxkBhIDIyIgRSUGEgMJAYSA4mBxEBioMCA1ns0tQZjww0orcic5qvg90Zl7XsZDEPDQh5jH6cao6izBJOaUcqL8jh/BnsrbXRlhCQlMfAwGdA9VVuLmuyW3Hw+bWjx6QAYb1qJcqhFOIKuGzggWeP7ZqZTzAzujzGr21ih4jyqjD61uehNrVKJW3OUq086Glef9Hpc/Q627zwGV590DK551xtw9XuOxVVsJXf/4Ouus+YjkVGiYiWORzFtMplQ2q4JhtOrVOzj9riquARZxYxNYEGMfqVonj4TUw45FFOf/lxYbR1RPjw3lbiQYzTUlpZW6Mvgxc0DDywe8Ztc9Q0NeN3rXo9PcIPr0EOfh1nc8Gpr6+CGWTOm8xyf9OQn4wMf+CBOOuldaG9rx0gOvdmlOWgumpPmNpJ+KWYzDCR3YiAxkBhIDCQGEgOJgcRAYuARzoDWW9kpct0Hs8x0SsF2Ly8UbIO5kNjEFaLigsf7K2vnVJR3BJOGVn6y1NJk0XBC4AYR7q0apCMxsBMxMLA+/16thvFDv39Lp1LHjQG1koEq38NV4qaOfDUNjWqqSk1TS1V8JOBwH6j0fXXzeU21mW5Eg9sg4saMbucSHyBmJjd3uvN44Q7cbMUshRwxXP3zbAHt74WZobauAfXtHfBHiVjQSr71dW6wC/wM6ckU6QaehgqNWPJ+uRZ8oa/l2bzDfMMz8QprzZ9N1ZL53Mc11WvISFX7jQZoZpg0eYpL/dBDy6Dvy3LGZqoabhK+4+0n4VnPOtRF3rtoEc499wc4/fSPcePro/j2t76BO+64zfkOPPCxOPnkU9HAjTEHbKbSHDQXhWluZoFgAUkSA4mBxEBiIDGQGEgMJAYSA4mBxMAWMDCS1ZZflTGSpTw11yIsOaaAAEjNHAUjuL2raFBniZto3g+kja7IxOi3aYRtwED/gw9kWdrm75XpRaVl1pzMXF/lC+s3rFju/HWtbWgYN9HpxaqmsQmNk6dm0Ej3BNxmi3uLKutaRTFihRuWG1IE4N6sGiReUyuTQp21meKpjLQwn3oaN02ym51YTGNWnq/X8Wlu/Nb5e3OU4FcSWirN02dg3AGPw7j9D0LDhHK+fLRqduA4Og/1qRhGkBOPM7a4scXuQlxArIYACD0YjMIRzPX33InFv/s5Fv/2AgxuHGBscBRCx0rt7Bznvny+v28DVvWsHPGwz3/+4XjUow5w8Rde+AecfMr78cc//h433XQjbr75Jlx8yV/xkY+chl/84gIXs9usWTjiiKOcPpJKc9Gc9H1dmuNI+qSYxEBiIDGQGEgMJAYSA4mBxEA1Bp7cVY/Zk9N2QjVuAvbIa/xirvy8wrotW33JloQoM641K16DcLGKkYS4bO3qnBnIdV2uV9PcGtw5yjumK9ORkqqdhYG1992TTXXGC16BBm4qZACV1jnzMfkpz6bmy9q77/BKoe5b9mBmzXjhyzM9Kru9+NWobW6J5ohbbS6ZGcxsM30KfsVyg0gd1F+tFz4QhEsIKMys0I/YcMWMfbXhFje7aAMGM+PzowTWiMe6B+51m1yyZxz+ctTGN9lCUENHJ/Y47n3Y441vw/w3vh0THnuwQuGeVSEGnGNJuWv5OFFLnFAYp8R4AqxdoWnOQ8UBrJzqKhqhmIaoxHhebuAQU2g2rl+HNXfegjV33cqOg4wqcRQmKcSMhWpm6Bw33g310EMPkpqS0zdX6c0sbXQp7sYbr3dvcpXCm4fCopRI7M9//jNcceV/HfSUpz4Vra2tTt9cpb6ak+I0R7Ox50djJ0kMJAZ2PQZmzJiBww8/HCee+Da89a0n4hWveAUe/ehH73pEbOKMn/CEJ+Cww56PQw55+iaikmtrGWjkLzGb+bNdNWloaESN+5lpa7Nv3346p3nz5mPW7Lk70XlsX8521tFf/dRGHPOs6vKygxtwwB51o35qT9y7Dt84oQ2XfrITZx/dgvPe045fnjyyr9MY9cmlAUaFAb2VVS2xW0loPeEULsEYZFyBOc1oxMLlkFkRUIRABpTBWusRy4qcOcZlUOZRBhk+QpqEOeP4NLkyZZ1KYmAnYeCBC3+N3mVL3Gybps7Afp/4Eua9/jjMfsVrMf9NJ6H71LO4WdPs/D3XX42e/13l9GK19F8XZ+a0Z70Ae73zNEx7zgsx/dAXY8HbT8GM578s81dTOvba18Upds+3fQAL3nYy1NZ3jHcbGyVuUOx53Hvg/CdG/8nQJhwDhqbUHepQ3ZxOcZV7HrgKrlup/O7G1Gcchj1PeB/2fOv7sccJ78WeJ74fc456M2N9nubpu3GT6r3Y4/j3YP5x76b+Hsx5zVu4CeTSu+rBv16IvuXLqJfQMmMWuj54BqYf9lJMeepzMOeIN2DBu06DPiKqsQf7evHQv//JWJYwZzeS5qiNNcIcnJOVUhQX5QBpEmdspjI+qCRZGDuW2XJUcOLGF76dpLWtHXV1dejr68O6Kh+bHW5a++yzDzes/A8Jv/nNr3kaPNnhgon/8Q+/Zw001Ddi3/0e5fSRVJqT5qY5aq4j6ZNiEgOJgcTA1jLwjGc8A9/85rfw1a9+DW95y3E49NBD8dznPtd9F+FHP/oxfP7zn8dznnPo1qZ/RPV75Sv/D8cffzyOPvroR9R57SgnM2/3PbFgr72ryj5d3djvUQdg9933QAd/wbejzHmk85gxczfoOzgnTJiACRVv3o80R4rbORh4Aze53nxoE6rJe1/SjK+9uRW/OqUdp71qZL8E3dKznj6hBhrnUXNr0RD21LQMWLl20z+3Ih07NQND1l/hbLK/9UwJjoqmcqMsy1fRz9hPwiYUHyBMmq4173CWV1nLKlvgElNJG11iIclOw8BA73rc88NvYGD9ejfnev5AMvUZz8eMF7wSk5/8TMTv3drAzZu7f+i/ON0FFqqlf/sTVt9yfYaMP+AgzD3qTZhz5Bsx4TFPRO8D92H1bTdl/sq9lMbJUzDxwCdg/IGPx6THHuzeclK/2mZusPE3gjXcoJFvwqMfj4kHPSn4nwDNFfkdmuUHdPtyf2iwBNNgEtAusapSYoqWObtj4mOeQHkiJj76CdB44/d/rMumt8PMDBMfSx/nOuGAx9H/OEx8/JNBOMs6sH4t7r3gB+5/VwQ36BonTMKMw16G2f93NCY/6RlomjSVE2HhRtain5+LDT0PsW+YL+cnTQIY5846JFdDN0DcC9xhrCVs8kLAXFyAfEdnlD8Y5SgVIwEOVNaXNngIK+9LcAxKe3uHG2XVqh7XjrTabbfZLrR/Qx9uvPEGp2+quvOuO6HNR8VMmjhJzYglzi3OdcQdU2BiYDszkIbfuRg44a1vxdve9nZMmzat6lsmZsaNhfk44YQT8MY3vnHnOrk020ckA+0dHZi3+3xMnzFzpzq/3vAzsSbdv2GDmiS7MAPTxtXgsMfU4QcntWFbf6zw8Mc2YgY3u0Rvz7oS/nbDBvz+yo3441Xb/7r7w4c68NePdeCcN7Rqekm2IQNaU2lt5VKGdarTY2VR4ZpRO0789z1HAOMfFA6XTzFGsEQJpaAGRI2iAYUjO9QxM7zPQaqURS1Qk4ckLTEwNgwMDmx8WAOtuOpy/O+0d2Dltf/FQF9vWa6Na1bjwb/9Gdd+8ESsX7yozFc0bvrUaXjw4j+itLF8Luvvvw93fe8rGNzQXwwv0wf7+90mQw3vuBIM4CaQWY3DtPngZRBmwccHQg0sG0v+mNDrzMINMjODmYEVKg8zI2wOZjrXYiPnqHEHBmA19MnBzTLldN+VZZzTwCBKxMzoZy8TVqJSKCuu+Q9uPvMU9NxyA9TXOBfwIaV+SrmKm4J3fOXTWPavS0IvPnCYw6VkWvUB+5S4UTZAPulinhDKPMoVLSjeYVQEumAqwYQCpBPnKLRkwB9uwLJsDvdxTqWTHakKYzOmpYYctLS08NxLWLN69RaNfdWVV+Caa67CD7//fV5Og5vtu4HXoP43RQU2NTWqGbFobiX+xWqumvOIO6bAxEBiIDEwQgZOOukkPO+5z3NvuKrL9ddfjx/96Fx84AMfwPvf/z5897vfxV133ikXamtr8eIXvwQvfslLnJ2qxMBoMrBmzRrceMP1mdzEXy7pP3p54IH7s39/p0yZivHjJ4zmNLZp7vv5s+s9d9+F22+7dYu+G3SbTiIlG1MGlqwcxMfPW5/JmT9fj3P/1od/3bwRG8LSZsGMWpxwWNM2nde8qfnP5X+8egPe+911+MhP1uInl/Zt03G2Jll7i6G1ydDcsDW9U5/NMZCtrcJ6TPHGlZpb1skI4jG/HguQa7T2cEqouBTxmqlRJeFSTmYmxhHMWYqXOMNVfgzVDpfiJqN4Z6DGxaUqMTDKDCy/8jJc/trDndz783Oz0e74xmcddvVJx2TYmjtvdZji7/zW5zK8qOitq5vP/gj+e+zLce0HjsdNnzwZV7/zaFxx/KuhPtrwAoo9yvXB/j7c+Z0v4r9v+T/cePr7cduXzuTm2Um47gPHoeeGa3DTGadkc1h7l/+f7mKGh/7zD1z++hfiste+wMdQ11z//boXQCLfv19HP23pl73ucFxGveem61wKM3OtKjPphlvO+TAuP/pF+Bc50kcuo08PBTNukvEOlu5x1cBdP/i66/PvN74Ulx/zEvz7DS+F9P+QEy8vw3/e9HL8+1i1r8B/iF9xwhG+c0W9bvF9uO3zp+OqdxyNmz/9Edzx7S/h1s99DNe+7824ndz03Pw/9vAPDeiRo2nT5LSgjUdxf/W734h7z/seON1MFAt3qAMV9gGCDh5SKcpDi8UFQCHGKnuogg++ECScpi/EjFroBWhwABb+YAwPfUeGhuvt7eUPywNSRyz38wfss8/+lPvC+ZF0Gj9ufLaA7OlZNZIuWczg4AA0RwFxztKTJAYSA4mBbcFAV1cXnvKUp7pU/dyUP++889zm1o9+9CP873/XQZteF1xwPk5824n4/e9/5+JUvfIVr8T48eOlJkkMjBoDl9BkegAAEABJREFUJf5ycgN/mRmlnz8P6hdAS/jv8G233ux+WaXBp0ydoWankEGe08qVK7B27ZqdYr5pkg+fgY38MfM3/+1HlJ9f1o/P/7YXJ31rLbTptYF+jfL4BXXobDWp20Tqa/M0l964/d/iymeTtNFmwLi2qhzDr9OyVZiPMEZpPcY1GrWsmPcWbKpZ10zxUc40F+DHAJRSAncoQH5nOF+oAAiTr5Q2ukRFkp2bgfX3LYQ2kfqWLd3iE9GG16qbr8dD/74U2tDSD0BbnGSzHXSzVQvSTVqOmzG28GAw85tcZsRDaMEdkMpGeSUez7oGJc/k/cW6xB/+1tx5M1Zc+U+sueMWbOQPTYVMITQgZYlkSLQhlUvowMb3UR2iiG2iKLDCbTCHxAeeM1SF85IaRTGSaI9F26SPrnKg9evXsR7d8vgnPDEb4OZbbs70kSpxjnHOI+2X4hIDiYHEwOYYOOKII9HQ4H+l/qc/XYjvf/97w3b58pe/jKuvvtr5Ozo68OxnP8fpldUTn/hEvOtd78YnP/lJnH32OfjQh07Dcccdj7322gvVjqOOeg3e977345hj3uDc+uJ7fTzy9NM/iU99+tN4+9vejoMOOsj5NlXtueeeOOKII3DyySfj02ef7dqjjjoK8+fP31Q353vWs56FE054K+d8Bj511qdc36c97WnOl6odkwH9EuihZfreUqCpqQG1tXXZRDs6OjFlyjR0jhvnsKamZtpTMXfefEydOt1hlVVTU5P7zqyZu83GrFlzXFxjY2NlmLMnT57CfNMwjr/IcsAw1bjxE1zcJMbHkCY3l2kON6uJcFlrZmhpbYX6zZo9F/rKhImTJqO2cI6xQ11dncul81XuiBfb8RMmupjJhf+lvOivb2hwfuUY7pyL8Unfdgxo8+t/9/jXupobDE/cq84nr6if95gGfPCVzfja8a04951t+Crb4w9rqroxprjPvrEV86flO12vO6QRwiTP3L++Ijtw8D51+MgRLfjmW9vwo3e14Rtsz3htC/Sl+UOCK4DHc84nvagZnz+2FT/k3NS+6yXNOIgbd8XQfWbVZnOoC5f+rIk1GfbW5zcVwzNd+d/1Yp9f56456nvN9pien18WHBTNXed67HOaMW9qLU48vMlxd/572/GBlzeHqEduU7musniqfLZE1S3fVEkCbuBaVm9aWYwKbZktQ53okypRH/aFE7+2RJUjDBN+SRFyuDhLG11IR2JguzHg7uJwY/IhEHaw/C2qmo+UiLE18/G+3tSkFSGJMT53fCNMmaPHtxGJLVGpEqrlRXkpwUctuANAS5iEaijBCiGhCT7/4AoRxHKNRnlxLuPjznJcnFQmpNcYxWZMS0O9/8e0v290X98eN24cXvDCF7pz08ct7l200OlbUsU5xjlvSd8UmxhIDCQGhmNgxowZeNSjHuXcDz30EH74wx86fVOVNsOiv7u7O6quVb5PfPwTOOWUD+LpT3869tvvUW5z63GPexye//zn44wzzuRG1JEutlgdeOCBeMpTnoLHP/7xOIqbXvrie308UnPbZ+998OznPIcbT6fgta99XbFbma6PUn6cYx/BjbuDD34S9t5rb6h91atejY9/7OM47LDDyuKjoTl/8pNn4B3vOAnPe97zOOf9sE9Xl+v7nve8123U6XvLYnxqtz8DxRmsK/yyqqHRb9jKrw2m6by+J02a4jaL9uJ1NH3GTHR2dqK1rU0hmZgZtLm1195dmDV7DiZNmoQJEydi2vTp2HufbszmRpOZZfFSOjrHYTrzK364rxUQPmvWbBenjTf1k2gDS30lNfoqC4EFqa+vx/w9FmDPPffCzJm7YcKECZjIOe222yx077sftPlVCHc/l2quyjeJm2FFn/TiPGbMnInGxibBZTJ+3AQ3T+UwKz/XssBkjAoDS1bmPxzPmTJ08+b017TgVG5yveCgBhwwrw7a4Hk029c9vRE/eVc7tAlWnNhj5te5DbOZ3ESK+EF7ekwbaXMmh12m4Pz4US349Otb8dxH12O/ObVug+xRbJ++Xz3eww2rL7ypNUQObY57XhPOeE0rXvXkBjyeG1t7cvNJ7SsPbiDegqOflW8WTxtf4+alOcTLbHJnju0/d+gm3wnczFP+Vz7J59e5a476XrNvvbUVp7yi+qaVxpDsP7cGZ7yuBUc9rdFxN5vnPm1c+fkPPaudH7ERrK3MnSavPa8Ei7bTyiu3LlVcmZsGS3mkt/T3y+WwN7K5MJhFe2Lyw+EC4I5H/t+KO81UJQZ2XAbMdJcDZmpLoZVuQacP2hAqsWbr6pFW6lNyecxsmE4RV1vyMVIp1buEGDYsPh4M1lOGlsNkUvezdQgUksHIj/Ix8lhFmDpJkQQXt/9kedETz7y6vev6Bv+PqT4OMVpz0fdqveud70VHeycGBgbwgx98f6uGinOMc96qJKlTYiAx8EhnYIvPTx9b1CJYHS+//DLo+5Ckb0ouvfRSHH74852cdtqHykLf/e73YP8DDnCYPp61cOFC3HrrrdnHr7WAf9WrXgVtfLmgimry5Ml4+ctf7hbuixcvxu23347V4TsU1felL30p9LZXRTccc8wxeMMxb0Brq1+M6WNh6vvggw+60PaODrzlLcdB/R0QqkncPNDm2H777eeQPv7iQ3NetGgR9DFOgXoL7bTTPiw1yQ7IgFn+Q0VpMPzgUZhnc3Or2ywS1Ne3wX0nZ/zlkTAzwx7cUNK1IHtg4yBWrVqF1ZSBAZ9vPDea5u2+h9yZrFiu/+wH0P0z3H8Wo80t+dVpeYiXvilpaGjEgr26s2tZ12HPypVYu3atuy/MuCnHzS+9eRXz6OcL+WW3d4xTUyatrW0wswyrNl/dIwro79+Y3a+yk4wNA80N+Tgr1gzmBjW9WfXMR9WjlrsAA3QtWTmIex4cxNrwe9oJ7eb+Z8XiW1p3LRnEnZSewv+ueBf7CJOsWOOvbabHJ7iJ9uz9fX7ZS1eVcNviAaxa72N05TyOm2TVNpRO5iaTNttawl6WvvD+bo67jDmUq63J8KbnNEFvnslesa6EOx4YcHOTLVEfzUly33KeoMAgejPtNdzMi/lXc0469zi3pgaDNv8UF7oMaR7FzbO53NzS40Hn/QD5W9Pnz21I8CMIKIV1XvGU9HfJB0kRok5U6zNqKgb/R3pRhDrbVEf+aLAIqZRCSrryeKepj1Po4ngIc+UlLiBJYiAxMOYMlN+xYXjdqVL5OCn4de+aRR9gluvY5BHjmCHk23RXxVNCeOhSGIEOWUrCMKleAg6DXB4DaKHysEqAduxN1ZcAkAVvq3Ydg0O2E+PztRJzjjGvamr841Q/II7G4J3jOnHKKadh7rx50ILv29/+Bu644/atGirOMc55q5Ls0p3SyScGEgPVGNAbIhHX5k7Ut6Z95Sv/DwsWLHBdtWH2yU+ejuOPPw7vfOdJOPbYN+Liiy92Pj3Hnve8w5xeWTU0NLhF9pe+9CW86U3H4h3veDtOPPGt7rvCFFtXV4cXvMC/IStbMmvWLBx66HNhZtiwYQN++tOf4qijjnJ9jznmaOj7xRSncZ/xjGdKzeSoo16DKVOmOPt/1//P9dGcjzvuLdDHH+MX8GsMxbrAVO1QDLRxEydOqK/iPzwSXlvL64KbN/ri95tv+h//Hb4N996bv1k9YeIk6JdSitXHIG+88TrcdeftuJNyE/Wenh650N7eDm1cOYPVSm4+6d92qhg/foKaITJ+wkSHKW5Vz0qnb66aPmMm6upq3M9KegP8phuvx91334nbb7sFt9xyE++Pfpdi6rRpjKtzuqqekL+hoQ6NFW9sVW5sxU0t9ZPoP5iIm8Q9PcsFJRlDBjpbDV2z/Ftc2oy5/Bb/MUZN4bXc5NHbS9K1wfXJC9bjhZ9YjVd+ajWOPGc1/nObj9VG0P89uVFhTt757bV49adX49q7vV/gR36yzmHCf3G5v46e0l2Pp1Hk19g/+Uc/Dv/YKhz1mTV49odW4VsX9YUtCOCJe9crLJP95tXi2fs38NkL6DvGfnZZP55z2ir8H8d9PnPEMfTS4iH7Nbh+19y+EUecvcbNQ30EauNLc5J8+Mf514kcsEcdnsUNOC0n9B1nmtuzOCedu+b240v7IJyPfjzvwAY8uat8fsotaSSszS1x99yPrMKLyN8pP8jHUcyuIFp9SYaeK1GRGBxla7mAuUZ/EQx1uqsCUIaVINS5Wfm0RaRENJQMFuYNvzIL/tQkBhIDY8iAv1vdgO71TWqxRdltDXfkPu5TD92BcjFZNcTPDSE6ddsPcRHPix4OFAUSDA21YiHKJCyIp2AwH6B/vthdvgDkDXGFqcnBqAmNOYhR1YPR1IGmKwqhYhRXNAgNlmKUd2keThu7SosejaYfQNVuS5kydQpOO/XDmD17ttvk+sY3voq///1vWz1EnGOc81YnSh0TA4mBxECBgWlcLEfz9tvviOpWtX/+85/cRx9vvOEGfPOb38Bll12W5VmxYgXOO++nbiNKoN7cUltNfvvb3+DCC/+YuZYtW4YvfvFLWLfOL0zixlQM0EcV4yJdfSvfnP3ud7/rvlBf8XPmzMGjHrW/VMydOxdPfvKTnb5w4UJ84P3vR3Gz7+abb8Knz/60e5NGQYcccoiaJDsQA21t7Rg/wW8y6foo/txVnOY999zJv8ehX/yuf1OnTZvpQvUWlzbA4r+3AvVLpoX33IUN3CiTPWXqNDVOBgcH0BM2wTo6O1FT4zcqnJNVbW2t2xyjipUrV7ifBaRvSlpaWjFu3DgXcv/9i/HQQ/77xxzAqq+3F/fc7e/TGv6yTh/LJOzKqjAXGZUbWfEtr95ev7nR1lb+hlcbeTTTT2dAMY9yJRldBp51QD2++KZWTOn0S/yFDw5i4dL8raYXP77B/cy8vr+EM36+3n2ZPcJx//JBnPj1tdCbWoL2nV075DuxhG9KLr1hA77xp15cc9dG/O6KfnzmV+vLwr9+YS80jsDx3JBTG+WYZzRBG2yy/3hVP87i/KRHOeNn63Hzvf5b9mdPMhTfOIsxm2qP4SZfc4O/Ln9bZW6f/XUvfv1ff03X1QKvOLiharq+DcA5v2Lsf3xs1aBHIGjuyuGJaf3FRsXM2EjYsPilWm4TGqZwXeqDC34BxAsIOKZQ8HBDseUqmLUfw+in4YsC3dzM26z9XUAlldFlIGVPDFRjIP4QZZbflJVxZuZuYzPLXAU1w8qUGOBueO8RpGeAt+ByouqRj6P43FKwLKJKRjOmJ0JLPt8EN7ebvIco3ICZqVgJ3PPK6DSqxWLEtNmVYSbNPwC9ypr5WDiOfLkY++bWzq1NnDgRp5x8KiZPmcbfvK7DOeechX/849Kd+6TS7BMDiYFHJAN6S0UnpsW9Nnakb61oM+snP/kx3vu+9+Kiiy4akkZveWkzQY42LrTVVoo2Fn7zm99UwrjvvnsRP4Y4blxnmX/evLnO1vjnnnuu0yurM888w71Z9vaYzpEAABAASURBVK53vRPXXXetc++///5oampy+h/+8HvXVlb33HNP9jbZpEn+7ZzKmGSPLgN1dQ1oaW3NRN+vNWHCROi7sebvsWc2+H33Lsr0oqKPIq5dO3STSzFNTc3Q21PSlzywWM0Q0b3x0PKlDm8O/4mNM1gtX+43oszMffcXoax0do6DmTl7+Qg/ttjGDSd10JjLlvqP3couSm/v+uwjxsX56H+j1JfzK7b45ll9fQOv8wbBWHyff5NNm2T6OKMDWbV3dLIG9FHN4bhyAanaagamjKvBr05pz+Q3H2zHxR/vxMePbMGCGbUu74aNwLf/0ud0VfruKn2nlfSr7hzAv25igIwK+edN3MkhVlsDaLOL6haV7/21D2/+8lp8/LzyTa6YRB/3k67NJH0pvHTJ3CkckIo+HvmF3/VSG1pO/dE6vONba93/LvmXa/08h0ZVR2ZN8vlXrSvhm3/OeSlGf/WPvdBHH4XtGXiUXpTFKwbxt+tHNnax386ul+JqKzyHdD5uHesfSzJh/CPF4VKCZH2dbay1emMjlY0v5nqbN1jnGg3ENad0t3ikoiwuKirZ3AQgfRk9OUolMbDdGDCzMLa/Ic2iHWA+VPSw8N6I8fauBHJXuZbl8x3M8vweKQ+He8SUe6pafNoUUqHyoNtlMlcXvFbQeW7OIqYxJM4OVdlDMXN6xdcMZF+rHINwWV/aY1H0g6TGqeFvRdVuCzEzHH/8WzFhwiT+Bpi/3TrrTFx7rV9UPZz8cY5xzg8nV+qbGEgMJAYiA/GNFD1jqn33VYzb0lZfQn/kkUfhPe95Lz75yU/iy1/+Cr7+9W9gIn8RoFxmpmaIrF69KntLptKpjTJhtRX/61z82Nh9993HXy5UX2xpE0zfFSZRDsmMGTPVOHnsYw/Caad9GKdVkVmzZruYurr67G0wB6RqTBhobmlyX8q+5557uXaPPRa4TS5tdmkC+ndRm1zr1q2VOUT0cdYhYAAaw0anzM5xEzBt+syq0hY+Hqn7pK4u/7jgmtWrsSF8/ipeh8oliba+82rtmuobbYorSpxPqWSYOm1G1blojvX1/iNqDY3Nxe68d1Y6u40byZqrjPaODjXYuHEjdH+tC29GRlzOjhCzatVKLk6zn9jkipLah8lAPfeypo2rQRS9waW3oeKT8N6HBvGZ36zHhVfnbx09aZ861Pq9Huw2qRZfOa61qhy0R35NzhgfOmzFfPVRRP2vh/rfCvW9YD95Tzv+/JEOdM/m5EO+OB+Z41r9WNpI0maXsErR22mX3bwRkkrf5uyYf9GyQSztyd9yK/bTuPILa2uKbMrKZc36XfOator1lpESCZusxPWXWbnHrGiXmMngoFLWlUrsTdUVOSXOgKnJTVlVJAa46LTRVYWhBCUGtpKBeHONpLuP1SZWMXqonXsrfbmnmubzew9v9mBuPocCGe87Dl9XDVHfQhfGeIRKAfaq93i9em3+keadxqZaF4e5igHlxYr9y12jYg0O+n809fGCbTWAvth5wYK9Xbqfnvdj3HbbrU5/uFWcY5zzw82X+icGEgOJATHwUOGjUfPmzRP0sOTpT38GvvSlL+P000/Hq1/9ajztaU+DNr30Me7i2yfDDTKgb1oezlkF13dnxY8tajOrSsiwUPHjk495zGNw0EEHVZWZM2dmOWbOnJHpXkn19mBAPxv1ru/DiuXLcestN2HZMv/GVbW5VP+Jw0c2NvoNI1lTpkzB1KlTq0pbe7tCnNTX17s2VivCW12KqQ2bsHXcFJWtmOiXvjlpDBtXtbXc6BpmLppjY6OfQ0NDvsGh3PFjh2aG+MZWe3uHXO4L9qWsWtWjBh3t41zb1NSE+nBOq3r8RplzpGqbMtDbX3If49NH+aLoDS4NUuJFqjeTfvavfJNL+LzC/744Z5LhwN3rqspeM/ONqPFtfvNJ/UcqBy2ow3ff3oavvLkNrzmkEU/fj5v6c2oxb0oNOlqsahptimmjTs74xpf0bSXF/PGNreFya7NLvsZ64DF71klNQgaG24bS85PufNVV7a+Y12R8v0GxLpcwGZlYniPDKhST7SopTvI0xHPD+bb86nXdUpUYSAwMZYA32FBwGMTH8meH4I+2lf32y8xgZiFmS5rYp+KO32wK9tO/kCGOFiTBZBMspi2EFWK8302ZMSg+1dg7N32cIImLz52CnBgzS4LBxijF4gZhVBEDbfJYJR9G8YjfuVFf37DNRunq2tflWrt2NS666M9O3xZVnGOc87bImXIkBkaVgZR8p2DggQeWZPPUd1ZlxmaUww47DIcd9vyy/z3xkEOejhNOOAFz5syBmX/26+OG119/vfuOwnPP/SHuuuuuzWTeMrfe8oo/tBc3LUaSRR+TjHG33HILRiLxo5exX2pHnwH9Hd9w/XUoynXXXs2/rxuwcOHd6Our/pGmkcwsXjuKXbFiuds40+bZpqR43ajf8hX+f180M4wbN05Q1spYEfzSNyelkv8+o4GB0ojmsnLFirKUeqtt40b/S7yOjk53H7a3d7qY1WGDa/WqVc5uam5EHTfkol9c6I0v50zVNmfgodUlvO5za8rkP7f7jyLy0sGRT8s3XePgG3gdRH3JykHcfv/AZuX+Ff7vP/bbXKsNpQ//Xwv22a0WeutM8Wt6S7iNY+mL7n/1n378+1Y/T/mi9Kzh1of/kR6N9RbhbdYW88d5DZe8PuxtaZ2zPPxvj8PF7pK4iAknbmbuuSBTf30WFRnSi+KcOeBCMkyKQ/IACJPAaciOPI7De1RhmlcG+Ji00eXpSXViYPsw4O9DN7Z+KJBi5u5WmKnlVpFuXDrMvO1r0I8RHCGafUOaTfQLk2Gs9ohCT6kV49CjQpFDTehJM2hsWGjLywaxBZSeZwUgx+LcEA91Dm7+0xdR1wbY6VAyisI94OvKPh4d3bp/g/+IS0PhN7oPd8SGhnqXQl9sXPnDsHMA2Jo2zjHOeWtypD6JgcRAYqCSgSuvvCL7kvcnPOGJ0BtSlTGV9gtf+CIcf/wJlOPxrGc9O3M/9alPhd4OEXD55Zfjgx88BfpfD9///vfhrLPOwo9//OMRfSG3+o9UVnChvyZ8LGz8+PEj7ebiim+z/exnF0Df37U5+ec//+n6pmrsGCgNDrqP3emjd1G21ej9hU2yB+5f7DbOtHm2KenvL3/rpq+3l/eQ/3li3PgJbmrjxk9y7dq167doIy7ORz8/bGoO0bdo0T1unGLV0+M3v9o7xqG5pQV6O0z+uImlzbCBsBmm7+jrCB9b1McrNa5ik4wNA9/6M6+dsE+798xa/N9Tyje79LG/OJNr7hrAkees2ayc/cvq37MV81S2z9yvHpM6/E/qGu+cX/fimaeuwlEc68Svr8Xp56+Hvgi/sp9i1/b5n+bHt/n+lTEPx96S/ONb/fir15dw1xK/Wfxwxn6k9DWYPxWuu6Q4q2IB5/8GWTsn2CMoKB4ec2kY6j1S9JICLe+mIkxCtaxkAYjDu9bBipc4I310sYy3ZDySGNiBz6XEG1M3Iafo7nK2LGb+pqTKwpudd23c/CJQ6COLW0Uhhbcq69ypHBKllzBtZXCwC+NTVQZJcIZmUwg7VUR5RH0kdBLQXKixBIwaYdaFIoBuMlUApRLkY1NaJuGE1CXDtoPSu97/MNDc3LLNRv/lL3+Br3/tK/jGN76+zXIqUZxjnLOwJImBxEBi4OEy8MADD+DKK690aVq4KH7Na17j9OEqbWQ9+1nPytzF/002bpLpf0n8+Mc/hmuuuSaLi8qkSZOius3a5cuXu1zz5s3Fvvv6t2odUKie+cxn4qST3ulEHzGX67778i8f10cXhVWT/fZ7FGbO3K2aK2E7OQPFt8Hawkf8qp1SXV0dzIZ/12BF+LL6trY295HB1tZmlybizhhB1dvnN8waGuqwqTcU68NHDauljB8/bGzkBsakKS5EG27FTaxVq3scPm7ceOjL/WX09KSPLYqHsZQbFg7gH+GL5PXz/sufWP4Jg//evhFhTxJ7TB/++tNbWYdww2pr5r7H9Pxjj/qOsJ9eGnbeCsmmjqs+9orw1XOzJ9VguPGPeFojznp9i5OndPtfBhdSO1Xn7pSKKuafO6UWT9y7rsLrTX05/typ/hyWr9Waw+OpHsrA8OzkK7JsHSco6yCFQGhiZiKQuDcs5HMOhzjIOwXK6XFZ+vvOrBIEZVL9SsvcSUkMJAa2PQMGM8vS5hs/GeQUM8vizMxhqsK+jtRNSB6vrhIFj6yvIsGxvWDIwccWnzHKFfP6EIJe8X2p5wgNFQIGoyZhw6I8bFhyjAYUZlaBCfSPOxQPRTF1BpmLy8wxUdavX+fG0cKtpsb/I+mAh1GtXbsWl/7j71g6zP+WtDWpNTfNUX3jnKUnSQwkBhID24IBbdBv2OD/R6qDD34SPvSh0zC+yttR2qT60Ic+hHm77+6G1Ze//+Mf/3C6qvgl17W11Z+nxx57LDo7OxW6TUVvjylhXV09jjzqqOytMmGSGTNm4Oijj8Yzudl1yCGHZF9Y/5vf/BoPPeQ/dva0px1S9YvmtXF2yimn4Mtf/jK++IUvKl2SRxADertpffil1/Tpu6GOG1qVp1dbW4c9F3RhX254zp03v9LtbL1ZGH82nDN3nsNkr1zp365ywAiqFcsfyn5JutusOVV7tLS0Yp+ufbHvvgdgytRpQ2LWrFmdvTkZ7+PVq8o3sVaHjzF28H40M5djVcCckaoxY+DLf+hFT9igmT25Bsc9rymMDdy/fBA3LfJvKM2fVou3HZ77YtDkzhqc+spWnPnaFvzu1A686PHlm2Uxbrh2bW/+03hjlY8gvuzgBuw5o/oz/T+3+X836uh+/TMa0RnerEI49plVC+FP4wbXk/epx7r+fCyFDAx6e3xL9e2NYv43PnvouSuH8PjRxqvvGPoRS8XsqlLK1l+eZ8dDuN+dzsqM9z8L1ayY1mTqYhHySp7P4wpxmtwSZ5RX+ZrR4worwzS+xvPu9EZX4CE1iYHtxoCZbtM4PG973rH6gUaSocSkm+WxBbVwSyuqUtTH+MMOUOyDqgcfMxyLxcVnz7RMUS64PMqlOPDwKBUVpsjCZUNeivDQODhUyiOVLjVeFBvFI75mkGBvsI4TcGPQDoUsBm3sGn2xuxZmZoa2whfNjt0MRjaS5mZm0Fw155H1SlGJgcRAYmBkDOi7qX74wx+6j4epx+Me9zicc85ncPLJp+AobhwdccSReO9734svfvFL2WaQNvW//vWvKTyT22+/3elaXJ955ll48YtfDH3B9xOe8ASX6wUveKHzb+vq/PPPyzas9tt3P5x55pk4/PDDsddee3H+r8HJHzgZ48b5jzVqjnfeeWc2hUsuucTp+mXCqaeeije96c147GMfy02EffH61x+Nk046CXpLR5t3PatWudhUbWcGtvHwSx6432Wsq6vhNdONceMnuC9n1wZXZ+c4buzOh96wqqmpwYaKjy0Z4FGZAAAQAElEQVQiHAMDG7Mve68Pb1v19PRgYMBvUoSwzTYbN27EQ8uWuThdd3su2JvXXzt0/TU0NGLChImYN28PmBlqOV99bBIVh35OWLN6dRlauYm1enX5tawv9q/8SGZZgmSMGgPazLroOr9hpEGe/9jyjapf/Lsf8f/oePVTG/H5Y1vxiic1QF+6/jZufJ1zTAvmTOIP2+ys3zH86+Yt2+y56s78Gj3pBU1410uaXW69oXXaq1rxtuc3gZcasw8tX7uwF/GL6PUdX187vg3aeDp4nzq8h3k++uoWdIYvs9dHCq+8rXxuS1b4FcKcKTXuvE56UTNe8oT8/Iv5951di3Pf2YY3P7cJBy2ow5sObcIPaT9qTq2b2AMrB3HGz/wnNRywi1cGKzBQ1AswVbd29X8NtMBeXH9qUVjWxQcYvSg7tHqjjyWHvcFHlFuXqoXr53GngofB+VnTyEv1Lc/cn7TEQGJglBlwD4VsDIOZF0HRR0gmb+KS88vI9nholCjVi/cojxkfNt6sHupQAwdQgY48nLgAPawQdWSaHk2Ih9ySaLuWmYSxcabL47XyWkFEQlOWl7C6WTYqAZ4TaFfGKUaCMT7iD3sdHZ1jPPLIh4tzi3Mdec8UmRhIDOxKDDycc9V3VJ37o3O52eUXXJMnT8bBBx+MV73q1TjiiCPw1Kc+jQvuNjfEai6iv/nNb2QfeXQgq4sv/iv0ZgtVdHd3441vPBbf/vZ38MEPnupyadG/pW+4KNfmpLe3F5///OegjQXFzp+/B97yluNw9tnncP6vwtx58wRj5cqV+NrXvur0WH3nO99G3Oxqbm7GC1/4Qnz4wx/BGWeciZe//OWYGt6YWbp0KfRl+rFfah85DPT0rMTi++51J1RXX4s5c+aiq3s/+De4dkdra6vz6ZdNDzyQf9zVgYVq+XL/dmCElof/jTHaI20XL77XXauKb2lpwfw99uRc9sc+Xd2YNXsONEf59Dai5i69Uoq4vpx+/Xr/BnuM04baunX+Y5LC4vd6SU8y9gyc9fP1eLBn0A08ucNw8iuana7qd//tx4/+3oeNA0CNAY/nJs+7X9yML7+p1X2B/YLwtlUfH90/ubQPS0Me9R2J6KOKdy/xY08dV4NXHtzgcusNscMeU4emBsOyYb7gXW+iffY367FqvV8s6H9pPPY5jfjMMa14OfPMnuy3LVatK+GLv8+vN4Tjyjs3apkALQ10Xq96cgMOK2z0Kf9nft2b5dfHLI95ZiO+yM2+NzyrEXuGj10q7vsXD/3IZRhml2y0zjJY2bnL0vrSkU6PbFOM0fB/hXSViBAo5RiIgIcgNqEYUaMuYZMVb2vNq79XD6tnjjuMkJkwiUNc5a8Yp6YqMZAY2B4MmGkDio8Q3cV8JMQ5mPmbVY1zBYd7qAR9800xRwnKpT6xle6lxKYoYGzoi+IhTHPlnjnDWYJTeBCBEpnBmzUBM1gGSVE4s1KVxkalPESIEx/n1KyqDK0WkwWPorJ2zWroBz59F0ZLi/9hdhSH2+LUmpPmpjlqrlucIHUQA0kSA4mBETBw/nnn4eSTT8all17q3iCt7LJq1Sr85S8X4aST3oE///nPlW7of1f8xCc+gbvvvnvImyw9PT34wQ++j6VL/dsq2vQqJoj/Tsa26BuJru8Z+/SnP4WrrroKlW+m6A2Xq6++Gqef/gnceuutQ9Kp309/+lPcd6/f7CgG6Duc/v3vf+NjH/sobrzxxqLL/SJLwNbOWX2TbIoBv/gu/JSxqeChvvCD2Ej+fpYufRB33XkHKt+EUtKBjYNY8sADuOP2W4dc1/JHWb2qB4qVvXHjxqq55HMS5ia9cn6yF95zl7see3vLv/he8bomFy28B/dW+SJ6+SWrOBe1ktWrVqoZIqsKeFEfEpiAh8VA/Kve3HX8uyu4UxVGOqS7Pmi++eLvevHVC3vd/7gY3+7yHkCf/rtt8QC04fTdvwzd7JE/xg7XvvUba6Evu+8vf+EKsi/+3wZce3fu6MtVl+6PV23AWdyou/buAWyo8Gns6+4ZwEfPW4/LqrxpdubP1uM3/+nHyvDRTSWc2lm+Qrjw6n6cGfNzs08xUbS5p+85e9f31uJn/xp6rwyWfK5KzmL/R3pbKqxR47makRMW2boms5iAeZwe2RIBIY+6BpWo7+lCXEXIrRXZl6ogd+17k4gvwp3GZHrWIU/o4LTR5WhIVWJgezCQ361mBjPjJCTEeTf7G5a3LE06HkZRAoMxA9OyrpZT3igMYZdsfJrlxaCpOilzBMOYXypzqPEWQW+42j/OnOoqn6s8puJZ5eLAEBavZ3VlNu+ojnrfaNXirCd8h8bEiVNgNnS2WzK2fvN78BOfBH2XzZb0qxZrZtCc5NMcNVfpSRIDiYHEwGgxoM2cM888A8ce+0Z85CMfxte+9jV8/vOfx3HHvQVHHPFqfOYzn4G+wH648W+++Sa89a0nuP5f/epX8MMf/gDnnHM23vzmN+HnP/+52yQ7/PDnu/+NsZhD/9uh8Ne//nVFuEzX/96omFe/+lVleDS0mfWhD52Kt7/9be47tb7zne/g05/+tBvr1FM/OGSjKvZTq024N7/lzfjwh0/Dt771LSfiQfP+GDe57ix83FHxkpHMWXFJto6Bm2+6AddecxU3oG7fqgQLF97t+t92a/kG5XDJVnFz6I47bsONN/wPt992q5ObbrwBN9xwLa/5xdCG6XB9hZf4A9v111/jxrzh+uuyjVD5KmX58odcnM6vWl7lWrbsQdxy8/UQD5rPbbfe4uYmW/0rcxZtbbQpt0Q8FH1RX/LA4mwO69aVv/EVY1L78Bl49mmr8Pj39OBlZ5R/nLQy81f/2OviFPucD6+qdOMHF/e5/3Hx3d9di2/8qQ8/uKQPn/9tL9781bU46jNr8PPLhm70KMn7vrcuyxu/70t4UfQW2Ju/vAaHf3wVzvl1L37yj363sXb819fg/d9fh5N/kOeo/Pih8vz5mg1405fW4DjG6+OGmpvyHHH2Ghz7xTW49IYNCqsqnzh/PQ7l+b6fY5z9q/X4ANvKwItC/uO/vhb6TjO9vaV+Tz25B8d8YQ3+d1fFDlhI8PQP9rhz17kFaJdu3DKPz6khJDiHRw3mlQKWAcKCO2KC8vWfrDyAyxjEdAiHIoIK549GaNNGVyBiVJuUPDFQlYH85vWbQTGIuArvWDMqhH1NJRSzSiQ4qjYhNjQKKagyK8R7NYSkwhlMH6MHjNcCHJ5OsZ/3+TpGqDWYmlyYiIV2AadqxopoZbFif8ZYRYDRL6mAx8Ts6VkJfRFzQ2M9OjrHbfWYZoZTT/0Ijjv+rTj99DPQOa5zq3Opo+aiOWlumqOwJImBxEBiYCwY6OnpwX//+1/oC9v/9KcLsWjRoi0a9sEHH8Rvf/tb/OQnP8Ff//pXrFkT/nuuLcqydcGa6+9//zvo45iXXHIx9L9AjjTTFVdcgV/84udO9GbblvQd6RgpbsdmQP/mrl27BpL+/r5NbliNxZnoDS7NRV+cr7mNxZhpjB2XgX/dtBHf/HMv9JbXuX/rw3V3VrxG9TCmro8A/vTSPnyGG07fuahv2A2k4YbQhtO32U9zUx59L9dwsZX4xddtwHncYNMbWpW+aOtcv/fXPnzp97349X+qb+zF2K1qH0GdtKaSFE/JnOFrp7Iyrr9UqG6yuLiyCKMliU3QaZaXiPtVY/RpM9/r0e+tGt+kOjGQGNieDMQN8eKNmuucWfl9uwU/KPFBEJKrURoJM1YUxjkktNxkUXzYt3IeX8lPoZPFPcto0eVrOATZvp1HVUuIs+Tj55q83pLGIBWpEulROKigyre1hMUQtZV+YWMl+ntbtvRBN9zEiZPQ0Njo9C2tGtlP/7uX+jU3t2La1OlSt0o0B81FnTU3zVF6ksRAYiAxkBhIDCQGEgNjyUAaKzGQGNi5GNC6SjJ01vkKzNwaMLcVm/UxWRUiLAv3CpefYQ3p7dhDFpeANKWxcWOp9WKmZBJvxzptdEUmUpsYGFMG4o2qtgQzf3Oa+e/rqpyKv7lzlGG5MUQrFRDmZYlA9MQ24kAMUiuvBMhgxEN+CifA4vbB1Eavnk6Vc4VLwj7gEdL6B18wCOc5QhyxYjeZThhodEicXaisoEv1Y0gbe9FvSlf19MDMMG3aDNTW+v/FZUtmoi9E/uUvf47e3nX4938ur/pdMCPJp7E1BzOD5qS5jaRfikkMJAYSA4mBMWUgDZYYSAwkBhIDiYGdgwGuK4oT9euu8tWYwXxIvuRztjNVBTdcHAEWp6L8UJjEo17zNeCmwcVntV/ip40upCMxsD0YyG5PDl6+uWXmfap106plkCtm3uL97OzqlY/JfbltxrFyR0HTk6VgUlUvjaOWZqEoVuIhxQAxyrxmgFdiE+KFQ4cUiXRuj9HNErt4ULVAtWWiR2lVRxZlzCTJgO2g6Psw9BGB+vp6TJ8+CzU1W/64/fnPL8Cxx74BX/zC51Aq+S/S3ZJT0ZgaW3PQXDSnLemfYhMDOwYDaRaJgcRAYiAxkBhIDCQGEgPbg4Gqayq/ABx2OuqjFZsLMFeHKhhqypZzAkKIawp2QeWqkd4sM3UWrm9ZqORF9pavvPL+SUsMJAa2goFSlQeDWfEODnd9gGSZeaNa381OgeOpnxlzUFe8VLW50Jcb1HJb4xMIRVbwUVWeYOV+AfTpdS+vypBbln885ZpwcFvKCyqOiscYOyuXufiKUA2XQeonyYDtoIjz+xff576vq7GpATNmzN6qN7s2OfVNOPUml8bU2PoeDs1Fc9pEl+RKDCQGEgOJgcRAYiAxkBhIDCQGEgMZA5VrKpNHi0C1QRym1ZiWasRiHzPvkQthBecQxTkF4SBQaUcPXaFrQCw35fPJ6XMGW79kTBtdjopUPdIY2JHPx8wqphdvSj4S3EaU90s1s/xGDr3MLGiba0JexpuxDxMKoQaqw3RWhFycCxszqxjfiKqwZVGe2EOoFzpYhEvgMhAID6FyDf4gqFg/qodUmxl7m1QvtAlQL2CbsejebmVgYCPuX3xvttk1c7fZW/2dXVtyEvpOLo2Vb3LdC81lS3Kk2MRAYiAxkBhIDCQGEgOJgcRAYiAxYH4B5ojQms0vJs3ZrtIarRAjzGQrWGJCSkKkVEiJNgPUUIOLog1/5Jq3uY0VVpXRVmuA65clQdroQjoSA9uXAW0W+RkYzMyrodYbOLpd1QaIzxUh0dpUG3Nx+0iDhNyb7q0+UfgYYb/q8R5VZPkMhNDHouFkeT8BrxTqckzxQN4DOhjC2UvLpRqWe6kxgLVV5iK2PYreprrv3kXQRwf1EcLduNnVOW48zGybT8fMoNwaQ2NpTI2tOWzzwVLCxEBiIDGQGEgMJAYSA4mBHZ2BNL/EwMNmYMh6TBmLSxmuGblyBApY1qcahnh4p68j5tdy0SpvFSkpR93Ybvsr96WNrkqOkp0YGGMGzGzI5pU2tswse1ZQ66igHQAAEABJREFUhZmVzcys3C5zZoYeFCOJyzoEpcTxgKE9S/APEjb0yiqfhhD6QkdZQSVYXoz9M0SBEgeYq6tWLqbkepZHlVtV+25HUG9T3XfvQvdl8GaGSZMmY7fd5qKlpXWbzUq5lFO5zfwXz2tMjb3NBkmJEgOJgcRAYiAx8IhhIJ1IYiAxkBhIDGwJA9mKi2uNYr+SMzIv12pBD41zszJ62CA2fl1p0OFzSJN4S8N4TViUkuvuerFye2zORcO1gPqljS6kIzGw/RjQhpZucN2MVWcRHPkNnEf5vrk9VCsR8jd8SANZUadz82VIsMvg+3FScrPxtqvldwo37+DG0yzgjuALTY47Z6hKrk8wUG4AzuagJYg1VoUS0jrEGJj9FsEh27/S39fSpUtwf/jerobGekyfMRO7zZqHjo5xW/Vl9fqyefVVDuVSTr29pTE0lsbc/meeZpAYSAxsDwb0fNjqcVPHXYqB7XGtmNkuxXE62dFnwCxdU6PPchphV2TAuK6K5601mMkoXwD6CDkUQP9w6zDhLsRVDIxFfaPusuVA+a2tjube3XLhNIf6uU4knja6HEOpSgyMFQO86wpDmekmjqKb0vvNhOW2umz5poXPob5O+EBSdjbODEM4Pa8UIcv3LR8z+uSn+BAq1Ytzuyr62Z8lPpnKXAVDD8CsBydr7mEXEd8OxZQYWWQxB3awY926tVi08G4sW7YUAwMDaOSG1+QpUzB33nzMmDkL4ydMRGtrGxoaGlBbW5fNXrow+RSjWPVRX+VQLuVUbo2RdUzKNmUgJUsM7OgMDA4OuinW1de7NlWJgc0xEK+VeO1sLv7h+OPPFfo37eHkSX0TA5UMxGsqXmOV/m1r+587t23OlC0xMBIGdrxrL1uXaWpWcQ7CJAE2rtZMel7R4sqNMQ6ixRWwq1VxKaimqrBLwGNPIVFH+o6uwE5qtgMDDeMmomHCZNR3dG6H0bfdkHXtHe48GsZPGEFSY4xuQjYqhbtX/zCbye8cqmAWbWcOsT26udqPp9rM51NTGDokcBEFHfDRCEe5FUDXTO2ahse87vE48LWPw4Jn7e0wVdP32w0HHnUQHn3U4zD3yfMBDuxGYSq14FHbUIdHvfJA7PeKR2P//3uMa/d72QHY7+WPxr4vPQDznjofk/aYjIaWBkazxI5U8+J39qPLYLlrB9T0d92zcgXuuftOLFnyANatWwczQ3NzMyZwo2va9BmYNXsu5s7bHfP3WOBEujD5FKNYM3N9lUO5lFO5kY7EQGJgl2Vg48aN7ty1Ke6UVCUGNsNAvFbitbOZ8Ifl1i9llKCpqUlNksTANmMgXlPxGttmiaskKg1uqIImKDEw+gzsGNee1lkSf77cpvJKDjnbYK7NG79e86Bqv3KzGCBoC8VlyBa1VtY7vdFVRsdoGClnNQbadl+AAz//PRz42e9gj+PeUy1kp8Ee9YkvuvPY/5NfGeGcCzchNyrcZ/zY06yA84Z3GxbhxpXLjA+HYDN8hEW3v/IazIx9Smy5T16iOqTIH0GNFfXNt/XNjRg3azzG7TYe7dM7fAemq2+tQyexzpmdaJ/aTrw0ZHyrMXSyT+eMTnRM60CnhHrb5DZ0EJ+273QsePbeeMxrHoeJ3PBiEmQPVBkSjmUwaU7kt4LtwB2w0t/xmtWrcP/ie3HXnbfjgfsXY+XKlVi3dq37nxqLP6xJ18cS5VvJGMWqj/oqh3LtgKeYppQYSAyMMQPruXGuITs7t+4j0eqbZNdhQB9b1LWiM47XjvTREv0nKcqt75U0M6lJEgMPmwEzg64pJYrXmPTRksE194xW6pT3EcHA6J3E9rj2tK4aekYlB+VPcWoeCjhtluJyrHoeBbkucLFlOQjJXcCIIB5y8daH6wcdeaB8aaNLnCQZcwasoXHMxxytAWvrG4DwUZHNjlFto0p3YqFj3LDwN653qptwhxViR67qxufjRU2hk89eAJzqg9xY1QNclCrNS+3gxgE13LMrYWDAf2xGgH7hpXmXBksYHPB5hUex/MlEqOQ2sNatWIf1K9ejt2c9+tf2ozTITTd6FLrnMxZg8oIpVI3xhaKJVEAF706h6iMja9euwUPLHsT999+HhffchbvvugN33H6rE+nC5FOMYtVnpzi5NMnEQGJgzBhYtarHjVVbW4spU6Y5PVWJgeEY0DWia0X+eO1IHy1Zv36tS+032MY7PVW7EAOjdKqdneOha0rp4zUmfbRkwx3fHa3UKW9iYJMMbI9rz7jyipMyp2hN5zVnuopYAXKrOq3PCGsZ50JYuRBX0XBFAU7xlfOpUgZCcnuTRnmRqxxRoEfkSxtdnotUJwa2ngHuCJXy+2rTeRg7NMB31oZQ0adnQ9GWLszMx8uWlFtCougWL/d6y9eKUoRaL+WWxzZdayqSwQFudHFyVsNNKW5quV5MV+IGoJnBzLgXmG+AWQgIjzBaRBi/6v5VuOqH/8WVP/gPrv7RFbjye/+mfjmW37kcjh+G7X7IHqipq/7oopu5AOOfPDfSkRhIDCQGdhkG+vv70NPjN7ta29owbdoMxAUg0rHDMjDWE9M1oWtD14jG1jWja0f6aIo+Hrlund/sampqwrhxE2BmSEdiYGsYMDN3DelaUn9dW7rGpI+mDDz4TwysvnM0h0i5EwNDGNA1p2tviGOUAa2pDOZG4XKNLXUWKm4Py5zPZGZiDqNpQYLt+xMrlKFYjmSa8rg+HslMhxWt3F99teg6pCoxkBgYCQN+M6fGb8SMoIPbsAlxXg83JP+xFmxWvFmFAGbmBDx8HyoshN0DhmqVYsR8bkA6AHZQ/2Ch/IioWj7SYtcQJDSoZQ33t1Di5pZaqI1vdLGDNsA0nusQ3uhycfQBroIO4wYZODczYRKhXjas3YBb/3wT1q1Y7wG626a1g40TB6ofE8cpc/YBVpRTU5UYSAzsnAykWW8FA3rrc/16/8zURsbsOfPcf3TR0NgIbXBsRcrU5RHAgP7udQ3oPzTRNaFrQ6ela0XXjPSxkNWrVyFuqmmDYvLkqWhra0ddXT3M0r/bY/F3sDOPYWbuWtE1o2tH15DOR9eUri3pYyG9/zkBgxtWj8VQaYzEgLvWdM2NNRVm/pmcra00AUFcd0mVeF9chQkB16clGP94S7W3zauqKc6ChvAaoRIFsszXJrsoHlCY+nEgOmWxcSX3p40uR0iqRpuBGYe/HN0f+nQm8495azZk65z5GV6M6T7lzCymUrGaGsx88avQfepZeMwXfoDHf+dX2P+TX8bub34nphxyaGV4Zs94wSuysRa87WQoT+YsKDMOf1kWt897P5Z5Ovc70OOnfopjfwpdbOv4wxn05lJTo/cVzlPn0/XBM9G+oCvLYeZvQAFm0iX+Bs02heg0M8g28610wjBTvDQ+RHw3b1StfV/nUmx8KBVyON+QyjiOzx9D1T0PM68SlDawUW9ryYjjCWV/bXyJG25kDVJXJ+8BYgseg4xh489XShSmVKA20pbdusShZrXonN7pdLmLinLqB3nlM/BPnLwLeqRV6XwSA4mBxEB1BvTvhb6/T2/pKEIfTdN/YjFr1hzM230PxP/kIrULdiku9Heva0DXgq4JXRu6RnSt6JqRPRaisZYvXw69faPx9O+2Ni0mTZqMqVOnQ2+aJZmReJhWnQNdI7pWdM3o2tE1pGtJ15SuLdljIhvXY/0lr0hvdo0J2bv2IHqTS9caeM1tLya0FjMzP7zWk1En4tAy2yHgUgxDDrkkzuFXckqXxTpfyZklxjgfWzgE2aGw3CdYiNpc0kZXzkXSRpGB1rl7oH2PvTNpmjYzG00bRUVf1Nvm75XFFJXmmbOx30c/h1kvPQrte3ahvnM8rLYWwqc86RnY/ZgTsfsb317skukrr70CrbPmQmNMeOzBmPHCV2S+qLTO2R27vfgIF6O4npuviy40T98N7bsvQPue+6Bjz73RMX9B5qutrYfi2+ft6WN4vm30a451rW1ZXK7o9s0taWa8SQt3rZnfODIjrgBK/Ee8tqkZ9R0dlE5KbKm3Uy9IQ4fHxLNGVKqYg+mqFEVJAB/rW1Q5XBSnVuJGl9s0pD6wIWx6MX7Q4ToHGuGNLjBGp+h3/2nQZQQ1lhljaWfFqHEQo39j3wDM6C8NoLG9iY5CMer0Te2egdrGOpRM2dmRcCqJgcRAYmBXZEDP+WVLl2DRwnvQs3Il+vv7+TuZwV2RinTOBQb0iyBdC7omdG3oGtG1UggZI7UEfSfYsmUPYu3atdi4caP7ZdcYDZ6G2ckZ0DWra0bXjq4hXUv89erYn9VgL3r/dQx6rz4FA6tuw47xP+KNPQ1pxG3PgK4lXVO6tnSNgdfath9l8xnNtMgCNmzorxpsMOJan+XrLq3CCFYUxoAehUkyr7kMWhtmEBFGsoYTuEOdzGnuXo+qm58BzO3wEKEmbXSJhSSjzsDA+vXYsLonk41r15SNWfRFvY8//JQFBWP315+AltnznLVx3Vos+9fFuP8Pv8DyKy5DiT8oyTHlqc/G/DedJLVM1i28C/f+8kcZNuP5r3AbZBlAZd5r3oKahkZqwOpbbsDiX5/vdFWD/X3YsHY1+ntWoH/1KqfrH1v5dPtuWMXFBP2Kkb6RMZIN4cuBFZeLv0N9f/YOd7huY3+j8hYPmPqY+Xgz38559RvxmM99H4/5/Pdx4DnfxYGfkXwHB36WLeXR53wbj/7Md5z96LO/ha5TzlAan9prm6/9ZFCYRugjhyFMJV88KbCwjtIP1NoA0zkOxo80MoM5UU1FhapizKi4B5XAcmmb1OaAmpoa9K7ppa5YNqHof3vc7aDZqK2rzTIoNrhTkxhIDCQGdkkG9HEeLQQXLbwb+p9a439wkVr/H33sajzoGtC1oGtC18b2vim0WbGaPx9qPkuW3I8HHlicJHGw2WtA14quGV07uoa293Ws703qvexYrPvzs7H2wkN2KEnz2Tn/PnQt6ZrStbU9r++4lhrUGs+t0zib2FLlapU1uCYsX5cZrGLNWVg70oXsIF5my0FM/aVmPinCy0AawiRUYx+qmmLa6CIRqYw+A3d+63O48oQjM7nlc5/IBu254ZoML8Zc8943ZTFRmfy056B9r25n9vE31def9nbc/tWzcc+Pv4VbP/8J3HTWB6HNKAVMPvjpqOsYL7VMFv/u51h1k39Lq7axCdrYigHTD30x2sLHDAfWr8Od3/lidLn2wUsudHO96sTXuPbKE47CIOPMjJtea3DlW4/CVRR3HmqdHIk1d9zi+lerzMzBZmpLMFPrxUytc0MbQdKyloZ7jRSMqaGUuMOkeD2IiJkRGxxEiaLNJifsQ5fqTQj7xSDlYKQQNhWllD3ABjcMYqB/IwY3+jYGDvQPOLzETa5BfWF9dFRJaFYTNsyGOlu5yTV5r6mud2mwhLVL843SGD37cXNQQx7qGmr5W4c+F1sT5u+MVCUGEgOJgcRAYiAxkBjwDKQ6Mfoet9MAABAASURBVJAYSAwkBjbDQNzo6u/rg1lYdbm1ZkVHLguLSEmvHYRwjxvMK4VaiEHppHmHNElIGJps0emDXK0oDYMqmZUzbXQhHTsTAx177pNN995f/xS9Sx7IbCmrbr4eD/79T1LBXQ+M2/cAr1fUd377i4hvlXV0PQpTn3kYmqZMxcyXvDqLXHTBD7B+8aLMHk4pcSPJbz7ZcCHVcd2BQzwxBx8PBb/ym0UfYGZYdf1VPNcL8cBf/4AHL/kj9T/hwb/9me1FbP+EJX+7EEv/+Rfa1C/5E/WL2RE88jw0hinxqeJb1eW9ZFFYNM2e+1bikrMucnLLhTf5nOy04u6H8Pez/+rkjktu87hq+likwfgnKGhorsfEeRMwYe5EygRMXjAFc588D90v2Q91jbUubN2KdVhxz3LEbspTy82tlvGtxMy90bV+zXroqKurU5MkMZAYSAwkBkbMQApMDCQGEgOJgcRAYiAxANTV+vXXhv5+1FgNwDWoExQOoy5ho2Lwf6RHMSpas/mNKRquOARKCQUUMBBw3gwHj9zQ+tP5ifqS+6LG2XpXqhMDOwMDzYXv9lp907VVp7zmjlszvPgl8BlIpXfJYiw673vUfNntJUdgzpFvRl0LN0sIrfzflXjgz7+htvliNbyNJJsPLY9wd7WHtJElLbbgzY3CoRs2+tRN+kP//Sfu+t5Xcdf3v4K7v/81tpTvfZntVyhfxt0/+Lrzq737h1/Dfb8+z2VUX6dssvK76yjMo/xhQktPGACajwTZIR8NTZqNSkGV6SRi3NLjJr3v0zyuGfu8YD90v3A/7P38fbHgOXtj+qN2Q219LUqDJfSt6cPdf78dGGQKjm8wKkDrBP69cRI6t5raWqxd49/4qqtPG12OoFRtGwZSlsRAYiAxkBhIDCQGEgOJgcTALsJAbXhpYN369dDbXVprxVO3sA5zNpdyrg2VW99JD3hoUOyCcHBJh/INMO8wNVnHaHhAPjPWLL6zcInivHCF7pVUJwZ2BgZq2zvdNHWTjdv/cZj27BcMkZZZ81yMqvoOHy+9UpZc/AesuPo/Dq7vGIfxj36c0/WdWndVfGTROYapNBcMDsLM3WnDRG0aNhu+rxl9FDO2TKOHQVBp+VJ+Wwvzsf7Glw03v9hX3socqDi8v8R+gOJRdhBhEaScEule6PCdMQT3AXAJGYZwuM3CYJtxk4241Qgw1NQazAwP3rwE151/NVYtWQ0YeKgqsQXqmuthNSUH1zc2YN3atQ6vrU0bXY6IVCUGEgOJgcRAYiAxkBhIDCQGEgOJgS1goD68NLB27RrU1ta6tVbsXuLulAkpETFKKBkuu4AXVHkopt5sWYxSKJmZKXLKkPgVrluDC3ZZhEu8T3CNqiSjxkBKPEoMmBnmvubNVWXGYS8d8ah3fffL2LiGGyeFHnf/9NvoW7a0gGxaNeNNtTVvdFVJa8ZcZbieHHxclO8YVWwglXWoMMrzmeW2UuZWRbeiySmwuEdIDueIUkpynzT5gYh7CzwKIxKUZcaNLU2G3v51/bjljzc6ue2iW1EaGHTnqi+yv+/qe7GxbyOjQlFnGP/QZg7WfNwC9c0NWBPe6Gps9P+pgHxJEgOJgcRAYiAxkBhIDCQGEgOJgcTAKDLwiErd0ODXUvq0jN7oQlhz6SRNVRUxK/cYjFFc+LHOS45Jy3GvKVriLdWKyhENIZEn39ryVsRrvJnqxMDOx8BgXy82J6UN/Zs8sfqODtTUN5TFNGziLbCywGhwk6ZU4oZM8cvWo2/YNt6osfWBJebymq9lSmRV+tr33g9Tn/5cTH3GczGF7ZRDDnXt1Gc8D1MOeQ4yjPjkpz0HEx//FKbRpln+OCgfne7KwgAWh8bWGe6B5TXtLsU5BiQ0eiAB8WGD4hGScTZuIyu6elf1YemtD1KW4sGb7sdDdzzEyZagN75m7D8zhhVaZfDm4ACgEVs6WtHTs5K6QRtd7qGMdCQGEgOJgcRAYiAxkBhIDGw/BtLIiYHEwM7EgNZQWktpzj09Pairq5eaSYmaW4lpAUZdxbgC09pQehQXQ0PxbEIptwJY1pisLEyKQ4RyfchCyK9BI06AXo8BNdRTSQzsdAwMclfjP8e+HJuT277y6WHPzerqsPsxb0NNxVs/u73o1Wids/uw/YY4zGBWA6upGeIaHrDgiq03zfK3m4SYGcwksspl0hOehrlHvcn9r5G7v+54zHvtW7D7a4/D3COOJXYc5h35Jsw9krpiKDNf9Co+EcB8XjDs4R8S7iHlxrZhIhnHArrNWGVRAVQCqRkuJQAKl6iz4tzHFAEzggxhDR33X7sIVltDHJi81xQ0tBY2JRmnGMUaqxrF8e+gvrGeG12rMMBrpLm5CQ0NhT7qkCQxkBhIDCQGEgM7EgNpLomBxEBiIDGQGNjBGNAmV0tzMwYHB7m26kEN11nFNxTMDPpTnLY2tSR0FGGajLQyyGEOER7Wdc5mxdRggBfEQ0ES2uxjZmChEYtFxbU1rk5VYmAnYWCwd52baU1NLeo6xjt9a6vZLz0SrfP2cN17ly3B0ksvcnpNYxPmHX0itmjjig8Ad1O7DA+vMjMmKPHGVcu9KW5Ls2S2R0GbogcOuDk2sFGBKHFzh6bTWcHM3+JWWwv3RpjrzPgS+zodVQ45YgBbDc4ooWwKhQiLAJdbihOB7CddKlt3SmwBARJkh5nBFM5xXB7TzOU2931cKxYulwH9z4ozHjXD6a5iHNgXMGzs3QCeIEr8e2iZ0Ioa8nL/4sWubWtrg5mCkY7EQGJgJ2MgTTcxkBhIDCQGEgOJgcRAYmBsGTAztLa2uLWUW1PV1qCmthZcVCEebt0mQ+s4tUEMFrTY0GaJlm+5HqXiuqrK/OZ6c1nItR0DXDHWXszU0lRxQU5RVSYK86vgMjgZiYGxZaCmrm7EA/YtuT+L7dirK9OLSsvM2Zhw0JOcNE6aXHRlette3Zj23Jc4Wzfpwh99E4vO+y429KxwWNvue2LWy45y+uYqba4opqauHiPbHOOWWHZjqmc14c3PGM1NXjNvS3d3P5X7//Rr3PrFMymfxK1fOgu3fflTTqTf+mXisr9ylvPd+oUzcPf3vsJeeR6mpz1c0UNE8/TPGA6v966qB+vhRI9i2AwpGkeSO9iBRbZGUeKSFCZgERxO0QctvupegI7SYAlT9pmB2obC9cIQzhLrV6yHhS+tb5nYioaGRiy8524Y/7S2tqK2lg9mPKKOdDKJgcRAYiAxkBhIDCQGEgOJgcRAYmCbM6C1U1trG5dpJbem0trKzIaOI0gSPMa1lwo7BgTe5GKQBcXDaEhcAPVYuLzzqnNKzRDEHLGF65wFQoemKX/a6BIbScacgf6HlmRjts7bEw3jJmb2ppS1ixdm7t1e/GrUNrdmtpSGznHY690fwYITP+Bk0pOfIbhMahqbMP/ot0IfXZRj+eV/w/IrLkN/z0rc85NvC3Iy/XkvRfuC6ptpLiBUG9euBmpqoO/60gZbgDfRGMws88fNrAwIipmVxZmZ8+jGlbL+voVYfuVllMux4qrL2Uq/zOkrrvq3a5dfeTlWXE2dsvrWG9itlOUM6YgNV8zFWlV3iaiEXhVKnBcdLAQggau9hnDQYgkGn4PKA/j55A6D/7Ny0QqsW7YWZoa6xlpM656G7DDA+GfDun70r+1nLqB1Yhum7DkNS5Yswfr166FXbtvTW11IR2IgMZAYSAwkBhIDiYHEQGIgMZAY2BQDZob29nY0tzSjt7eXa6oH/PdzlS/2YGb+jYiQzGBe09IuqAJKXKGZGVhkBlFQUCua8rii0/eR3wS7SpiMXOI000ZXzknSxpCBvqUPon/FQ27EmoZG7H/mV7H3u07Dgrefksm815/g/MXqgQt/g95lDzqoZdZc7PeJz2O3l7waU595GHY/5kR0ffAsNE70b3Hpi+qX/u0vLrZYzXn10WieMctB/SuX4+5zv+F0Vcv+ebHbMJJudXXYnRtimp/s4WTtwrucq8S7bv5x78Y+7/sE9nzbyVhAcS3PqaFznIupVpm5uzS4+Cjg3anNL0kAuXvNm5i4mY9VY+Z1xeSarOri8ymy5B80pepx/oklp4Qx7MKhqQBU4Q9pFDlcGHXvYC0gCk25JFR9kc9rSmhmqJFC4dm74RURBTzuvcpvcFqNYdq+M1FTW0OURUF8eII57r1yEYyw3vza85l7Y8qCabhj4W2oqalB57hOPqALb4KxayqJgcRAYiAxkBhIDCQGEgOJgUcsA+nEEgNbwUAd18CdHR1cXhluvOF61HOtLozA0GyFNZ5bx5VFeKcZW7dmKzqJyQyN1ExCrJaZHlOQQIMRKMcJuCK/U1ylIbksdHqqEgNjzsCi87/vN3A4cm1zM8btfxAmPOaJmYzb79H0lJeB9WuxkBtT2sSSp2nSVG50HYl5rzseUw45FE1TZwhGaWAAd//om9xMW+bsWI0/4HGYesjzoomFP/4WNqzqyWwpd//g69i4epVUNM+cjdmver3Th6vu/fm52Lh2DYx3nRk3Vbr3x8THHowJlIkHPgGSyi+8Hy4XYDDzAh7anDILNttoa2+H5DHCl/Jb22PldcnljbtInCpgGOaQQyJ3SRU4tGtlRY8D5CCgeTnbVQQQxQFuqgr1VnmtuQzyhErsYqYKrjfcoRGBh25fhr7VvcxTQmNHIybvHd7qYjjYR+MvvWUJVty9HDV1htq6WszYbzfct3gR+kp9aGpqwsSJE9NHGJGOxEBiIDGQGEgMJAYSA4mBxEBiIDEwlIHa2lqumSagmWvzNatXY9HCe1BfX8/llpUFO0uLuIAa/B82AVGjdZy+Nkc6RSYbX8oMQhbErVbB5Z0TgiyKlT/3gabWf3SGQiBormGXtNHlmEjV9mBg6T/+gls/93GsueMWt1FUOYfBjRsrIWfr43rXf/id6LnhGmhDy4Gh0gXfc/3VuPnsD+PBi/8Y0LyZc9SbgBp/2S//77+w7LK/5c6g9S9fioXnfy9YwLRnPB9t8/fK7Epl/X0LcePp78eKa69w3/GlOWkeLo5jSR/cOOjM4Svejdzs8bevjzIzr7BWjuiTHqPpGmFRLvXiw4Y9zNjKdDqrqkV9vEPPsWiFbnTkmpnpeQM2Ac99BGCsijngEPhDjkHGUwY3DniMHXwumZprCYuvWQwQLA0MYso+U1A8zNiBwO0X3YI7Lr4NvT3rMXHWJExdMANXXX0F/8pruNnV6F7D1RteDE0lMZAYSAwkBoYykJDEQGIgMZAYSAwkBnZBBrTJpY8sNjU1w2oM//n35airb+BGV0NchhZYMWhdhnDobS6JM+lyratKeViGG/SnRL+WgWxYZAFmqHIIlF9Cd2jMhNOuKBH2K/4KZzITA2PFgL5L6vqPvAtXHPcqXP7aw8vk2ve9ZdhprOPm0k1nfhD/ffMrccPH3uu+hP2Gj78XV55wBG4661Ros6ta52ve/cZsjFu/cDou/WvjAAAQAElEQVSGOx685MIs7vLXv9Btxg0XK3zdortxy2c+iqve9lr8++gX4d+ve0FZf22eKa5cwl3qQN2oUYjndz0fLCV30xchdYk3sfQtEY2izbLYpzJvxF1bcjVcH68WaqHBLEtSwOVWjgBJFcSTypqBvo34x2cvwaWU/11wTYa7fT9n+V73/+8+XPblS3H5V/+J6y+41nmyqjD+Q3csw/8uuBpXn3sF1ty3BiuXrcR1116DlpYWjBs3zn1nV9rsyphLyogZSIGJgcRAYiAxkBhIDCQGEgOJgUceA1obNTU1+bVSSzOuu+ZqrFu3Do2NTTDjQo4F4fAq12csggymZohYxBVnRbffEnNpK3HFKjS20p0o0HxGcwCrIUHEWAizoIZqKomBnZaBwf4+rL7tRjx0+d+w+tYbsXHN6p3oXLK7tGLOxFkEmlnY7zGYmSAnZsR1B9OiynokJfRnY8ZqRF1CHJvqXUoA5PTJ8v0mYg5iyyI1NFSlSXI1nEoA2IRiFuKCPWzDOEVmeWjrLboNazagZrAGCxfegztuv52bXc2YNHkyOjo60scYhyUzORIDiYHEQGIgMZAYSAwkBhIDiYFdgQF9/5bWRpMnT3JrpTvvuJ1rp4Vo0Hdz1dYNocCtt7jW0hJQzlK+WpVZJhaDqqEuUZnDGUrtFFeZq1UJVxe/3oy4WqGKCEJIsWmjK/AxGk3KmRgYOQP+Bs3ftOId6u/iQgofIyCPA4aEKWAEwhFclB4EThlS+fGy/N6siFIWOljkUC4h0r0Ehzc2Uce40MYkwSx21MNUUoa5SRofpZLco7j6hgbU1dbjphtvyDa7xo8bh8nc8Kqv8pnzvHfSEgOJgcRAYiAxkBhIDCQGEgOJgcTAyBjY2aK0Fpo0aSK0NmptacWdt9+OG2+4Adr8auAaiitNV4rnla22wjpNtpkVQ5wut4QLNGfDKSGOjfMhHkavRSNsnclUlBe33CPkhyLGQpMl70fDrY0Vmza6xEaSxMCYM5DdmWFkf4Oa6U2t4KMenGy4ZRNgGjAzijSwNYz40F0PP0ZMJ4jpqqTweaMvxg8N9HFgoHINH1fsWYiiahZyILbF2HLdGGNmZaARUyFLhQcjYGbQ0djUxAd2PR/c17tXcfUFi3qgz5gxA52dnfTVZbGKT5IYSAwkBhIDiYHEQGIgMbDNGEiJEgOJgR2EATNza5/x48djJtdCaptbmnHtNVfhhhuup68ejU3NYbZcS7HIUGMwqWXi1l9aBJahyCO51oM7pHhROKfhULhIZUF25D5BGtNclMl0kmvOLKwA5ZGkjS7PTKoTA2PMgG6/4pC66b1tVu4zky0BzHyrN7r0gAAP6WxGVkJ/NRJ1UhtzyR4qfkzhilWbS5i3CylxfrnHa3JIgpWpmQJQrTo+cfAwBbDNilErUaoUq4xlnJlHG7nZpc+ZL1y4EBf/9SKsWbsGra0tmD59GrThNXHiBDQzpqbGqmROUGIgMZAYSAwkBkaDgZQzMZAYSAwkBhIDo89A/B4urXlmzpyBqVOnoIVrobVr1uDiv1zkP67Y2MhNrqawoipfE3FZxe0kX7vZBrcxWsLGwaqcTcUoRRzOMHB5NuRNMfAwCgdRHcRgQdPIUv26kVZ0CAxRyksPQCVtdCEdiYGxZaD6xlTxTnW3Z5gUd7f93az7FdX68j4OsZtq8pw+Rz5eSD9MZ/ZzARbGrwyzcoDh5YCsACrUqa6SIxO5ZMQWyDUyABRsFA6LuBF0aUsRIcDi8DxDfUMDmvgbinXr1+OvF/0JV115Bfp6e9HW1oopU6Zg7ry5mDVrNqZNm4YJ/C1HW1sb9PaXXt3VK7z6B0L/I4mZEiMdiYHEwGgykHInBhIDiYHEQGIgMZAYSAxslgEzg9YpEq1ZGhrq3RpG/4ui1jTTpk7F7NmzMG/uXLfmaW1tRX9fn1sL/eWiP7svnm9qbnHfywUeJYpbVJkUL1Il4Fge8bVfaXk91sIkcB2IZgmpq8iOPtmUsrTyh84uD/0qgn1cRWc5KVq2mvlPL9XQTiUxkBgYQwbMqt+YmkLlJhR4g5v5eN244GFmYKHmS8S9NVxtwVFiX3/zAxGjlqsoP+iIg5W8J5reGlqX+9WJOcrCoh1bOoOaP8jUz+PGeRrVskLAiOfx9BpFpXwCAG0Dzxn+qK2rQwsf5M3Nrbh/8WL88Q+/w2X//Afuu3cRSoMl95bXhAnjMW36NMyZPRu7z5uHPffYAwsW7Im9994Le++1F7r22QddXdWlu6urzFdpd4V+3YW4ot4V/Gq7GROlK+DdXV2QdAW7su1mn66Cr7vC7gq+7gJe1LuCX203Y6J0Bbw7YF3Brmy76e8q+Lor7K7g6y7gRb0r+NV2MyZKV8C7A9YV7Mq2m/6ugq+7wu4Kvu4CXtS7gl9tN2OidAW8O2Bdwa5su+nvKvi6K+yu4Osu4EW9K/jVdjMmSlfAuwPWFezKtpv+roKvu8LuCr7uAl7Uu4JfbTdjonQFvDtgXcGubLvp7yr4uivsruDrLuBFvSv41XYzJkpXwLsD1hXsyrab/q6Cr7vC7gq+7gJe1LuCX203Y6J0Bbw7YF3Brmy76e8q+Lor7K7g6y7gRb0r+NV2MyZKV8C7A9YV7Mq2m/6ugq+7wu4Kvu4CXtS7gl9tN2OidAW8O2Bdwa5su+nvKvi6K+yu4Osu4EW9K/jVdjMmSlfAuwPWFezKtpv+roKvu8LuCr7uAl7Uu4JfbTdjonQFvDtgXcGubLvp7yr4uivsruDrLuBFvSv41XYzJkpXwLsD1hXsyrab/q6Cr7vC7gq+7gJe1LuCX203Y6J0Bbw7YF3Brmy76e8q+Lor7K7g6y7gRb0r+NV2MyZKV8C7A9YV7Mq2m/6ugq+7wu4Kvu4CXtS7gl9tN2OidAW8O2Bdwa5su+nvKvi6K+yu4Osu4EW9K/jVdjMmSlfAuwPWFezKtpv+roKvu8LuCr7uAl7Uu4JfbTdjonQFvDtgXcGubLvp7yr4uivsruDrLuBFvSv41XYzJkpXwLsD1hXsyrab/q6Cr7vC7gq+7gJe1LuCX203Y6J0Bbw7YF3Brmy76e8q+Lor7K7g6y7gRb0r+NV2MyZKV8C7A9YV7Mq2m/6ugq+7wu4Kvu4CXtS7gl9tN2OidAW8O2Bdwa5su+nvKvi6K+yu4Osu4EW9K/jVdjMmSlfAuwPWFezKtpv+roKvu8LuCr7uAl7Uu4JfbTdjonQFvDtgXcGubLvp7yr4uivsruDrLuBFvSv41XYzJkpXwLsD1hXsIS3XJm6dwrWK1ix77rEn5rlf4O/m1jQTJk5AS0sLF0Mlt+b51z8v5Rro91jMtVBTczN9rdl/1GVcN0kYnBVzmq/L37iCi2aF4mEEJBlm0kpE4QRlR4kW12pqqIFrN7h4GRJzplGV+PFjMEEWdWHjCxfHstNGl6cj1Y8MBnbOs+DNGCdu5m7faPqWfm2AFV2E3A3vA7ak9vmVy+UsdPWeAlBUCwNKLbq8HnqzKfcT0NMoPotk+g6sI0iVRXOCO6tCUAgp29ACj4BTKy9KUsWn/oWsAOP05YvNLa1oaW3DypUrccV//4tf/fJn+Ive9Lriv7j1lpuxaNFCLF36IHp6VqJ3fS/6+JuPwdIgz6gE4x9UOTSWYPklRVt4lIhHW7GVumKiRF+0i/HRp1Z+tfJLirbwKBGPtmIrdcVEib5oF+OjT638auWXFG3hUSIebcVW6oqJEn3RLsZHn1r51covKdrCo0Q82oqt1BUTJfqiXYyPPrXyq5VfUrSFR4l4tBVbqSsmSvRFuxgffWrlVyu/pGgLjxLxaCu2UldMlOiLdjE++tTKr1Z+SdEWHiXi0VZspa6YKNEX7WJ89KmVX638kqItPErEo63YSl0xUaIv2sX46FMrv1r5JUVbeJSIR1uxlbpiokRftIvx0adWfrXyS4q28CgRj7ZiK3XFRIm+aBfjo0+t/GrllxRt4VEiHm3FVuqKiRJ90S7GR59a+dXKLynawqNEPNqKrdQVEyX6ol2Mjz618quVX1K0hUeJeLQVW6krJkr0RbsYH31q5Vcrv6RoC48S8WgrtlJXTJToi3YxPvrUyq9WfknRFh4l4tFWbKWumCjRF+1ifPSplV+t/JKiLTxKxKOt2EpdMVGiL9rF+OhTK79a+SVFW3iUiEdbsZW6YqJEX7SL8dGnVn618kuKtvAoEY+2Yit1xUSJvmgX46NPrfxq5ZcUbeFRIh5txVbqiokSfdEuxkefWvnVyi8p2sKjRDzaiq3UFRMl+qJdjI8+tfKrlV9StIVHiXi0FVupKyZK9EW7GB99auVXK7+kaAuPEvFoK7ZSV0yU6It2MT761MqvVn5J0RYeJeLRVmylrpgo0RftYnz0qZVfrfySoi08SsSjrdhKXTFRoi/axfjoUyu/WvklRVt4lIhHW7GVumKiRF+0i/HRp9b5+Qt7vaXV29vr1i7LuIa5d9Eit6a5imsbrXF++YufuTXPypU9/OV+G1q4FmpoaAS4NkJ2lKhRWKi44lXWijMHbaLippVbLVWGCPcYM1FRoig0s+K9xc82CpEgC88U1yuuPzU9qGJw2uhy1KQqMbAdGdDNWDG8NqEixPuU92t+M2e+Kv1in023zMhippxgbj5GaLOg+kGPi/XxMcZBfIhFW218yEj3wr5gPxZny3SKqghSFy6hWlYYUuIYxhySzGfUJK4JCnW4CZQYDScIRyEiIGx4AsLr6+rR2NSM9vYOtLV3YuPGAdz/wAO45eabcSX/Ubj075fgoj//Cb/73a/x21//Ej87/6e44Lyf4PzzfuzaC6hXk/Ppl1wQ/OfTviDole359EkuCP7zaV8Q9Z/m45z/059kY57PmPMLvgsYX7TPp/88ygXCneR5hBXlfMZJLmCc5HzaF0S9MMZojX/eT39Uxqfs6uP/mHGeg/M5x+L5XsD5yj6frdPpj3k8Pvz5K+58xl8Q+sqOuvoW9WL+ok8xsov+mMfjaXxxVE3E0/mJ/+zeFh8XhGtR105RL15fRZ9iZBf9MY/H0/UnjqqJeDo/XX/p+gv3nK6HC4Kue6eoF++vok8xsov+mMfj6f4TR9VEPJ2f7r9Ruv/4syp/hivye0G4tmO7o/F/fuFa0L1zQZjvaP38eT7Hk1zAcfTz/fm0L6AuGevx3ZiF8WVXk/M3EfOzC36K33Ct8rvf/AoX8Rf3l/79724tozXNA1zbaI3TzrVOe0cHmrn20adctBbiqigrZXaZoZAAlKR7Ma64tFbzVqxLMLNolLUR9m2JPgmQRWcKeJQZ8H2I+S70Vy9urczgtNFVnZ+EJgbGiIHN3KmcBW9nvxMlnTctCzVBm+/rAodUzMiiTSFlcHtDQ2KKgAt2gMaWJcP3i5YQuAeQEAnckWsAdRUKKg9hFBZFlXnNhJZB3uDkjdFlD1fFShzuw3xtAHHWGPagX9+/VV/f4B7+rW1tbvOro3M8uhRVtgAAEABJREFUOseNx7hxEzBu/ASMHz/RyTi2XiYQn0hRS1EcpZOiPmrVP2+ZTzkpHZ3jUFU6crxTcbIpnYxv7+hEFPWNulpnu3/AGMONuw7plA7q7h826r7tcOfWRjxKe9BjK1y68kqXtPMfRrVR2jmXtrYObhB6cXbII1z9FdteiJEtX1HaOa8MZ//Mjnror/ztxGJf2U4PmGznL9jK2x7zC5coX0EyvzD6MzvqEef5thNzYxLTeE4PmGznL9hp/A5ea53ZNSI+HGfkL7bt8e9HGLnL7KhHPPFPLjuQ8UY+nE6e1Kbrr9PzU+BD11vxepItroqS+eN1Fq9H5nG+iJPvdmKxr/h2esBkO3/B1njthXyyXR/lDJL5ZbNvZkc94ml8//crPiji23FJntTKbpcuiX7q7dX4p199JJlfWEW880U88Z/45/Wha0ai601tvKdlt8sv4TUjW772dP1BPGRCbhxvoc34kR24i7GRQ9nt8efPENfO+9HlUR+Ks9kqVnh70NVKhMdWelGET5+hj/ft5ubazr8z5evgz925rn9fcin7eZtzcbZa9WHbyVb9Xcuf3aUrppp08ud8J1xrZC3XEH7tMB7jqA8RrkfGOdH6Y6Jbl7j1yYSJPl5rFObVeO3korW1Dfr+La1xampruRTyb1a5dRHXPwTKizBJAXWxsrn+QjAsKGYmT0G87esIB4v9WSLINuDU8lIN09qXEVqAOnd5FnqgaTi38wM1ApMkBhIDY8VA5U1pZQO7HWgiZh53tnSK0+kDvA9VDrPhfT5c40sYx1gWl82Mtg+oqBUriA9EPTmkblJ8ntirPJSoCiXHfXy05ZLAzQplR9mGljzqKpE+RHyWDFYcIZYMcorOm2Jm5SPSll/xJsVJsARQWEIfaS6AVa7nGmFX2J8FEmeD/S0TFA8LhmKjHjpa6KEIU1UQo0/FQ4YyHTqUUC19dMbaqAuNYlQkilYrIVS9FJwFFWUpyxyA8wkrCgqHcJnFCUgXJpFfEvXQRkimG8MprKIj5pBdKQzLinwyFC9dIl2YRLYk6qGNkMw0vmPBV5GYyKHsSvGRvpZPmuKlS6QLk8iWRD20EZKZ+Hcs+CoSEzmUXSk+Eq6RT4ripUukC5PIlkQ9tBGSmfh3LPgqEhM5lF0pPtLX8klTvHSJdGES2ZKohzZCMhP/jgVfRWIih7IrxUf6Wj5pipcukS5MIlsS9dBGSGbi37Hgq0hM5FB2pfhIX8snTfHSJdKFSWRLoh7aCMlM/DsWfBWJiRzKrhQf6Wv5pCleukS6MIlsSdRDGyGZ24x/l4xV5fiEXCkMasVBDbSMAnfE7mqNiNFjWSuNhiul4KER1zxyl2irLQohBqt2YjTMaaVMc6aqkqqi+Ei4yKiDuziUaLrxZXD9FX7+pxfs4iVXnOYr+EPdqA0ZllgsCpEgrHeKOECPGx/ZQYQ6axa5abgyZG3mUPiQIRMIAHPkw9KADp8pWnoZAz4LPDFwluuXBSE7HE4rn7aCSmmji5ykkhgYQwb8jVd9wBLM5Je3pKpgOzNU3ifDLMbL4qMgv8M9MKTmAzN2ZywLwBRxE40qyo8c8Zqvy2MKlksIVEwL2RG6535NJoBUq+LqHEIMJqtMrAqGPFEeayDMCoCvkR+cN4cv4N6Kcb71NQpR4BFRqizsJ0BCKy8BiPMKZu73mlXkzkyT31VSnJhzmtNj5f+ZCFa5y4NDxmcQi3eCGQuGs2RH8f5o+dYYhezg2TvdXD20inhsyyLUudJRtIt6WcfcUApZw4UOOX0FR1Hnyo65jbITRfVDKeQpdpMdJY3vmajKj8irdBTtou7TDKmVQuBwoYl/sYPql7LIqySuaBd1VD+UQp7hQhP/YgeJf1Q5dPFUXjhFu6hX6S5IKdQOF5quP7GDdP2hyqGLp/LCKdpFvUp3QUqhdrjQdP2JHQx7/UV+EI8ikdRZnEetFyvLFX/+zVGPGHt5UU2j2CtChM2KhgNQDEXFUYh2nmy0Yh55YmBozSX1V4vJH6XMIMg8grywZiFatbhsqlyMKokPzTTm0+ZRZsstTG1BlMaZQ3xlPV2IKnPnIy2KRcVvz2WmV1zabBCFyigxi/cLcVJmGtSvJIerpBgrCRsWLuNYw8V5lIEs6Y0upCMx8P/svc+urdt23dWaFAk5kZ3Ill2ICH+KgVQdSiCqDmWgEB4BJIQFRRAFgpQKRMoLADXyDOEdAkZAMWDJEhZSqNuetF/vo49vfN+ae997bc7Jse/sZ7TeW2+tj/HNNfZac6+1zrn2j30D/SX49amnzi+k8hVaQ13tpXVbzpnO3af+5DaTfUixps+xrz375p3kqxslp2UJ5EzGI66FCCT06xi0DCsB3YVm6dFYdj5+yAP85WL1P9vKVtvVdi5ayZmNXXwnK6qOiMCLTBnxoC0hBJyVkv2dFSaCNpXSICOksin0XJ59EU+etpe7PDOysxfgmRRMjaUNJTDO52+OEX8PbwMxKj7a/DnQ55ercV0uWcV6yiJcCplO1eHrEfxxzZSXR70AU/args6rcxSHu+r1mtKW6sp0KvZ5vr7E5/5VnxtKOGBRL8CUGVXQeXWO4nBX/Xz+8fXl3EeuIxkG6FQ9vh7x+fxT3Y0SDljUCzBlRhV0Xp2jONxVP59/fH4595HrSIYBOlWPr0d8Pv9Ud6OEAxb1AkyZUQWdV+coDnfVz+cfn1/OfeQ6kmGATtXj6xGfzz8uxKTcUZWqKI3+vhPe9we7PtecaWebU1OSTVkVDiS7qyrC+zDFUEe0rP4NTSvk27YIjEiTHdYQwZmGBI/qTPIzi1LheoYRKkEuIJ3n1v62sa7XR6e4qqgOE6Ckcgy0wM85RXTf87gAl3vbGcXacVD+VOz153XTVXuOR+qKYxB6f1T25dRoWNceWMSUU6/z8/z6EFK//4uubP6szw18buDHvYH9X1flC5Qn1xctKbD7zQMdzCz850O/KdRszhKo5p7ON43Lyd4YyZe02aEedNv1jhMja7QcJTD9VEb6ZeGC5cQ4uiUqZ3AnMXXEMXhzcofZUIOMgGoQ+6HVll59sdJIV7dYDoelYC9Mh7OkXZaHxflge0Mwm5vX1bSzu9xlxD53GFX3IVX0mMpiCChBHaQtn4RGv9GC8Up7hTnsFcx6LU2pWvFKZS4lC+a4DYXpEThI/NlSwStzhqyKh5a/AEu9ak8tMZ97/Y3F3XedQlaYHtG64rw08UrnahymgHOt69xXOAuN2mCqnc7KTuBUANcjWlcmZg9PuVRL5b2ScVTxqqzStOPzfG6A6zjvx7mlhsL0CBwkPseo4JU5Q1bFQ/vc/6tu5bqHvqUlfr7+6ga4jbkn7sf1WURWmB7RuuLMHm73Ui2V90rGUcWrskrTDj772+ms8p3c6F63wEHgc5wKXrUD1i4e2uf5Ly4lmOrwa33unxvgPs77cX02kRWmR7SuOLOHz7JLtVTeKxlHFa/KKk07eHo7nVW+kxvd6xY4CHyOU8GrdsDaxUP7C/p8PtB8xK+qpFc6Q1b9YT7+ekK+L3aeooISDpTuXrl5R6WqwpUrHbT6Z8IH6FNzVh6dHDGam6XpJ0zf1dGvOzlGdeP6Gs6AkStBguKV4qZP7g4evIItNLlJmc/E+8XPPeWwo0hP1wfbZ7W68ls9e9HXCIWvLPdJtD8HcsZMecg3avmk3kPeHaS2jVrNN9PnF13fvJqfz/h//vD/Fvj5pj9Tnxv43g3wRfsNP28wuPxiy95f5TVsd49fwndTz/YIO16yL+3VRr4xX+Qsy7Qtn3rxUVKzGOC9NaPQmqiEF0LhOKD7hCraKPpMfs77ObH6nGE7015CSvrkaP0XV0ZoG7zgZvePn+3BzIauqRSanElJV+eqMkp2xKtWHU7jpsnxedKXmVhZzmzKWl415aA1Un2lMr3E+Uuo+1gsK26SjpiWl3PIGby6mUG58TRZYpjKxzL89rFhKpGaJWY0gQC6f7LuO98nXjkF3anjOGTw9J05x2dRX5AADkKznqz7zrGzhr/WeU6NnNXMxfgMczmdFT4Mjq8KJ4OUrCfrvnPsrOGf5zt3qsDqcLg2nveDa3VQX033fLc4J+u+86nz5+e1122kgw1eu0dRdc3g7FcFGqgmU121WDudVTH8eb6yA2/w9L18JRy8AhYcwJUZrWjtzG20wut3TXfGa+ZQ8IpLdWqk5GEKZ78qnAxSsp6s+86xs4Y/z1dOxRs8fS9fCQevgAUHcGVGK1o7cxut8Ppd053xmjkUvOJSnRopeZjC2a8KJ4OUrCfrvnPsrOHP85VT8QZP38tXwsErYMEBXJnRitbO3EYrvH7XdGe8Zg4Fr7hUp0ZKHqZw9qvCySAl68m67xw7a/jzfOVUvMHT9/KVcPAKWHAAV2a0orUzY2hPvMJwnaqKZg4HT9+ZczwW9QUJ4CA068m67xw7a/hrnefUyFnNXIz7dTmdFT4Mjq8KJ4OUrCfrvnPsrOGf5zt3qsDqcLg2nveDa3VQX033fLc4J+u+86nz5+e1122kgw1eu0dRdc3g7FcFGqgmU121WDudVTH8eb6yA2/w9L18JRy8AhYcwBfGqna8Jdb3mGVI8LKTsgSUoDK+/aWhh+65J6e/gUOU8dn4OrgS0bNCesFBd1Keb1mEUwF84xXmhZRzIe/+aJxzRjekEiTI85Jroo7GQ6NixIGCavkevUll9hR5JOa3R7N85zzWandB58cpHr3FIhbzybqCDlzK99j9zGsfr4+ukCF+VlYqZ31+0cUtfPC5gZ/EDfAlqnxtdq0vVGn39l1Xws6/VeEdJfznXjXPWezNX3fpbXrlWfp2rBn+N968qTDYu2CD5aTg5ej1VkrXQFNo1mxKvbp5TF5Z9GOtkRx9iKER7GWm3QupHpaBLYagZR473bWiKUAHhxHqWE49F31Q55368Hjroxd0ybwal+CbcpPiMJcS2YEC6xbTMjj8GHB2TAsfzC/AxqPiMT4VbcOLUcFqmS96Ph+OWDXDVICWtvbQw9EG1SdlqYbUMT01fzYtrkyPTgun3jAmYnjWPhq+m/jTT41Ua3rq8xn06AzCqTeMiRietR8J30386adGqjU99fkMenQG4dQbxkQMz9qPhO8m/vRTI9Wanvp8Bj06g3DqDWMihmftR8J3E3/6qZFqTU99PoMenUE49YYxEcOz9iPhu4k//dRItaanPp9Bj84gnHrDmIjhWfuR8N3En35qpFrTU5/PoEdnEE69YUzE8Kz9SPhu4k8/NVKt6anPZ9CjM2iTHxgTOTxrPxK+m/jTT41Ua3oqzytxJXp0Wjj1hjERw7P2I+G7iT/91Ei1pqc+n0GPziCcesOYiOFZ+5Hw3cSffmqkWtNTn8+gR2cQTr1hTMTwrP1I+G7iTz81Uq3pqc9n0KMzCKfeMCZieNZ+JHw38aefGqnW9NTnM+jRGYRTbxgTMTxrPxK+m/jTT41Ua3rq8xn06AzCqTeMiU+q3rkAABAASURBVBietR8J30386adGqjU99fkMenQG4dQbxkQMz9qPhO8m/vRTI9Wanvp8Bj06g3DqDWMihmftR8J3E3/6qZFqTU99PoMenUE49YYxEcOz9iPhu4k//dRItaanPp9Bj84gnHrDmIjhWfuR8N3En35qpFrTU5/PoEdnEE69YUzE8Kz9SPhu4k8/NVKt6anPZ9CjMwin3jAmYnjWfiR8N/GnnxqpVvVh1HkG3z9G2tvp8dHgVDDak6c/rbQ5qhUeYcPBOM1tKkBfoOWZ1CXdC99ta5+vBOMRVFCHV+O0XnzPRRPaen7pEkonhPIgqoAZBqmfQaqrPSUxD6pR6UrYlu2wrOWFKWLW0nVEpPo5NfVQryeeZ8j5Jz/Vofk+vduQefw14dr3Tr9mmnE04GfUnq/u83+Mvq/nkz838EPeQH+x/aJPsPlFVO/lzQRwhm1KAe1oS/uZ6dgAtc/nfGs3rwPEzzyvACwl4izUIIt3p4zGOKdeai0yMym9Xl2ObDkdOnXRlN6/tPQzxl8pTgOQCxnuE1xtpWhVa1bJuqJ+adWznbX8nIKnRIyskLU4L/bqah4fiK687pQolpRVnZmpvxrSMuvUICskaxE+PmXWgc5wmmNf2WgLtQ+eMZZrQMmwBjNW/hLK63A5SlYFfZGVqvdqKE9Of+LdzGgzx+tHo45GnZ4K0AbnPB79eGcdnQrwpsLB7KfSD6angtGpnDEalR79BsQALaXWcOpg9lNHo05PBWgDDhuNSj/eWUenArypcDD7qfSD6algdCpnjEalR39idCrAnwoHs59KP5ieCkancsZoVHr0J0anAvypcDD7qfSD6algdCpnjEalR39idCrAnwoHs59KP5ieCkancsZoVHr0J0anAvypcDD7qfSD6algdCpnjEalR39idCrAnwoHs59KP5ieCkancsZoVHr0J0anAvypcDD7qfSD6algdCpnjEalR39idCrAnwoHs59KP5ieCkancsZoVHr0J0anAvypcDD7qfSD6algdCpnjEalR39idCrAnwoHs59KP5ieCkancsZoVHr0J0anAvypcDD7qfSD6algdCpnjEalR39idCrAnwoHs59KP5ieCkancsZoVHr0J0anAvypcDD7qfSD6algdCpnjEalR39idCrAnwoHs59KP5ieCkancsZoVHr0J0anAvypcDD7qfSD6algdCpnjEalR39idCrAnwoHs59KP5ieCkancsZoVHr0J0anAvypcDD7qfSD6algdCpnjEalR39idCrAnwoHs59KP5g56jsPnVkqCLdd37uSjZZ9LoVmgHJhvv9t11U8e1wt3xw3oR+gwKkFZ9cdtdFlVjqoMpyVn79ETIUrumqr8vE0yQcSif0gtOXtt0oGtQ8v26rPhlANTyvhax2Tyi+IKIU1aDkD2Tk//5TZqX/+xO+e7My7iUKzV4lS8tOFStItro/7/gj25LmZJV8eesQ3iw8HqFMmMpuNn/+iK1fxWZ8b+GFvIF9sf8oH2HkTyBeqfZ2x31z2me0dI9v5Nslbe849fU4Bp3bxw2Hf0R60x+NnFe9qubpJlvLO1Z4enjrYAMrNMJUepKX04JXtVvORXWKY116H75Uz1jtwpMPhjHlhy6nRdQal3q2Xl9KLI9ibyjxoIxk9RbumyUCWMp6GBbNs0zSgYA1a/DMW3NU4ei9XX6+PPXSpxoSbFEwNrZXeNUN2STp67tPVq6J7bWU8KtAzrJpNETEVDozrsOD88KMISwkbM+S5Sq4kO/Xp00fOElgtZcM4Tht8OSJaHNkhWfAbollWLWb0JtpmpMy0VScZx+mCL0dEiyM7JAt+QzTLqsWM3kTbjJSZtuok4zhd8OWIaHFkh2TBb4hmWbWY0Ztom5Ey01adZBynC74cES2O7JAs+A3RLKsWM3oTbTNSZtqqk4zjdMGXI6LFkR2SBb8hmmXVYkZvom1GykxbdZJxnC74ckS0OLJDsuA3RLOsWszoTbTNSJlpq04yjtMFX46IFkd2SBb8hmiWVYsZvYm2GSkzbdVJxnG64MsR0eLIDsmC3xDNsmoxozfRNiNlpq06yThOF3w5Iloc2SFZ8BuiWVYtZvQm2makzLRVJxnH6YIvR0SLIzskC35DNMuqxYzeRNuMlJm26iTjOF3w5YhocWSHZMFviGZZtZjRm2ibkTLTVp1kHKcLvhwRLY7skCz4DdEsqxYzehNtM1Jm2qqTjON0wZcjosWRHZIFvyGaZdViRm+ibUbKTFt1knGcLvhyRLQ4skOy4DdEs6xazOhNtM1ImWmrTjKO0wVfjogWR3ZIFvyGaJZVixm9ibYZKTNt1UnGcbrgyxHR4sgOyYLfEM2yajGjN9E2I2WmrTrJOE4XfDkiWhzZIVnwG6JZVi1m9CbaZqTMtFUnGcfpgi9HRIsjOyQLfkM0y6rFjN5E24yUmbbqJOM4XfDliGhxZIdkwW+IZlm1mNGbaJuRMtNWnWQcpwu+fQRmZtZKx67qvBgV8P1pvu2NB5PmTDwluuL1VCS1llzDS3ccQEtNm0HyDV4i1XH6ZDalyfLyp+wa71xOA1JUMzTr9XgLusIXVXxacD1ZiXR1hjKhDvrHzzjLkPB0Dz6e1jn98iyfTTh9fl7NDyB5avq1kENXUW27DagCvx5/81Cl0pWgPV779TOc9gw2PyOrIodl8+cXXXUZP530eSW/fDdwfVG+/9jzdVqGbTnMzptJvpptughrRVrs5ymW7QzOWesto7TIbxfzMTJTz1pt3koiHiu6nRSJDL3PpIuBnrLeFmHZoFUzEgNhAWHRjPDm65ld8jeL4+QFHyeottYLyMd/PIhRfTNwA/atmXR11GqrYAOau59XgIARzEzUdQYsxnPNnmfNnNfO0OujcDqQUvbw83i0wVNn3wHXIUqGNVRx8hIqOdk1rcpwHgFUgaLl8Xl3Oah6G6+ax+rdqt4647Ubx50GjgNGo6I7hM+llLVQFr2VV05sz2FYVEM2Xpt5zSDAcQD9AN1pPs8/b4YbyaV8Wa/caHsOw6YasvHazGsGAY4D6AfoTvO5//NmuJFcypf1yo225zBsqiEbr828ZhDgOIB+gO40n/s/b4YbyaV8Wa/caHsOw6YasvHazGsGAY4D6AfoTvO5//NmuJFcypf1yo225zBsqiEbr828ZhDgOIB+gO40n/s/b4YbyaV8Wa/caHsOw6YasvHazGsGAY4D6AfoTvO5//NmuJFcypf1yo225zBsqiEbr828ZhDgOIB+gO4037p/5wzHn+XqO/dZzcef2qrTunYoWRWvMBdTseF6xEOfdn3D7uxlQ1dDb3B8UKKTQUp9gz48vdccH7/Ts7SeUXwnfkaRmAHaM+k2146ous2I77Eb5aW//FN/4XzBtacty02S7Yv3SRHj3+T0eLfTaxsJtNOZ/W8Qc5+5CXPsp+YJmeGOsW10BKo+/9PFvqJP/tzAP78bsP3dh+d3NMvPF25mr1+MpV/On6XkyL39OntLB+F5vFZq5FVQ0r1djPD6rxkYWOOhrjdCeiexIwUaXK8tTeRaNXL07KdFp9bQI+Ug+71pmxNqA0co/Q1xHHx/zcSz9i5Uy2kWKOmQLtp/oSmig6vqCofWi0ydFc2Zd3qnpiSbciB9fVyHNDRWNqgwZ5+aEvQp1zqEUNfmcb0ItQ90/EGb7nLoDkeknkDT4Snh4FwunwzagblpXG9oMVVcOgyJegJN2aMEesrqYI3WyeDS3DTz3tBiqrh0GBL1BJqyRwn0lNXBGq2TwaW5aea9ocVUcekwJOoJNGWPEugpq4M1WieDS3PTzHtDi6ni0mFI1BNoyh4l0FNWB2u0TgaX5qaZ94YWU8Wlw5CoJ9CUPUqgp6wO1midDC7NTTPvDS2mikuHIVFPoCl7lEBPWR2s0ToZXJqbZt4bWkwVlw5Dop5AU/YogZ6yOlijdTK4NDfNvDe0mCouHYZEPYGm7FECPWV1sEbrZHBpbpp5b2gxVVw6DIl6Ak3ZowR6yupgjdbJ4NLcNPPe0GKquHQYEvUEmrJHCfSU1cEarZPBpblp5r2hxVRx6TAk6gk0ZY8S6CmrgzVaJ4NLc9PMe0OLqeLSYUjUE2jKHiXQU1YHa7ROBpfmppn3hhZTxaXDkKgn0JQ9SqCnrA7WaJ0MLs1NM+8NLaaKS4chUU+gKXuUQE9ZHazROhlcmptm3htaTBWXDkOinkBT9iiBnrI6WKN1Mrg0N828N7SYKi4dhkQ9ISmyA9VOJboLWctxFFCtDld/8lGm4jWf/FUxUtDVOTPNyrBG62RwaW6aeW9oMVVcOgyJegJN2aMEesrqYI3WyeDS3DTz3tBiqrh0GBL1BJqyRwn0lNXBGq2TwaW5aea9ocVUcekwJCqAK7N6E5cf08pUkr4T2Hz/ywh8KvxE9BpDg+fklGQEvped79FRLzgT1bmyqoWzRYRlGyLnHxVU0X2og/pNDZXGe8pIoEgOrYrwqpndboJ3AdlOzrrUZiWVV6zFZOdk22H3xS/mtvLarMjXaeQXJwUq6Eu49P0oM1AJssHPkd28uqx8m0xzzTHQs5//oou7+OBzAz/hG+ANoH8BlTfZ9VVs5yu63h74TXZ/MfMhlAz5OdBnMpizckSyvr+fCeaVufA1nK26R7wl2JbDv84cIgNpe9GAdGwC+4Slp+TYDMyqIdWYJNviHz0jY+jgadGb9Abo2ZozDzPPEDgkKLNSZxHHDGeURAJbuOZhYCzGBp5zHYVzqaH83UgpRPOaowKlt4g+1enpBrfeUUHKbbH11OGAITwqQBtUTwM58JSe/TEK9bxe0y3w8Rc9xQjVVkqTtefCZx12Sc++xCv58/y+DHepvO/1FONUWylN1p4Ln3XYJT37Eq/kz/33ZbhL5X2vpxin2kppsvZc+KzDLunZl3glf+6/L8NdKu97PcU41VZKk7XnwmcddknPvsQr+Zv3z4xJF6qt1Nrn+X0PZz6up+RnX+KV/Ln/vgx3qbw/r04xTrWV0mTtufBZh13Ssy/xSv7cf1+Gu1Te93qKcaqtlCZrz4XPOuySnn2JV/KPff++ns2jTUIyaQEOaL/7/ScDB2YPde3znF9jTgYpWWsk32K/MuVAjXWv1ps4xTXH1ItUu1W5e6mavQcCtGN3x1nOJtdEfiZM3WdF120u5qz62bF3jVQd89cBY6UuET+d5eRednjWIS1DwtIOhvIz6vTdrq7PZ77ZkqvcFTr73HxxvNpSyW+f//lFV13OJ31u4Kd3A/OLKN6fbO8XaOfNLSJ+qHBsct5Q7l/1e0+Tu2n3nuzKG3km0ubYkO8tzujB+/PPPcyA1mDZ0c2ZR2Rg6zRgCTNTH+Whh2ZFZcCrrj0x+LcOqEtZJUaxqdX8XMmZ+rKLy+IOY9rOa8jQXpmOtls3WyVN2PYzG+U8IC7KAl3+zFenGjz2lE0Sf5RJu4jR5YgwAiR1OHdV0ttkZbShRNrqQ+teZnUrAAAQAElEQVSTZvV2SBZy6by86RGHTx3t2aOD0Z91PM4fzgygP3Fqw6cyBwdw8I6PNnXmPs/nJlSfC9wN0CNObfhURuEADt7x0abO3Pfunxnw3PNOezdzzo0/dbzP87kJff78pX0HesTzcwb7qT17ZsDozzre5/OPm9C++7knHXFqw6cyBgdw8I6PNnXmPvfPTehz/9K+Az3i+TmD/dSePTNg9Gcd7y/y5x8f23zcfLzg7IfPXHqbxGCADkqqFPHNioX67vtf1x+qdp5eE5wPd1IhKSvdsXzsR36tHq4b145XMVdO2iS8vrGm9s8CTGIXzo+fkQP4wj+0G+WgmyA5/zzluSe8einHQGnZs/XDU8LBQ4qCmp9VvhrLe3FiuFZ9qaP3ZWe3ydeHl1eZMX421dqlxOcXXbmEz/rcwE/xBuz+gra78hphfBHbsHyp80UdAy3lZ6zecxvilzUR+rj2O0d8u3Dz0GwoFpp1+3/WoXqDweX1varTl8APXm2EHXN00aekZl1CGMOt0eTNrd5h4UEMOyn0tkrjgWZ7Yft4IIKD20IP0AFe1WjwevS6R3o8z+nobnXGu9OawAzKTFWCEmSlUc3BG2S0rtqRjwtpYR8XuUYsuU6q7sbQB7gXN21mvVFCEkrEsF78CTRLtmQnKcHzF9XUyM0PYSgV7JmQ6UN7XwgaCN1reirA+DxftzvTirqfSi0MpQLUZ31q46OD6akA7XP/+ty/OuZzgq54JTrd7mjkZ1Xi1IZHrjU9FSB+Pv90u1utqPup1MJQKkB91qc2PjqYngrQPvevz/2rYz4n6IpXotPtjkZ+ViVObXjkWtNTAeLn80+3u9WKup9KLQylAtRnfWrjo4PpqQDt/4f7t+ew1CyONR+UYY3795+W7TJGt5weKMwbSlyd00lrq5x/lKjekIWUstDghflAHWuQn3/yw4HLV+maQORgamlePrWE9F1Vc04zkGA6g58zDhUf8Kr2GOesBs8mR6CAUNZQH+e1jmKoylpUCe65WtIgOjcghqPV4/YLMqomyptmO/0LvfK8zZA55BL58KezLduZY/Xs5xdd3MUHv8w38BP+2PuLlBc4v8hCsfMGkK9su7+YbecLm6k/BbJX4jwlXqJ9hX1/OXamUrJqDzXiseLLsi1lKUGhDV0rMwgxwvJXAnIaygP7jfTU16jtPMKns7nj7AaSWYqi80w94sv8+Llvrb2OdtuLXojxWDbTYBnVL56CA0J7nf4YU3tCtDzfxciOMwg91/M8xg6/2kotus4crt1x/6pgIp8v+dNqds/KDpSZt60rXG73TnlV7+Q0WV5IebN8m1M6i3Axh4KUY9mn5pps2ymf57tuxLkLFhXAv8KZbdVVvHoq0Op1hO2zy8T01M/9u27E646oYLWP4sy25CpePRVo9TrC9tllYnrq5/5dN+J1R1Sw2kdxZltyFa+eCrR6HWH77DIxPfVz/64b8bojKljtozizLbmKV08FWr2OsH12mZie+rl/14143REVrPZRnNmWXMWrpwKtXkfYPrtMTE/93L/rRrzuiApW+yjObEuu4tVTgVavI2yfXSamp/75uP/9veT+SH7W95/z6xXXx0tmq5McJWWv6r1b2TRgaUNfq6eMJoiTHdWpKY9l+1Kg9NQ97TDvmYttaZFX5prOzFTVmbvTxSQ7HVBHuibk42ca2guZyhK4xIt90Z1Rt//qMtlxhlc9XgujjlgSTbie8+rgpWp77NIO9pdCqnMqLR9R3/s/Rr/mPuXPfAP/+X/xX+rf/ff+ff3mb/7Wn/mszwF/0W7g/KJ8fmxewks2/PXou+WXYP1G0H2NNv1Ovs5iaPZwDpynoX8bTID8pZKjsr4xenc4vwdH78pJoL1HzojFX27oJt0Rf/4y3Ea0bNntV8LAV7WUXMCXp0QrbyV8sNqUnJcVImUWik/VDpTdfIcwBzKySthtjTy1TZ5m8Q9912imO/DsD6voG985Fc+kwKsP3Ys/A+9OmejOxciqaJbXFZ09JSY5yGdTVBeU3FCCP//e4+rIIZlB7XNe6Vxohz1aPbqOeIXjU0OzHHye/6r7crI2lJi7GsfRWOjc2ivNKztcSFP1FYKi6nREO/3n1rKrvGrSydpQgue8qnrnkMyg9jmvdC60wx6tHl1HvMLxqaFZDvhIXDucbhAarZ/hMAVWB2ewi3NepTsZj/oKoSqadUY7fWbr7b9q0snaUILnvKp655DMoPY5r3QutMMerR5dR7zC8amhWQ74SFw7nG4QGq2f4TAFVgdnsItzXqU7GY/6CqEqmnVGO31m6+2/atLJ2lCC57yqeueQzKD2Oa90LrTDHq0eXUe8wvGpoVkO+EhcO5xuEBqtn+EwBVYHZ7CLc16lOxmP+gqhKpp1Rjt9Zuvtv2rSydpQgue8qnrnkMyg9jmvdC60wx6tHl1HvMLxqaFZDvhIXDucbhAarZ/hMAVWB2ewi3NepTsZj/oKoSqadUY7fWbr7b9q0snaUILnvKp655DMoPY5r3QutMMerR5dR7zC8amhWQ74SFw7nG4QGq2f4TAFVgdnsItzXqU7GY/6CqEqmnVGO31m6+2/atLJ2lCC57yqeueQzKD2Oa90LrTDHq0eXUe8wvGpoVkO+EhcO5xuEBqtn+EwBVYHZ7CLc16lOxmP+gqhKpp1Rjt9Zuvtv2rSydpQgue8qnrnkMyg9jmvdC60wx6tHl1HvMLxqaFZDvhIXDucbhAarZ/hMAVWB2ewi3NepTsZj/oKoSqadUY7fWbr7b9q0snaUILnvKp655DMoPY5r3QutMMerR5dR7zC8amhWQ74SFw7nG4QGq2f4TAFVgdnsItzXqU7GY/6CqEqmnVGO31m6+2/atJvMlOtq1w9grOMVilkaujPtdZ8vn1XHtDQiuV1R+MaoX+RgrfPx3RMkMJNVcm/KD7rthFpBvSFvmfkakn1QiEDHhYevVhqutsqPUrVN34s7Q9M9+DjuyvT1Wn9ER0v0DkIx4xBqD0V1kLntDWUun14g58Z+6Xu6TZWxseh5pFROQwldK3Pf9G1LuKHLH/9r/+L+p3f+Tv6r/7ef63f/d3/VH/jb/xLP+TjPmf/uboBviifL7i/SPkFVjszY/UXfN4u81V9+YpuEXbeEHs77XfQ8xKVDdR0s79bEQelXcgeXkO6bJH9nFp9xjIirVY7EMASQhlNiXCxNPq6V1/CZucgNjSFN2c/D3CMzPupRy4pH5eKdLaOyD6BSLzKlFqWJXSQ/XZ6dVys+z33mGEOMDVVggVZQ6vqHhzlGI7M63I4NW2Wg8eqDdGzyqEO2AjHoA7ov4XMOM9kMVIc8g3gO57XhmeNVY5DbC/eNdJeDivUDCxClmuHVr6qEngNxbcIh521uUq12yVb96Av1AysfddOrXxVJfAaim8RDjtrc5Vqt0u27kFfqBlY+66dWvmqSuA1FN8iHHbW5irVbpds3YO+UDOw9l07tfJVlcBrKL5FOOyszVWq3S7Zugd9oWZg7bt2auWrKoHXUHyLcNhZm6tUu12ydQ/6Qs3A2nft1MpXVQKvofgW4bCzNlepdrtk6x70hZqBte/aqZWvqgReQ/EtwmFnba5S7XbJ1j3oCzUDa9+1UytfVQm8huJbhMPO2lyl2u2SrXvQF2oG1r5rp1a+qhJ4DcW3CIedtblKtdslW/egL9QMrH3XTq18VSXwGopvEQ47a3OVardLtu5BX6gZWPuunVr5qkrgNRTfIhx21uYq1W6XbN2DvlAzsPZdO7XyVZXAayi+RTjsrM1Vqt0u2boHfaFmYO27dmrlqyqB11B8i3DYWZurVLtdsnUPpy3UDCxClmunVr6qEngNxbcIh521uUq12yVb96Av1AysfddOrXxVJfAaim8RDjtrc5Vqt0u27kFfqBlY+66dWvmqSuA1FN8iHHbW5irVbpds3YO+UDOw9l07tfJVlcBrKL5FOOyszVWq3S7Zugd9oWZg7bt2auWrKoHXUHyLcNhZm6tUu12ydQ/6Qs3A2nft1MpXVQKvofgW4bCzNlepdrtk6x70hZqBte/aqZWvqgReQ/EtwmFnhW94s2+TzJgznJF8/5qXkx+Swllo1AH9CXT6VDs/P6WKs6RkF2AXVJHHVHVytvUcDQY1eq9pqA339MqZcsDiIPbHqTZ1Wwgn8nNG7FKYcRq2839Hxnbpz4RaePhozNph9Xy6hjl3IaXFI+Ojs/WS5x7XYb4cMRxsqUamo5YggjNtNDpwcnoJ23bVdOo/eKde6/OLrusufjA2v5D4S3/pL+lf/1t/S//J7/5n+pt/81/7wZ73OfjP+w30F6nd9f7RoLm+qO2rzufY1Puen9U5A/mVEO8vefOsDh6VdVDahUyt5yN887mZkTIbzDl0usWl9Mz0U3uYo1rpXCoU9MZIm4RLdkwWVY9Aj2Q5+Vg1+4ra+uuwNs2M7cyocJuJ3m+27SlRUirLpBOnGR2f85yTnb4X7EDRpKyMzeNqFAlCdUyncaoWmnenxPShvdylxju1gH5Dmqwa4QUzRR2Nfjj12Z8a3jsww5l48G/VmcF/gn1g9OHPOv5ZmZmz4Xjv6szgP8E8GH34s45/VmbmbDjeuzoz+E8wD0Yf/qzjn5WZORuO967ODP4TzIPRhz/r+GdlZs6G472rM4P/BPNg9OHPOv5ZmZmz4Xjv6szgP8E8GH34s45/VmbmbDjeuzoz+E8wD0Yf/qzjn5WZORuO96a++RexTDaYB92p3i+UGG1qpC8L7/P8vhbuAvauzh3hP8E8GH34s45/VmbmbDjeuzoz+E8wD0Yf/qzjn5WZORuO967ODP4TzIPRhz/r+GdlZs6G472rM4P/BPNg9OHPOv5ZmZmz4Xjv6szgP8E8GH34s45/VmbmbDjeuzoz+E8wD0Yf/qzjn5WZORuO967ODP4TzIPRhz/r+GdlZs6G472rM4P/BPNg9OHPOv5ZmZmz4Xjv6szgP8E8GH34s45/VmbmbDjeuzoz+E8wD0Yf/qzvfGbmbPi3wF68Z12aHZLVf/dArkG3iFCw3fXQUb4gQpZqbF4jtUR1PM7CAmUOWTOl8Rfp7mdA9QiNTh3I+ef49r+ebz3DNbVU9i5KwWMbnMefo2j5yZCip84+UPo+QLfY/lZL6c6qrZ3OA2JILYsYr3UUcHb182eNkU6HSX3+p4t9DT9s/of/8L/V//6//R/5RSt/CNJf/au/qv/wP/qP9dt/+9/4YR/8Of3P+Q3kLSa/eKov4vpIui96pPFtH+rPov25eE1Ztd1RQrJC3q3nvrzJLumbe/Ix5JNf6+h6L82udThqU9iglXUwDUbaLLq36Ocz+LCzad9RvYrT73k/9Tos971Gveq7kuNL/jLDGQA3Q/ggNEpnjU/FjKPULNi6KyGpY+07lNaTzzPS1pqD0kBBn9DZ65yurilHA0p99+fUunWLtDbpUNOqzlDHs0ctLYT6Dv0ydR4jgtmpL+OH1wAAEABJREFUeyZi1p4tnoQPQsuDsxegTYU/MbPozA2mp+6ZNFn1DOYsiTvBB+PBtQINSn2HmcVjbjA9dc+kyRJgjvp5fn8Kc0d1H7kYeEotNAj1HWYWj7nB9NQ9kybrc//rkuoukrgfEFp3A18j1cPHe9aZRWduMD11z6TJup8ZAR+Elgd/d874Z51ZtNlDnZ66Z9Jk1TNm5vP19/n64/MDzOcGnM8PgDYV/sTMojM3mJ66Z9JkfT7/1iXVXSRxPyC07ga+RqqHj/esM4vO3GB66p5Jk3U/MwI+CC0P/u6c8c86s2izhzo9dc+kyapnzMyfx/cfPgA+Dj4GAAfwwq0phWT2baAonUX0d/Je/VwYjkmlm2yRA1WckyWQMrMH4AxRuWvqYVabPTMSWou+vrmvAboQ9mdvWHKN1UgxRH6Oquae2F0K+0E1ndgG4+Mvjv/lnFee50IS41/hr9JrpE3OoVcfhfSawa68lvpL4aYzCHqGjF0vFYJQt7Gb6pBrBsLHRi1cc7Sf/6KLW/iB8b/+3u/p7//9v6d/8A/+G/3hH/5hPe1XfuVf0N/9u/+B/vJf+SvVf9Iv7w3ML2G+3oBlN9qDN+OLu/e1Zju/S7q+uG334Dfz4XNYzUWrI5KyOAKUtVNm4LUnQ7KYASXhPeEIC8xY6YVABZyTekppVTOHeFDtWCIlx1CUfQ40YaVzod9kdYV5y83GKKHJx8oHZbv2aWVN8IHwVlu+lCLCpMBy8lrQQaSmPib6+UKxOqgB56aU1tVMpT/2oDDI64kjeIHmgJtTLHeT/DgpSi8mnLmGipFVwa7X1ph5lQ5rKC63qwonA6aoJ2LVLNrJLdtSraQmElUdhmfGdoTrbJseRKPsPmNwwN5CtKoMntyyLdVKaiJR1WF4ZmxHyLPoA5seRKPsPmNwkDkVlKihVNZwy7ZUK6mJRFWH4ZmxHSHPog9sehCNsvuMwUHmVFCihlJZwy3bUq2kJhJVHYZnxnaEPIs+sOlBNMruMwYHmVNBiRpKZQ23bEu1kppIVHUYnhnbEfIs+sCmB9Eou88YHGROBSVqKJU13LIt1UpqIlHVYXhmbEfIs+gDmx5Eo+w+Y3CQORWUqKFU1nDLtlQrqYlEVYfhmbEdIc+iD2x6EI2y+4zBQeZUUKKGUlnDLdtSraQmElUdhmfGdoQ8iz6w6UE0yu4zBgeZU0GJGkplDbdsS7WSmkhUdRieGdsR8iz6wKYH0Si7zxgcZE4FJWoolTXcsi3VSmoiUdVheGZsR8iz6AObHkSj7D5jcJA5FZSooVTWcMu2VCupiURVh+GZsR0hz6IPbHoQjbL7jMFB5lRQooZSWcMt21KtpCYSVR2GZ8Z2hDyLPrDpQTTK7jMGB5lTQYkaSmUNt2xLtZKaSFR1GJ4Z2xHyLPrApgfRKLvPGBxkTgUlaiiVNdyyLdVKaiJR1WF4ZmxHyLPoA5seRKPsPmNwkDkVlKihVNZwy7ZUK6mJRFWH4ZmxHSHPog9sehCNsvuMwUHmVFCihlJZwy3bUq2kJhJVHYZnxnaEPIs+sOlBNMruMwYHmVNBiRpKZQ23bEu1kppIVHUYnhnbEfIs+sCmB9Eou88YHGROBSVqKJU13LIt1UpqIlHVYXhmbEfIs+gDmx5Eo+w+Y3CQORWUqKFU1nDLtlQrqYlEVYfhmbEdIc+iD2x6EI2y+4zBQeZUUKKGUlnDLdtSraQmElUdhmfGdoQ8iz6w6UE0yu4zBgeZU0GJGkqd1b2X39Vj7uryyfn5Z6lOdXQQulh3eTW33hlAS1kLZdEUe/WUQfT5Vls5TTWDyUlUVMvqoILuktP0lpA9Ff2xyq1BjHRwQLsQtU6ww+pnkjbSFZlXZEcBqKtGqb3MFEHAX3BEu/JSniU7HW2wL8WyHSMrI1pUizgVpLTEjO7htBxhh2VpD1ejibFtdA6i4k6F6/NfdPU1/Dj5f/4n/0T/w3//3+mP/uiP6oG/9mu/pr/zO/9O8Uqf9Et5A7YfHzdfsOCS+5da9HlDzxuabdnN02IUXDm/XjjFpX2z5JzxeCpbd4WMedbak6dlOCtO+M4ht4XHa1Vec16bnoF/aW8fucR6bEat/ufLaY6ZN9xXANuIjmaHbLGJHS1LOVPvIh57sew0TZIXD9Nj73q56mAuQJz9bdQuV14CnDlQkitPYjuWM+cRU5t7qUyAGCw2ASSqIx5AysaI315sxWW2t1p2/kwRDzicWQCXvP5RRXeK1lDi1FQOu4FW8JzumeXPnAr6z6U9Za9FtApTaU5W4pXqVKU2lHA6V00K5/wGPfg8f27U636ooPUXlxSgpORrbxRlHtUiXtXB6EFzR1eh80uf++cOcg21Pp9//XmmfI5YfG642NzL3BVq7M/nX26AewDcCYC/6tZgTgIppcGB0nG/Da2Ye1Zcpvocp+s/l5c6UGCtwpQZVIt4VQejB80dXYXOL32ezx3kGmp97n8+o/oz5ZXPFdjcy6tuSaUqMdOhpTELf1UHcxJIKQ0OlK4/9166Yp6juEy9qjq5n/RSBwqsVZgyg2oRr+pg9KC5o6vQ+aV+DSm1ftmeXx/0ug+l9sdvqbgSLoae5lgO5/ZS7isGer5lbT19E6k0eqAjqs8uako7NGHZZDmkDZjSd9U9EDNfYtUSqu3k7JTczfHevYTacz5HPV+6rjh6ph0H6NAj1Sp9MfvqSnombA6MbjlZyZbt/jQtL1wENZ//aFCALAhib6m29CSslHPV5JViVZN6rXp85KxLLPZV+fwXXXUxP176vd/7X/Q//eN/vB/4b/5b/7Z+9Vd/bfcf8rkB1bvA/avfnv4le3gmw+284fdvm+pN0r58/Vzx2lO26/yUrX2XZNB+Pv/cMWe/6lwck254XV3MHKeUS6NDXErRDPSukKUzBrUd6lCQspadPpscd0n3Ysl2QY+wrRh5l36lWNYReOv+UW2Xb5oT0c+2hpbA7AZzoAZeErygPF9pM5mlBAVkKl3Z8vFPiZUywRnFJ7lJrCK0zBRK6RQdKcfOAzQ8VlEl4ClidnOEBfRFd5m5Eehtq/9p1SkuJSTLdnIvl57Pv7QOWC5NyboFOoJJCydHoredvQBF4eDo42sFKuAKfdNU+3SEl+KbdjSheLYzCSJkueBoIVm2k3s5Kvg8X7kJVXAfDgMpe3lNeCtainbg2Y4OWnaKSwnJsp3cy6V/Pv8+n3/KZ4Iq+nNCu9cKdKhJCydHoredvQBF4eDo42sFKvjcv+qelOA+XDXpWF4TvmlHE4pnO5MgQpYLjhaSZTu5l6OCz/0rN6EK7sNhIGUvrwlvRUvRDjzb0UHLTnEpIVm2k3u59M/771+szz/lT1W34M95hOOPv+a8jF0hAzx4Lqj2pdamqctjTDFsyzZUHeEK0KgRnepUlhef40pj1mEgpVcm0LupfLNLkWwXZKmgCYT17XdmBLCoAL7AJJA6603k1URdfjfpe9nOTnczebX5FVZ7q0+jQv3kqQrbyip+JR7i3R4/Lm0NwgR7AX2j1KbJu8uRxUm3AxEyeKzPL7qOy/ix6D/6R/+j5n/C+Ku/+lf027/9t3+sR3+e85O9gXzVHm8WX18mPmr+Us8XNf+FF+i3PuWNpb+47fb1CwV78xaWc/u8fpaN/q2DmAHt25ZDU1THhPdCbdZnd2ZuVNfO6Va1dM70LnXksf2MkFIyLFBNjeIcyjJSlmgvEmkvNi3g+jxzDznn5652vwjnDfrFlZHpr6fMHBOLr8fWZwD82gdjEIQzzxRDSGDJKcK+W5aZeWSvXqm2dQW7QTT0FGVGE/TYAI2+kJQl9jw95gA6M3DqBgRxYeY4C+lh8+EjF/CCGVV46aTwrdODaJSagxdIpXb6PF99P+teVtEE9zMcL9j3HD4WZ2x9xPGpG5AZSOV8pNkMj7wX/jR4wYzyzLHgWx8xs0WpG5BSO3E+0myGt9MZv5l4BphRuCayb+uHVjRezVYlldqJ85FmM7ydzvjNNGfMaPVakX1bX9L24xWvSpqBVM5Hms3wyHvhT4MXzGideXhbP7Si2VOzVUmlduJ8pNkMb6czfjPNGTNavVZk39aXtP14xauSZiCV85FmMzzyXvjT4AUzWmce3tYPrWj21GxVUqmdOB9pNsPb6YwvNccLZrTObEfwrWtFZotRNyClduJ8pNkMb6czfjPxDDCjcE1k39YPrWi8mq1KKrUT5yPNZng7nfGbac6Y0eq1Ivu2vqTtxytelTQDqZyPNJvhkffCnwYvmNE68/C2fmhFs6dmq5JK7cT5SLMZ3k5n/GaaM2a0eq3Ivq0vafvxilclzUAq5yPNZnjkvfCnwQtmtM48vK0fWtHsqdmqpFI7cT7SbIa30xm/meaMGa1eK7Jv60vafrziVUkzkMr5SLMZHnkv/GnwghmtMw9v64dWNHtqtiqp1E6cjzSb4e10xm+mOWNGq9eK7Nv6krYfr3hV0gykcj7SbIZH3gt/GrxgRuvMw9v6oRXNnpqtSiq1E+cjzWZ4O53xm+l2BnPs2X4EeiVCk6XdIzRsqhJ7Y7jFPyGpZFW18u3/QspeNk5a6v7+Pxr93qliSsRJVvX2dMrh8xrQgGpGCTpQP2DxDBD9XPhzQm08z84gforssCwNEAcc8E4vPz9f8g04M6A0Um/g2HpZN298Cb8mSSIgoDeQa39Z6JA7aiYSVTPCwbspJxPX+vyi67qLH4398R//kX7/939/P+83f+u3Nv+QX9Yb4CsWPD7+66s+Rn8B25bdkPLGk5n+pZf+DDHn9RE5Mu+n/bxWntkRQApvfAX4aPATl56XnrMvr5+CD5YekdewupTDC+UM2/noY9XKhqpJDvaaZmoM6DEepRc66C4f0Zsh/Hqu69les7cSv/qpad7ORa+VD9S27CCCgzdPjjorE5nNBhWUYENkyflHX8JRQEr5jMMB3FGBUht6hFefent2+nI4pYi+HMFI7VEHfbOVs7f8GFm1P1L+1l9+CnpKefAB2gCNgaojrlrnD1+1ngEPYc/MwCN9nl+XwAWJaxXB3ZxAG6AzWHXEVeduacffx4egzQw80p/u/rM5i8fcMGcjjl/PQAhBmxl4pM/z6xK4IPHHKoK7OYE2QGew6oirzt3Sjr+PD0GbGXikz/3XJXBj4lpFcDcn0AboDFYdcdW5W9rx9/EhaDMDj/S5/7oEbkxcqwju5gTaAJ3BqiOuOndLO/4+PgRtZuCRPvdfl8CNiWsVwd2cQBugM1h1xFXnbmnH38eHoM0MPNLn/usSuDFxrSK4mxNoA3QGq4646twt7Rc/zyk/RhZHMPbl/stL2rPhezhnhKMIvw/Y2XI4SClOZU8/xdEAKjDpwNlzPMgWbeR7+OJKlJl6rNv+Qy9aezPBPlDiPcVtAf9Eq1eOt2cvdb80pPL50AHCgs+ph7dGaqLmHAWk9Lo25CW0dOQ9eo0tdwTX2UvsP5T8BLb7N+T+nDmHQZNu+Pyi69RWZzEAABAASURBVHYdP17zB3/wB/thv/Ebv7H5h3xu4HYDt6/m+xcwv9wCtmW7ttEX+VMnzgHKmaC5vhm8wTATZM3zQ9/suNT1cr89k1FmwDUU8WrqzXCeLt292hcpS4rXVVdEcHSEqfCCyY4b1EH0D5i+kmzLtCeiVUvFTK0ScapmV7z6YJSAZyArjWRblt5CFesGMiem6i9NSfS1MSlL9LqCtuRI1JRa8DvoJLKTLSU3tMJbcZR+PV7aVWMtTamjwxvsU8INCnO80FSBg5u+gGOpOJVzUo9ZhUeRRD4Q/dK0YvmUzNuQhYM7ngpkS8Wpn+fXXRx3pXBupnTBFqJfmlaMR2vZDlk4uOWlK2w49XP/3IiOu4JzM6ULtnDOaGI8est2yMLBLS9dYcOpn/vnRnTcFZybKV2whXNGE+PRW7ZDFg5ueekKG0793D83ouOu4NxM6YItnDOaGI/esh2ycHDLS1fYcOrn/rkRHXcF52ZKF2zhnNHEePSW7ZCFg1teusKGUz/3z43ouCs4N1O6YAvnjCbGo7dshywc3PLSFTac+gvcf3ayu8E+JTjjgt3cezYjWQ5m+fCuUy61mfaUpcW9qnbY0YIRbDelDEqhKZIUXnOp6VjOyQ4ZpGVFWYv5MpPgSz5LHNnkqFQQyloqVPBB/RcEzIFyJ7nmVNm76Aj+dyr200ufGWcfSFFBZziNS+bHjzSqRoSTgl7hWeHaA9WI4M+uHn9JkW9N+l42/4FHfmpiU501cyX00JE/v+g6LuPHpL//+//Xftyv//qvb/4hP+4N/HSe9v4LlNc3vzwa3n3P2/0F3ppku6BfOPq8eqPMXrvfSPJWku5biz0u8/787+3qeTblEZS8XgpnTWUmQALIb4CVqeXQQS+FrlXewukeyKhlsfSMyKf0aJeV0/kgUrJKYw5UM2nM6Vedua6d2wrn3G46R2rSdztHOi/eZbRi0wFEaut0BSSQfazWStDulVhS2G1xGhjxHIM7h3iZ1HMWGQ2cvHtnJ6qqXp0qnAxSas25rumSitE77SD0tkZ/VmU3mhJUpw/dy2Egpdbn+XUNuaXrVmBeimODlNtCewetfUq0T06zFh1Y7f53fc6+0Rzi9K6qMH2J0zu5Mk2vBNXpQ/dyGEip9fnzr2vILV23AvNSHBuk3BbaO2jtU6J9cpq16MBqP3/+6yKce1u0GL0jDEJva/RnVXajKUF1+tC9HAZSan0+/+sackvXrcC8FMcGKbeF9g5a+5Ron5xmLTqw2s/n/7oI594WLUbvCIPQ2xr9WZXdaEpQnT50L4eBlFqfz/+6htzSdSswL8WxQcptob2D1j4lxg+9LfSbkObU4INY31/nYH3PnHG0FNED+AYm2EIIPQhdiw6sdn+dbsK5oAZ6srN0Vns6vY3r86/t6tkDWnqTc2bWftCa8BJs9w8XS39beBDYZvYUb5EjtM7rih70akkTvbezatf1i7JRlcjm5HOdP2+2PjPnvnbI3/pFF94HP+AN/J//9J/u0//yr/zK5h/yy3oD779AuQ378mzLdmSvOl/gqp43AKBfONw7OLvebV5qpXObz3x5bBM7sjcLpvfxKpmZefOHe+9wfGYCKIhyrRGseqbjgCqQ7AufxYzFP6O8qdli+6uxJGe/CrrH7LHKtfPLQb35uyJ6ZOlZ1ZHHK0d0c+bn/BqiYFFrvIjrDM4qbSeHAcqqTHLp1JKyiwMzoqnFk9JnSTWXkppVZOsho+kR6ID9VR/+tDmi6DlTPCmrPBK8kJSFpH32EvLRaAIJ7JkxHvXz/L6QuqumXJlIT42e+6KKCMkSs0p87j+XsBb3Aribqkt/Fu4T7ZwpnpSFVYAXkrJK22cv4XP/fS1krgTsO0J8g8/996XUXTXlykR6avTcF1VESJaYVeLz+ZdLWIt7AdxN1aU/C/eJds4UT8rCKsALSVml7bOX8Ln/vhYyVwL2HSG+wef++1LqrqRqiidlVU+CF5KykLTvdgk/xuef8geWVc8urkQJqe/W6fE6zxfJDyLlO0c538Avs7QcNjVUih90VsXYU9fumydMNpV6T8yPNXX+g4OaZG+RKzEHSom/eQlXQgeqdOkn4z8DsNfAKuN327k0KKgDi6i3hmfVTP1sUSwJMeiVu41Ui4+6CLe/zlDXsiqpI5ubVKbjmeA4sLxvpc8vur51Mz+w/sd/8sc/8BM+x/8y3MDtPSUfsM3bQMix7K/aYX+lM07NA9gOZRBOvXC+IUXNQM0mhUZQv3lpIoas8ixlCX4/BVU78EeZut/g9sZ2LO99m2zJcb3lIrQBvxx0uS75lpCCLNnkm9vN0m3LUQah1VML8XcNr7nU+TDoy/+ScILMCswG5sLjwMqCvwMDlikSZ4iw+AemMBHlOQzk8NLDswSviq71x7A4f2XV3ujMwKdGqrW1dOVRQ+aI0CjXQkcDqOynolOfiF+jJIAfjVK48VIktDlv9mgFOhpAYpaKTn0ifo2SAH40SuHGS9Hn+bmouc9QnYGOBtDn/tDpn4hfoySAH41SuPFS9Ln/XNTcZ6jOQEcD6HN/6PRPxK9REsCPRinceCn63H8uau4zVGegowH0uT90+ifi1ygJ4EejFG68FH3uPxc19xmqM9DRgGLM/aGn/bLi1ygJMBCNUrjxUvS5/1zU3GeozkBHA+hzf+j0T8SvURLAj0Yp3Hgp+tx/LmruM1RnoKMB9Lk/dPon4tcoCeBHoxRuvBTt+2cev6okqhI3LWLW+sZzlXkxqXs2QyfPMZxnR28SJTy96dPNsj20Kt1GSFbpO/FYmlRlb/mpcCkdXITpIAVXluz+F+QiwikRVdA9LP65a9XNvmo67cnx3Ppk11nJ+Lz2MXbt14WdURU6aV181+x1WK+wLO25sOrVUYdBLxEpP2YiNra1SevJdr8mftRIe72Mau5pdtvW5xdd+sTnBn7iN3C8C/ALmevVvmTPlzNqfjd/zKKA+x6UnwXOBP0+Ukd2e/sXDX3KMrpJfkmR2AN4eVTdIjMMoWV2v2nRFw4fCjKXldHVnPuzBy8lPnk6+AVey3Se/Uuw3WyXRVB5JDV7uEunuvpvpDkrtjM7252+1nkhzKbHA0pPHdT8u5Q51VASnJlQyg1L4zXMGD4ygONRwWhTVQ85M9O4C3Vo+FQlTl772TN6aq3sKY8anz0ADQleyHBslR4jd6XSw7OKKySrZvgMwNeK4jkgS8VPPZtKi0kFQssMvBAeW6XH+zw/V5F7mLuh1t0oEf1z/1LdiTqK5xMo66ue+xqfCoSWrfBCOHtLj/dT/Pyr15bXSf38+Uv8uWlF8fwBZn3V8+c5PhUILXvhhXD2lh7v8+cv1b3kLrKKKyQrhuo7FvywWsVzgVkqXqqaZ1NpMalAaJLgBdWREnrwuf9cRe5h7oZad6NE9M/Xv1R3oo7i+fzK+qrnvsanAqFlK7wQzt7S4/1F/vzjY8yHq1QH1AYXYKm0k0fjjtCniohOCYyXyoKzmy9oIyy01o3dDnlw+lz/caTsTBWyn5oSkfwFmdya3V3lHGqHASamwhfiCuQnvChhzAyinCtuzfJxipnzA1iDlhdbZbdNHN+xAF/SoWtxGCqQ7NQsARHjwyXsfHj1UlQz+LoFfllXil9N6n3Vz19YAIsHUPvwYpN4EjZ7Pr/omlv51M8N/BRugK/65+vgq3Vp9nyFI+S322/m7XOGuV8EvD0w39W2bCNsPNqlnzPOnpZ5eW56ZBTOp673wKZr5mh42GrZITn/6H24ZbboObU8JRyPvzCoaW+LN0V0fAx4xqGi2q66kr4ZzJX5YlvhVX3S9sJZ9ADOhVEXbNder55y8YspcxJ9AAdK8NDwqH3RkdImZ0XM6l0hWfV3GjXuTZ9eUfGBVpwc6dkrexpa0ROdkVwTsIa7JBsnL9jhtU6OVyJpJrxURwQpKNkHKyw+ruJfXImrczxl3lFrnVxbjTXcS7W0WNXs08Tinj5zF0e8OsdT5o0MTq6txhnupfqmKfsi9FqciSXo4ihXZ5zMGxmcHA+tMBNeqqOCFJTsgxUWH1fxL67E1TmeMu+otU6urcYa7qX6pin7IvRanIkl6OIoV2eczBsZnBwPrTATXqqjghSU7IMVFh9X8S+uxNU5njLvqLVOrq3GGu6l+qYp+yL0WpyJJejiKFdnnMwbGZwcD60wE16qo4IUlOyDFRYfV/EvrsTVOZ4y76i1Tq6txhrupfqmKfsi9FqciSXo4ihXZ5zMGxmcHA+tMBNeqqOCFJTsgxUWH1fxL67E1TmeMu+otU6urcYa7qX6pin7IvRanIkl6OIoV2eczBsZnBwPrTATXqqjghSU7IMVFh9X8S+uxNU5njLvqLVOrq3GGu6l+qYp+yL0WpyJJejiKFdnnMwbGZwcD60wE16qo4IUlOyDFRYfV/EvrsTVOZ4y76i1Tq6txhrupfqmKfsi9FqciSXo4ihXZ5zMGxmcHA+tMBNeqqOCFJTsgxUWH1fxL67E1TmeMu+otU6urcYa7qX6pin7IvRanIkl6OIoV2eczBsZnBwPrTATXqqjghSU7IMVFh9X8S+uxNU5njLvqLVOrq3GGu6l+qYp+yL0WpyJJejiKFdnnMwbGZwcD60wE16qo4IUlOyDFRYfV/Evrgq+bYW07kzQgeaGLpwc6ew5hx6M55xWuhW2sDjf/2u9PhHhWRqtuBheqO+YlUifzLoYnZguaEX5fJ/PYYPlPYuz0yVOTs0q6VuJM7NPBWmKVjhC/XzjCCDlWnUz+6PKqAq6gi2gFMaLXGl7kebDvJ/RE50zxKLhLDbch3EfCsMAi03UC+OgcBzX8flFF7fxwecGfio3wFflz/Na+Arec6/9RmBfv/ziC94m78Gfg8z81Ff25G2REsa6PRrhBvb1MI8G3e2hRa65JYjZ4V2PmRwyfmjbwr9TlOv10YE1Q1mtszcfFcoFSzYpVanid0PX09LeljPjKCDl66qzcPNnEtd2doR8a8XXCeauD0ZOD1JqnbyEZ5qzRt99dmbV32Zo5UcIT66uHgZ7fPjbjwcHoTUOB8/+WxpHj/duz3jUmYUzC+Dv8M57p82ZeOB7Z80sM8wC+Du8895pcyYe+N5ZM8sMswD+Du+8d9qciQe+d9bMMsMsgL/DO++dNmfige+dNbPMMAvg7/DOe6fNmXjge2fNLDPMAvg7vPPeaXMmHvjeWTPLDLMA/g7vvHfanIkHvnfWzDLDLIC/wzvvnTZn4oHvnTWzzDAL4O/wznunzZl44HtnzSwzzAL4O7zz3mlzJh743lkzywyzAP4O77x32pyJB7531swywyyAv8M77502Z+KB7501s8wwC+Dv8M57p82ZeOB7Z80sM8wC+Du8895pcyYe+N5ZM8sMswD+Du+8d9qciQe+d9bMMsMsgL/DO++dNmfige+dNbPMMAvg7/DOe6fNmXjge2fNLDPMAvg7vPPeaXMmHvjeWTPLDLMA/g7vvHfSPKu+AAAE6klEQVTanIkHvnfWzDLDLIC/wzvvnTZn4oHvnTWzzDAL4ODk3+rZX9+kMhzUXIlpakXh+19AnyoAVzy+Wa4eXuJK9/7s4GANSuw/cXxvr8TMUgf8BBIrKy+29oa+WT1v8U/ZTgYpsxz3xnPk9CrPUmplkt5F/yzDVl7O14n20Tliz7AhZ6ugCiRmqkFn+BJaXnlm26YDdGANrYKzqDiSa/78omtu5Eeuf+2v/bX9xD/+kz+RtNsP+dzA7Qbq3zIspXm+lPkKXpqUL/bVt6+OyPR2SCu/QM4zODfgjcK2bN/237ux2Dc8b9Np7feTUuvYPIO/S/St6NGbe0kXy+NuM3kFecrll7laGzIo55Zsf907Ew4J6nk1p8zqfWQua3vwws/cl6nM1EYqqEYqWilcUiYLOgKNtuqapW9EHY1afwBx4CBU1IxBm08TpbzVF4/2XMtmb9FK15AdgUW9ZCmaiKnhNVIpTVbRpLr/9LPe9pkb/6wjTz29k3NmvZQkOF6olI3Ta8XbPnPLvpWRp97Mo+HMfh6fzW10f31T0erl3/pvPGDkqbPnWT/Pl/q+r/vt/nP/fG7oiLf9Nz7BRp56HHOjnNn3/bl/7oLL6fv4fP7NfXAn4G3/jU+wkaey/x04s+/78/nHXXBHfR+fz7+5D+4EvO2/8Qk28lT2vwNn9n3/9D//bq+/XnSUfIBFK6Vfy47Aoi6tSrRbTVMjldKwmJmeSo8+oEenT6UVf4uH6x2O73/tntYtLN967R59wJ+VEvSac6ZGv62l16z6z3Z4z6VbM/usNipbPmp4Vp9S8k5ecwibOx1I6cUrf/Uk+isqNaUXDcBQz+kZD3+3IVlfptGC+hDr/jk7Qg3Ci1SqmViXmqacS6n2SOzhWNuf/xtd+ucU/8q//K/uJ/+//+yfbf4hnxt43oA9X9SSDQ/4Cs5vhuzwVK2wnRnJylve4z0gVtRffNl1Wm2EFUl6HB+FxUSDl1hb1+trzszgOoEd9aJj3efKidoLD9D1bvxmaHiD3EAk/JRaB4fWNhKogSvh06V6vbCpyAPb6zGpmXNByboHcyhUwEQuiCeDskiBg1nFa34pcMCm7LdrYpni1A1GTnf4VJ3xOEd1ihKZPj04iFOr+HoS/ETJ2c9glaTT5/OCmXwcjKg8WOYoSt1aCdL0a5+dGSWooTZp9VXSU4Pem35m0ABnUUen7t61TS5BdkgWHf8H6+zVUENtUlxqlfTUIJt1QVd8nt93wZ1xXVQUapAloSfZIVki8nljr4YaapNiUqukpwZC20BY+Nx/X0TdTSg1Ze6r2rpGR7KUJeJz/7LXZVBDbVIuh1olPTXIsC7ois/nX98Fd8Z1UVGoQZaEnmSHZIn4fP7JXpdBDbVJuRxqlfTUIMO6oCt+yp9/+TiypPowLNuLK993vboPDZGwxqdKsiNKqgzf0BWvRcsLp6aIGmRJfYDskCwRn8+/vg/uYu7lrNwrPX4hF0dfQMhAFt9H0eUwKSOVdg1hvo1Y0yuRzeWl4sMH9Hx/SZ9JTYW/w/Jzus5Z+oESw6lpNRWunGFHGeTzA228qm8Srx7ZMkVivxKr3X2kc/G/SLHc0iqava3eMzODu1Od5aqVNt2kXCe7BlbaTROP7/h8YNTQd4vrAeXVHIlNKHBpfzgl++r5sy1Y3wrOnv3/HwAAAP//Byv7DQAAAAZJREFUAwBXiX6GuzsOFwAAAABJRU5ErkJggg==) - -- Remove any composable content associated with the entries inside NavHost. Keeping blank entries for each route ensures that NavController's back stack is still the source of truth for the navigation state.  - -Refactoring the extension function:  - -- Change the method signature from NavGraphBuilder.existingScreen() to EntryProviderBuilder\.existingScreen().  +![Screenshot of Android Studio showing how to inline functions](images/migration/inline.png) -* Remove navigation destinations, leaving only the destinations they contain. +- Remove any composable content associated with the entries inside `NavHost`. Keeping blank entries for each route ensures that `NavController`'s back stack is still the source of truth for the navigation state. -* Replace composable and dialog destinations with entry +Refactoring the extension function: - - For dialog destinations add the dialog metadata following the instructions in the previous step +- Change the method signature from `NavGraphBuilder.existingScreen()` to `EntryProviderBuilder.existingScreen()`. +- Remove `navigation` destinations, leaving only the destinations they contain. +- Replace `composable` and `dialog` destinations with `entry` + - For `dialog` destinations add the dialog metadata following the instructions in the previous step - -### 4.2.2 Code example +#### 4.2.2 Code example Existing code: -| | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NavHost(...) {    featureBSection()}private fun NavGraphBuilder.featureBSection(onDetailClick: () -> Unit) {    navigation\(startDestination = RouteB) {        composable\ { ContentRed("Route B title") }    }} | - -New code: - -| | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NavHost(...) {    navigation\(startDestination = RouteB) {        composable\ { }    }}NavDisplay(..., entryProvider = entryProvider {    featureBSection()})private fun EntryProviderBuilder\.featureBSection() {    entry\ { ContentRed("Route B title") }} | - +``` +NavHost(...) { + featureBSection() +} -## 4.3 In Navigator, convert NavBackStackEntry back to its route instance +private fun NavGraphBuilder.featureBSection(onDetailClick: () -> Unit) { + navigation(startDestination = RouteB) { + composable { ContentRed("Route B title") } + } +} +``` -Steps:  +New code: -- Locate the line starting val route in Navigator.   +``` +NavHost(...) { + navigation(startDestination = RouteB) { + composable { } + } +} -- Add an if branch for each migrated route that converts the NavBackStackEntry into a route instance using NavBackStackEntry.toRoute\. For example: +NavDisplay(..., entryProvider = entryProvider { + featureBSection() +}) -| | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| val route =   if (destination.hasRoute\()) {       entry.toRoute\()   } else if (destination.hasRoute\()) {       entry.toRoute\()   } else {       // Non migrated route       entry   } | +private fun EntryProviderBuilder.featureBSection() { + entry { ContentRed("Route B title") } +} +``` -You should now be able to navigate to, and back from, the migrated destinations. These destinations will be displayed directly inside NavDisplay rather than by NavHost. +### 4.3 In Navigator, convert NavBackStackEntry back to its route instance {:#4.3-navigator,} -**Note:** When navigating (both forward and back) between destinations handled by NavHost and NavDisplay, you may see the blank destination until the transition animation has completed.  +Steps: +- Locate the line starting `val route` in `Navigator`. +- Add an `if` branch for each migrated route that converts the `NavBackStackEntry` into a route instance using `NavBackStackEntry.toRoute`. For example: -## Step 5. \[Single feature] Replace NavController with Navigator  +``` +val route = + if (destination.hasRoute()) { + entry.toRoute() + } else if (destination.hasRoute()) { + entry.toRoute() + } else { + // Non migrated route + entry + } +``` -Goal: Within the migrated feature module, navigation events are handled by Navigator instead of NavController +You should now be able to navigate to, and back from, the migrated destinations. These destinations will be displayed directly inside `NavDisplay` rather than by `NavHost`. -Steps:  +**Note**: When navigating (both forward and back) between destinations handled by `NavHost` and `NavDisplay`, you may see the blank destination until the transition animation has completed. -- Replace NavController.popBackStack with Navigator.goBack +## Step 5. [Single feature] Replace NavController with Navigator {:#step-5.} -- Replace NavController.navigate  with Navigator.navigate +Goal: Within the migrated feature module, navigation events are handled by `Navigator` instead of `NavController` -TODO: Add warning about navOptions - you'll need to modify Navigator behavior if you don't like what it does +Steps: -For NavController extension functions defined by **other modules**:  +- Replace `NavController.popBackStack` with `Navigator.goBack` +- Replace `NavController.navigate` with Navigator.navigate -- Inline the function, leaving the other module's function in place  +TODO: Add warning about `navOptions` - you'll need to modify `Navigator` behavior if you don't like what it does -- Make the replacements above  +For `NavController` extension functions defined by **other modules**: -Remove Nav2 imports and module dependencies:  +- Inline the function, leaving the other module's function in place +- Make the replacements above -- Remove all imports starting with import androidx.navigation +Remove Nav2 imports and module dependencies: -- Remove feature module dependencies on androidx.navigation  +- Remove all imports starting with `import androidx.navigation` +- Remove feature module dependencies on `androidx.navigation` At this point, this feature module has been fully migrated to Nav3. - -## Step 6. Migrate all feature modules  +## Step 6. Migrate all feature modules {:#step-6.} Goal: Feature modules use Nav3. They don't contain any Nav2 code. Complete steps 3-5 for each feature module. Start with the module with the least dependencies and end with the module that contains the start route. -Ensure that shared entries are not duplicated.  +Ensure that shared entries are not duplicated. +## Step 7. Use Navigator.backStack as source of truth for navigation state {:#step-7.} -## Step 7. Use Navigator.backStack as source of truth for navigation state - -## 7.1 Ensure Navigator is used instead of NavController everywhere +### 7.1 Ensure Navigator is used instead of NavController everywhere {:#7.1-ensure} Replace any remaining instances of: -- NavController.navigate with Navigator.navigate - -- NavController.popBackStack with Navigator.goBack +- `NavController.navigate` with `Navigator.navigate` +- `NavController.popBackStack` with `Navigator.goBack` +### 7.2 Update Navigator to modify its back stack directly {:#7.2-update} -## 7.2 Update Navigator to modify its back stack directly +- Open `Navigator` +- In `navigate` and `goBack`: + - Remove the code that calls `NavController` + - Uncomment the code that modifies the back stack directly +- Remove all code which references `NavController` -- Open Navigator +The final `Navigator` [should look like this](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15){:.external}. -- In navigate and goBack: +### 7.3 Set the app's start route {:#7.3-set} - - Remove the code that calls NavController +When creating the `Navigator` specify the starting route for your app. - - Uncomment the code that modifies the back stack directly +``` +val navigator = remember { Navigator(navController, startRoute = RouteA) } +``` -- Remove all code which references NavController +### 7.4 Update common navigation UI components {:#7.4-update} -The final Navigator [should look like this](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15). +If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94){:.external}. +In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. `BaseRouteA` and `RouteA`). This is no longer necessary so remove any redundant types for the navigation graph from the :`api` modules. Ensure that the correct types are used to identify top level routes. -## 7.3 Set the app's start route +### 7.5 Remove the entryProvider fallback {:#7.5-remove} -When creating the Navigator specify the starting route for your app.  +Remove the `fallback` parameter from `entryProvider` as there are no longer any unmigrated routes that must be handled by `NavHost`. -| | -| -------------------------------------------------------------------------- | -| val navigator = remember { Navigator(navController, startRoute = RouteA) } | - - -## 7.4 Update common navigation UI components - -If using a common navigation component, such as a NavBar, change the logic for when a top level route is selected to use Navigator.topLevelRoute. [See example here](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94). - -In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. BaseRouteA and RouteA). This is no longer necessary so remove any redundant types for the navigation graph from the :api modules. Ensure that the correct types are used to identify top level routes. - - -## 7.5 Remove the entryProvider fallback - -Remove the fallback parameter from entryProvider as there are no longer any unmigrated routes that must be handled by NavHost. - - -## 7.6. Remove unused dependencies +### 7.6. Remove unused dependencies {:#7.6.-remove} - Remove all remaining Nav2 dependencies from the project - -- In :core:navigation remove any dependencies on :feature:api modules +- In :`core:navigation` remove any dependencies on :`feature:api` modules Congratulations! Your project is now migrated to Navigation 3. +## Next steps {:#next-steps} -## Next steps - -In the supplied Navigator, the type of items in the back stack is Any. You may now want to change this to use stronger types, for example the NavKey interface provided by Nav3.   +In the supplied `Navigator`, the type of items in the back stack is `Any`. You may now want to change this to use stronger types, for example the `NavKey` interface provided by Nav3. diff --git a/docs/images/migration/compare_files.png b/docs/images/migration/compare_files.png new file mode 100644 index 0000000000000000000000000000000000000000..11a9fd5506f59dc6835ac4ad41dc9eddeaea7e24 GIT binary patch literal 36507 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 literal 0 HcmV?d00001 diff --git a/docs/images/migration/inline.png b/docs/images/migration/inline.png new file mode 100644 index 0000000000000000000000000000000000000000..67d267b942fbe4c20775fd608b789b438c6ed0d5 GIT binary patch literal 168012 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

Z-eq@kE(9%h; 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

Okd~HH>$iuy8mQ?Yz_&x$9f)T@&)u&b;U{C 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%0Df9|hjB>uBrl|p&x!z@& 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⪚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 z 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 a?}^?WCr%it{}e(&KB|hE3iWc<5&r{Ntn63- literal 0 HcmV?d00001 diff --git a/docs/images/migration/start_migration.png b/docs/images/migration/start_migration.png new file mode 100644 index 0000000000000000000000000000000000000000..4e90e71c6f8ffe202c2940462c3f301833b30919 GIT binary patch literal 40874 zcmeFYWmFtp(>96>Fc1g>L4ytMP6+Pq?h@Q3xLa^{f`{Plu0ayq-66QU%bDD{pZ9&% zIsec4etf;U>7H%fyLQP{RhuvcIdK%E_efAsP$-fTB1%wDFhD3M=sF-gq(mKm?F0tF=zmXv~^qP&0=Jl4KX>@NTXO`Y>`pWZJKq(wDZ8Wjrw zlK+fVDDPhfM#EvE(UEdZV&JO?{0s;+GyolW3y28fBE0z?aKTUo9BsQ^)wWx!ckH-c z^S)i!Epwb*g!Yp$dJ|O41n0-*uYqy!TQDLzEPo>yim;yq6**%e!-<%bg98f8&i%5& zw+c5t?KWghGuPSqT1hdso$mh0j-K^m{E}x)V)< z#L!(1#3N=F3M{;s`rSE{aMze|KAB#{$p2GX*T7j;cc0iN_JwBhB%%qecC6asC^DF!*zpU1o`o>fuPI$VK>>q z0JkuA&CTLICUsz~=uv_9HwLNO_Afbz~<)h;<8W+l9%62u43J>zfR{)d84R%4>16BNuzCpA3v#!H5Ay<5{wMXEA zY5xS(22Z+9iW33`BE%8Xp z0;&pk3KizO8CNYr@PN7&6dvc^dlMNTSw&I?jn{?6L}1$WV$acrAs49L&1uiq2FDOY zyPj)L>IL2LcFo^&WA2O!>6@{_AeBubZg{le_W*_JB0wUr9$qz+Mo{(JfdYNe+i7|g zMoXM)+$d4y3AQ@iMcm_vXaUD@+6k-i^a+za8Yj{g0`E5~A%udyJ+aIOILeXlf`h_- zk{Plv!+k{`MjNIcCLbmkhT0*;ictOe-jJZGV;;wvg&n&Uw-r@8#-{J)(_?im2fiGp zS-9g5xQ%%Z<_f4r1Xm1KLf3a6{T>5TepqdkpRe9&v_WNuF#ecZAKS3o)ZhGth!Mc| zBMc<6j$VVPjTnMRABYzS-OZtxWiH`F9Q-aJ>@Y09mur)J(`eHZ7Z;ZRS3DJj+cC_Q zs+9VhMcw$pm@ffCf`W{~0#QWx70c+dxhVNT2v^KgjWQ3W!gmu6nbgi)6`%j zU`AlXP`gk^Q&Ceb(1_BQP$$u5svf9{QR7k7CMqX2(tM;^Q+;8PHzG75v|BB3cfPb8 z#ZykL+^pzUrdBCdZ_d3CO)5CZPy61YTQ7MX_Fij5gkFSR*`{-mynf?8{4#UbaR+2d)JdMBGk9m{c=WjCULrOI&jX~LwDY9L2Ti6UUCw@s=I=@ zR@j}HR?2$~o%%H68*Y1Lw0N-m?i+|{FxWsOZXO~{jKEiHi zBWvT{@Mv?oq<9Q-%)VH^;9c)pg}pGhfXcbY*~@w4+$64^hcNYVs*=MHpBI0QE9>*q zk?|>+i>3X;(84fhU-M6Q`^yZ@^Q1$;3Q-+-f9`mueLQy}e}Q_*c+CX+Pjy#?%(IVBolJRIJ%lV6{w5pg5!VT>nB2gSs36e#U zZITobHSuUscQH)yYcXw+%IFTlT&$iLi|D>Sv7dxt1iDA{ZgZRd9>C zGbWZpN-3GT42>D>Pa^mf3^WxKwgCja6`x{$)^6VZjIsZkv63;T<9Z@@0vZcaANEXL zk5|ZG`nnh2MEaR(fWDZ_;_KK}%J~|_BL$HJp){gYu}rE=lvKHVPhnqvCKeS?32;oy zrfyumhn9x)Ca|40Q|&~HljH)MKr&=9rQl-(W}H~DvLV^M;AF~1nqt;DH7m=dNU~Ql zxRiB?%v1Sh2>&!g-(jLTW4S?fv2?cbKzl^P+a9Hk!bf&VYo-3)3SsuXtW-;0C%fk5 zmS?DKvkevRJA2)h)mG)u>FbZ(kVTjU7{wp$QKNXMPoXbyuSRne>9U^e-n3g-dbBlk zG}LMH!wX)=l%?5HzG=(xRryw>&$G`sA4acce(lo8gCyIKV>fWaX?M9DHkG3bSYx=GNzXc}z z8Tl`LJAB7?KN$rHiVhGTA?%3ntVBmZ?m}}BMWxxAam-#Kbh`ZR=;gtHIxLd4< zx%G1%b#ZYcXF>CB-P(Qw)^4(LXX>k(yV#@5y=H!`_88jOc6K^Xwxds->O7Yh@wt%i z(nW(fb}r+pEvm(7%a-r{pvmbFHa8BzZe^1Wr{m22!M@d%mF(PcWUr)$~{mA8DiFY8~X5$uRe zdGLMfPMCK-Z@e2!h%Y>lr+s01$?cfyxV6qU)8DPFGK+cOe6GwcYIU2VY=im6fG2xUQLU#T8A2-5F z=4X3TF&0F>ej)J}`;o7NVrx%QMNY^PkJ0^4Z)#;akCh=Lw+3W^rf5jX7^|>6Zz* z*x8k`kAn&yZ>V$e;krnpa1HRr8B5?_>r%5`T3cQ@VJv1lqh4XK*xrQx?h`qJ;MZ^y z4M|g3StuIFGY|>@{T>Pq@&paJ_@MFr=UEJz3JUh0au_J65DO^4zis3o_diE0wp6CHbcX7v%X*F(V21pC(RLyd)a33SeP72NN(m0}}%i2_F&|4CZk#Hsw+h z5&O40fg8Q8BkA8k z{xgn63@uKc$n596Pi{}(0xlKG!f2%Y(mco_d@&G?WqBx&R! z%ZP6wBCi6uLzwKJV-fO~3Ud9qLoOwUD1~JR;|M@WiU_K>K_6uzxT%O@2cr_~i)!sb z$1$|$Iw|--!$I%2r+~Nsz~HyRJ;QuYxU-*BDM4@1y_5Zg8D+~x|Dq#-| z5P}N)1vKe(0 zVu61sLK5e<1Ptuzx=$pNRJy?B3e4(sGk9k(@m;i7Gy)5QQO`@O))cc`zjM^|Y2Jm^ zY&3(-WDrB@D^py_;&idHq?m{fdDFvXvlRCRCuF!y_CKE|C@8HeeSNw%mV-sBSwr^0 zVlq)wh$m!|-{&cmL8nPTI+^Z!tLrIeB1H)axoleE&Ty*q{#0RMquuKG8CuW&?V4{) z$tDT!nmpfqV2jIs$$X_weZ1)6`&^dIhf7>uWVt`f2~I}$6R4VC+8#{KXT)Q7&>)jg zlg|#0jTu|V!A3M0Ow3Wrmzqdr^_{HH?VNWToOdmi%jBBQ6_;17?u)>ly4c=<&;5LV zZ%Fic`X5>hBMN}OvLenUK_;f0D;7oN`vT*1wTFfTJVRCIlMvYo6@a4rXQlj$$U!DB z#CEHwR6b94PA^ZKg;`+z4%B@V)Cm1Hw;#n$HzeHLeV-WlrEjP5AYq4)hw)tTm^+lF z(tIkhxr^-~aec4z{1ys!nA?+;+;B|V>i&LtNp#8r$6?#om*?TLw(x`xR_rwT9X#H5 z8zEPG@~A!@wf|3naO;lQRj|B3*PLDP>#muq_&7Bqv`yD zfI6PV>sh2(yOYT4>4M~Q=C?DNUP^AT6j|kUy4o&%x$7%lZ#9==*cYzI&Tu$;tj*?e zWiG748QY>(suoq_VVu7;kT8`H3u+m==JPnBdVV;p6#HyqnWNKukw_tHNu!ik)Z*%& z{XBcTbl`Tns&BE@;eDV{8dAPXtJ}gB#w&Sq#7U((n0R%!=DUBjuUuz2LzC-J|8DB0 z$zdBwwL~Qq34=;Nlf|q+Jcekh+0o2mrNtTJ{reK~9?E|hoy?!=9gwfbi<(d z`O+y4X4={dD0}aM`8>sbQ$`l5SL#jpy}(kLl&Cx`iP)``sNyETQsC)kAMvO1eS&s) zeet$jX-S&k<=mglf8(vSt1K1ElrzCwtvTP|jki6Tq@CaC^UURZvOEA1A5yQ7-qp>w zRPAZEnyV=Bs(-`larG_jgJoJ$&WU6DEfI%+(a$GJs>OOMaebc!1!>!xX2|Td>dfO> zDrR~XFWs+il)B0ID#e&l;wh-i(QM3ou^+zK#q>pdDe|~}pGYo^<&EJ?*KIJE2xa1E z=<*Kx59fD@0!2~GA-p>B3`c|F$DB;sxN^3X-b)lPgi2LrLdTaB$+u#%ZmK# zEJS?B1<0pnOh8aM-z=b8S`RUvN|D467Udyjt!(@FiFlXQeq12QW-N<$W=}|iSftS% zL*PU@Bt5*)sIJQ8SnC5i@ou)y1NBUWYWk{lvJ7vwPV492@VwiK2#DH^Hn}6|AB&B& z$3B`4;}CM*N%XygCMTsQ&Jc&_0xFBi+iB;|p&uYBe-XkN8aywh*gz#y7Q*vbG^Aor zbV7skv$Jn*%Wu)63An|2LQs`|-NC|up)~i>YM3mpdcp$MKvmTf4i3qU2TtMNS!Ok@%8`&5pjK_jFqyFHrD&nDP!M+C$zC zjB^QD!3d&DP_|g#I}kePTS+h?z`eoBW6u3m#3Is0r`wR2O#e7GUZvOmFkNgUPR@{b zX|vXmspuhY4JzYZGt2fCg9w89J@3vLA?J{_;b z(Cy6v0z$v=t*$20X*%S7H~!FV?CV=7D&z(iuz%L3B4!Qn@)j@g7^rGOzD^(YuGDIl zYX7XiMV_qZ-G)5&sT`Jo^8zoPJOdqz;c0c#t1TubrUovSqXEzz0QbfXanmx)6swnA z@Q8e?83q=1}I&Nf5>%gJ<&Da*LF=b z{<2p=+Q|MG1U?4Mu)ms@a zQI)1|nUU8-R4kCu)RT;jLSb4fgjl|Fq{!Q-BhbUm_0A0RYq<+zr9hEJH3Bqf{<7aCY)g+!=y8;!MX?{JuYBRz%`*x;jG3K=BpJj00OfvPNbyO`xj5LtqFj zpT%QsHZDo;h~bH#ONWB+B4CiMW7ddfkHHSyUpv zVS>!cZ`C+h3_5wqI>F-L{vv;;?}ie^aGLw}zjsjL<3iFu+FgVP46Eb_i8^!F0EC2Z zJQf;kw37-WfA$we)_;$N7Q`n2R#EvB-X>GXrHMdb7mHPNRvW62%_^#(kQ*St2Q$!Ow-S@x zcA0}lrzw={LsV{~AP7N8I)z~(9+!_E*C0G@v-=dA#(*>zgMizGsdtWOPyD^hiScg* zy>b$07(sc&Uw@`92L(eM-wD0(K`D~K|LlG@`_f^6;h?w=da6v5b$>iZ7#?Z!q1pY? z6h1^~0}c2v;s4_c!qh;5FU~~@?78rGr5*p55K(1+g?h^m2TP5WQni_xq;OTI2veUV z!4esE9p|~|D?i0jN6#H)PTD1AJE+sgfkBZ98vuxf9D!gt zkqc~a!yACRPPt=}(RnBpiNLaUp+Tw7g0f%+S(tCYnH)1j!jc}Y-z=$VuWp$n3f&}1 z{3JxDtyvKqN&ApACqbd=7?{BlVA04RSiu5@E%Ub|dg0^E2lZ|Uh&4ao>|3Po*=?yml(^9u z=e}ZI-hv%L4Jf7*d$oH`f*NQ1Jyn=sbnbG;JV#7$iaelAQ-ld$(<10XoAJS_LDYX; zq9eXB66WfZ-!HssiX0blJb*(3J!P`S$c%n9Ln^?Hu5Fm0fsf3@^=FNl2wH=3EH4@v zK95_h*m@o7zC3ZXcU_*uGJ0*{jLoA$vfZu&xPzUc7o^ZQ#2_G1A#rDT$ ztPcW~#lR4|7v9#^mYYux3-h$lcN%9-OYY=7xXdE zqyGj-Dfv2kBJp#xhLe!?>r|n9X?Y!iWNsf?Wo)yfr&0jmJgHG^0QRqg*~RzA`w94N z7$l`qsRw(}e_)U;!(q6*?tX%TH#^nw?Aa5?^$@wTGsp1SJ@3|BTe%M1f~|C z^(;Iyxegk3?d@Xk;PlgxF#PNA(Lpz&0~waW<#;qo)yj*{)%A-<^~Dfi+-twDEgaWi zZP~O7heTVpS~NFgxLWD7aY(dA$^Z2yKN3UvuT!9u^A-#bM5OevSxgp5*Boxxu;UC<-yS+hLDin~8`M2vW7}AyS*!n8*{u28eLngQKYMXl$@?D*T z-GZOO&VkuTmMF`hAH;|Flf1Q1Vx^X4|ecEF2Z86Kv7yCo6mcY7Wbrf&9BGW z*nJv=`j5$jXbN#Cm>xKK5MiAc4Fvuf>%WFO@BO#nQwkIyKvyL6Z}tBj z;18Al5Rn+G&i%im3N}K**%Q&nOBVOxCThRe;s1>ph+shj1N%vEN4@?NStwj>xi&*W z(%Q545&`^;hxng?`~-lg^%63yldc%H@&YmsP z6g`})ti>hz2r@~Vw~#upY+t~5J_c-$P|#+8vIvNueV3ZeS{!!4jMkU-D z0uKzw+Jdg){x$c)C*=GvK8LM?Y6IIVDxgg_=}h)py)5r+llHEnP|h%9Qex-+p{S zZVU*(QeLdHK-qox;(2?bn9g2~lETBoqayyISZx?=_3%ZVQGaq!wbXonlKf$4y4Fm- zM7K4%h28Z;=U_eu_RW_&gU_oS`LEtD{8=@h+X%%{e?u($ANM!ZZwWEbVVhtXTAw>aPp4npfious)yjOR~60g~RHY zurM_w07Fy09DC@K`?S}%=A(SR^~Vtdib8yCWl~JkfG^aF-$kYyZ15Zk2!kU(|J7HY z#JY|F0if}JozmeVuFpS`1tfZeubmHP^LgAaOYj+W+a%K2ZIp!1NS( zq&UWepMU?1Q7%Q_(pi0ZeiDN~_0&Cb#vy!mFPuy+XDQp_Z-{TK#KNQSKIW*EYZW&U z%V#NcB|;GnaDE##0etsvy-|TgC!Brm&J0Kma9rd+^AlxN znun6(v;E0OQ0`^#l;2zuTeu^)Upb{-~yF;4p?a=uyTyri}`dXjrBCJ+RD1T!_t5gJ!w1$f3apqve0X${&f> zXJG^v=T(sVKQK!qezJNH6b%jJhd51D20c`&CDU8SE9u_Y%c|ri{jvT}&xNsNNN1Oq zjwMcJfB@sRPd{$Swk2aXo+5bKiQlF~XLHCs-fB1Y*cTWvDCJRwxk{uqNTe{(L$pdT zi$kiRHhAOZ`Ek0%dEO~7;}EXf5Bgb?Co^sc>kI33)mLbS07%r=Fa4dpr$6|(5*u;x zmYA#8KM_+KF2HFuliRgGr`f?m0y!I%kmp;ucH`t`pJ1@nqCY8t<4nm+qFr!?bz=W& zR$ZQHHY5-NiCgU*E%1*_nq%V^hhSl6|23~W5RJLYJP{GNhmN3B_rV{Opp5)b8HR&_ zMXeL~$9tz%&YxWSE*$dqT;k_PvAHAXVMzEcKa1A`M~zm(@bi#Y%4_HAI-hR4hw8l; z$Sx8D6f^$}^T#?&NI}5}hG>ff0K}h3_u_*e$I}EtB}qlCP)X&&52o)ErBY}_!_X*Lm^&elZe#hV~oKJoh_Tc==WkPdmpNatUBNXXx_}AkP z#Amdtoh(BHgyAR;;pbax%7Sy@7tuwU3xaHQTPMugo|L-9Ry{mMGnh!FIOhNXkw|q` zb7~B@LGG6@)DT-^3Lp9)@y9J*#UV8U{LtdP+TOtVt7I}Dn1eIHyxmY5EMh8}!K{SO z>Vb?&trV!&?jf4{E3$y}RENUqI?e*&+zf1RyjaiX`{KGtkMtE^z@7ijFNKfK=rqh` z5Al&}9Kps3{52D=-g-gESDL`}Xg=;>&hA?@Bp7lu(^K|I=WjlPi3H03Qy}SsykV|@ z`Dz=SHza6}^b;c5=5rPL(}O{6M^%z)1S&-e{_zyv^5wQT8{7eq_?IaZg7EqqB51BO3NCZ;Bf59v$>c}H zq6D;i;LwEp@iri51cdSE48uAiAnA;1!7R$>t0}C-Y9sMP44uriy}qWii~J$B?zvw% zEWIBEfB%dshVhhbOQyzy=NbDj0cpqwzmoB>w&e3 z37{G3r3?OVW9sZKgFU5a75bgFpC5N1v568)6l%9iN;KFS=7i#r0KU#M!lhDiw@Xp3 zKl8UYf#jyDzd6&Y6^UFQd;rIk5h^OB24M31jS~hdsS!Sp&6S_e8&>Y`wP=todwnsHez{Ui?tlq z;H#jE-Mj*QADMwwX(4`VP7%+WY_?^`pf72v(hA3xV-Z$Y*T{)dbu?lXe<3=yD2?Aw~L z@mDdchih{Q6KS8KljrL(`u9wR9b7I+{K~(a3+PfOOMflYpOTFLmvLx`=zTkmu12~b zDNY|A)lNIJGF1Xc8P$f>!tElH-av5zD}cPYr4+#e_A|**dAs3s{;^Dgh9%m=={&4Sc`23pCkj3q6$ zzF{R^uB2BFt{-cAylj$_OB&K)`MmxniArsoEJNPsa5NbcaXsb#{zBTp+DfF04Y3R= z;EYzcC@(Qaha!(=N7DjkzH(}VZU9Y3v4HtR6V1$PU0aLm#jyU>NUzD;Z9Hv~k(*ON z$#;|mzY7_ZyN<3+XWp-N;$l*NmDbhobmynntRJG2vu+x%*VQdiyC)S^eM`VAo={N9 zoFRTAxU}Qu=T5Veqx@=m)16BmY9vU_X#+qA%igu0)Q zK5uSR%Isuj;m7Xl&}R>?0lN-^o|D_AFKdH6C#|>HN_Lzq+X{sqh$TwZRAI5PRql@l zT2;pBikb->7Gp4^?^c>`V_R;sEu0v+L}CN{R1<{x2gMP&|dC z$TdH$JR*8;VP@xxV52R6=%{#%z2?x)+i!tk=#vxgu+4S4XlkDvw);hh)Tv}*2!qDQ zxMP&|E>lcD8}bD?Ybttw*0nd6 z{Ta{&Q2u>={BgtQ`zd6rBSdbedc@_;>t2ysF2-zX+l=>?BSKK~ zVecOgYz{syyCrt%{jyFrz|e&lZ)Jb*%=}0L%+&4z5koe2GiAPP!lZ(uvj3+hG;vg& z4TKh@=5C&0UHSU1++XtZ(G)>kFFp${i*?tHR2I160HH(-YjR~EfcBH&fC(^AV-i$d z{~iquXc2Exz^I9zCzlmQ7|8bx1zTOIf9Pz?4C{^w!MkVb4SKJi)Q(kokf5HvqODJa z*UKj6_2x%%M3%%oy{%B9K*7H~ln{kN@^0#31Yu;bM7Nv_ zlRhzGi3}GKwvZ3&#A_rR-?0f%P1V|A5xR2jk)JM}&z8`^g=@K+lXX6>q;2GQg+0)) zLg3V_c0pZfGGUO~PUU0J*NCDp8T=|%zrbs|WYg+fSi4(U;wAGMYG4LY+LB_G0cuBE z9=mGC#{*@?T)Ph=k4}62oLoPrv~Riv2nXkow@tlnNu6yTQy-!;HX3ixeq$|3SDXx) zFCe(r)F>KoZKkrfe7=OvH2c!3>-owg^}78^qagQk8~a5ZzQ)~H;ns)SC0g&i2;*~0 z&`=|uHA+kUE0O#h`FG!n)tnD_J*#`3)$7R<6sazEKKm}YZP%16L2(q$NFER{BAebS zxKcBX#Zs>j9OPwb>o_8})4h#nxhRiL@JZO{{^M$m zOShtnh7%sK!m-7y4ku%PpeNSARgALlgoQ1(c&Bd(3Bwr#zr(#}rXeD3gCQ0k)VVUz zB$7(z_^^W1ESb(wo-;l-Mxvs+@AVVKN_LrboT%`Xq*HQqBz^47UcOHoo$99GnbE-! z?~1)NSFT+70nSb}%EwiLHjn%8+0SNm4$qZhja-c{k(Mgd1r_ufEm4bX<)iTC=RKQe zjCbnCKjU++$KL=_VPd%?HEIs9g~f4_tIyXatUY66xT8KocAt3rFyMBx69`t_!fHl@ zq^5r;6B&(hu>?O=99G@4q@edgxZ38eU!H7n*BO5BSTrWmfd}Eknr0Y*f-X~;qk@9& zJR6fH-!?mL^qlkfV~aNT>7m)W7%yxQ1q|Z}YwA#&V4QtR_+V0aw%l$w2hH%33Y3Q( z&z39o`8xgaGM~Xa^;bLV#U_S>M@oXu`Q!fE0k(dX?xqc!q}Zm>fZ+%fd~yxTH~V*o zGt_2jK^tDjF^}d8X)9#3G*Z}Og%yli9bedAy!t`nzDzbebBsn@=r_-rf!Zb6d>t>I zmID&i@{No|Li;c@1LfSP=H1gDq`J5so~KeUQ(}lgn+}Jf!Ye(bpqhL}k!$Iz!rrj> zTH;O2#orrB@CBp*h$ z`Ej`7*);YaK5(Zkc{vwP^t)_w+NMBx-z-2oxu;yVDegc?BW5}o*ZIrtn6t*zNeVn& zt{SX$iP}VAZ5+0>;u%9l9@CMRV(|vce6dz?0}>i|(-45Ic9HwMzVS{@yv}C|da>cq z)hEI`y90MQK&e2Y;DFKQbJSYLJNtH%7wrQ^!Gid<;9>G&;b?2zBI%_TFGj-cfh5tD z6tpBy)NZl-QT-OVOKdyUx$EOkG@z~HdTu-fip~5W^j@u3EWAVVUGnVHLTQt|Gx=xt zATc?Ol1+2py3;;sABy6T>C2nUPaf|dGFUpYe}aScI(^EKjq?-gG2T}_i(gijlxTMw zopjTC=>@&_QWMl&I-3&wAY?#YPB($aTbJZfoBY^)%N~;_v6~qbB)sW5=6wC2dvTLm zSQFd0f$F|c8W}jy35}TY+L7O}9rgY9G(9koV@78}U(*auXcSpg6CZiAF;v8f_>Ruz z)svOc!i&HHbM6%=SVwN$BAZw);)wW~yoz8Gl-2 zmr|;TF(6KK#cz9=Vy&8sI|>9a>s=A8Fb~^D4=q&hqNY7RQwXCum!#zFM3ua!XM|+m z$l{)gh9ttDx(<4}R-@e9c#lTTvJYL&2akx5KO0--Dj#wk$m&j(>2!vuJy)q`XB;hn z_m+OBfMp&Ez8GLe?yDrpP&@C`C|B#FAP&tQ84|awDKtQ`dI6zWsixyz*b={1N|kwg zVw*p}N=Y7m%p>1^1-HKEy2ZuI6XRepl@Nx`x88Ws2Y7A{* zU}tCTSQ7F5Y{n=kw$L_TA&6&_*1AVY`idJp57s~jX3_NbsTqV+AWdEZ+sretwkvI;CnY=)QU z-X@jJyIho;(sPZ!JfrCa(H}IY%@lrkS|(tw%jq|nKP*LgN|>u(dAzkRo3$Rf1t!_3 zeV;#rUzc1ztT@PTo*I)(lLqtmM-6;XMw{dK}L{qMGL0d9<}mV;Ja%kfBORI#A~xa~}t(%7~v9^hQS!vv-``Bu4h;P>gZt8(o%Xf5r&KY8*O zqu_djxPzR63iwC*ydj?W{2)}#qq}PF*gHoi-Ds`$3czp3;YJ>qK*oJj-({W2)Z*%|Sn_9%@glcA+j9Q^}cG4`i65>N3b5zOjiY{CY; zx;_j4ZzK1E7^9)*(q-=t2e{6zo}SRl5Ciq+6>KS3f%4-^cp2;WPPohy2%h}o4=xZB zZ%0_c!00&iM3CCGDJv42&*Y%s_+q=Q()jQ;-3(`C91w7}zxQD#v@>~(%qL-VAUJat zS?W6XQ$f$Q$GOSCj|7?5x_d4e4x6WYFuhiXGVSc1a)A+K`+-P}wbJP!m;@$Au|0fx zE28RjE}1|ad5TlXzECY&X{4l2l|aVExU4=%#6<+$-@j0lLqFpbU3^!hQ2=&#w)r+# zPuZ`U=jtm17a-$2AnhO6dMk=w#)>X*3fXLN5a~-~WrBY#^STStO2V&u;;5T03!rga{%O*PruqX>`B{s0#&!b#%zRlYFq+ zs#b*fvQc=~{K0%jwd?p}VOno)4h$s0bykWIeC2vlCe5b5^|VH@9<*W=QQUhHIrpKh zbHT!GqtW0>=lofrM2JIZw6! zkbJ~%N^7@#yV8~H18Ho~YO5ldEO=guu>lkA;=D%BC)Z}ls3tjo!;wXPqhAWfqOgO< zRx({-!9ubYRSn;E1{^0YUj}0cUqjce#b~nJ1Fv50y z46`*gpK0`Vw<<^ z7A6uR)Apjqr7%XMzw{|Y9F`DqxvGIBcF8hp`Rt^f=U$m0TgZ~jdam6E;ssNsQ#K5= ziCN&fW%M{>{l!1YaC1yu^v!mhtoFmj`ba_{-@KIz~*`1+|rq4+o*w?i$>X&~7YGi2X{$rK_yir{GIq z0*6vOH7=2z3*zWnJL#{nsXOYQQ%Z5fpsm))v&*XDO6T+&T(wYu+>9ZL7CX~;c zXl9j3#Wt@&%xn>RsEj{TQp#bN+jKIP)H6NYa~435*7dy(l(-6b59NR^$;xA78mP85 zI%^G-xg5`i6o5L%N_3m!T4`l;HnQA-P7rw2&3^@D(hP+Upk)V-N44dI3F8FP~I zv(OtZ5*K;0lpNW+6A@x>B=!&-Ie=idQ0BRaNPGgpnHJ%(;bO&gF6jVWetn2AAG(w%v*seNya z3!;y|2m9nF%-{KgSmBi15Pu)~>ZFzO5(nz0G}ziAc>Ido+=+2qwSd#CHM zgrp2!NJttZ0c@_jSoP#6?bc@le5mxFY$OQCL{z}$gbXH{g*Z)GZx(8d6@sJXv-!+& z*o7A|By^r{wHN{A+eRL|-(dtVrXpeb_yxxNYf)U7XLVA?h`zdZOkJ)Wej!YkP9M!;1wms2VtGHGc!O>c&i-ito%VBFI z_cqc25Ya7=+_F*NAwI~&v$!8BeBW@gq@r6x4l1+hHz_B$8WKpUcnO-V)`yoC#Ipc# z`&V+yGKqwR3V;d~bywTZwLERh!C#ok^~V|OF)9-Xw1Q>5zeY2dTWl)>qTPfO0b<(hr1p2b2JxBF6c5TYM-P%+1Z&7diSy-x7KB9QgUO`p_lG-2#^===gZ1%-`;W(bisz-g@ zJ51%E1sNk|xs_rdh+ibrz96vO_9-RLb2(Y7F0JQ@S8&pTdO>y!l>xCVGASF9KInCE z$eayiAgr;I!r*kqSMLP)2ZmU4u^(E6WUGLXYpW8v&24(c-rV9Ccz4$4@3voiNTzBa zi7qdVv(U3RrkLk<{bEM50Wt;y$;;@y(9;S&!n55+cJ6S9+)nZPwH9qr_4~0MK8Zi3 zDFiyh=A7hO(;K_lQEmVMIDiON1~fO8ZsOn{ETUViix*;svx`E5nA$|=1jGirm6S)e z6BX{nGlNM^4eajd5Qu1kG%kvT=CPU#2-qTjA?y_sx%@)>c5nyonXEDLkM>vG;_!m; z2Zi7?yO8c*(GKy+Pp^!!}iZjdjy< zukd929W1?6hU9(&5hZQ8((SQP=G z7t%D}u{>a6v0&C^a?cu3GE`&#${X~n)(P_(>{p!cXA8WG8xPPkj#vYw3MGuHorVr( z3BJyf>KrYC-L^9XUkqzQLuhdY?;fCM{e(9Xj0qvSa*Okvh8> z!JK{coswTlYuxqfB6w@1-v0-AIhOci;wbZ$W>HPnY+=G#9NtdF%UGkzfnl zN$8=9%+2Ppcmea-y>|~n%jky(kbmwjCFotZVd^9gPoS_8nJs^BXdJkbZ5aoP^`>5GEk z_ERjai@D0H@f6Bm4U0l2hvI5mIsrcULi0&god;`x%B}Imm03`y9ip$q$_v+wjIe zbqx_-xVv*Gtmf4dy`hgnu8#2aY>&`6&bpy)T@U+>{h5nwb#2S06x)s=*CsY0=6N=v zb?wM{f{}2)4s7Ske-<6M?LM!x>L7cJ!&TGsRqGW0XK1UYRn~mnll6>nBugKYbO5`2 zNq&MnZUx~W?fblUDIfQIdPX!Y?YIi`p09$VXML8*ea};~IhD0m)k&=>ha%c?#!9X| zi{D+Q@R04n1(4pCh&+k!Y~g(@!Z39!Io#`G?1EWku43f=5dYEED$~#UjqBi-F0jndr`f=Gun(jX-gg0vvr-6n3|C}-2 zF&zAa_t(!_bFDe&;uXm;UN0n+8}yyIb`fhrtiwN+I!~T`B53P;VbQpp7|wit^HUD~ z*mB@uqfg!QL)QelvEx&MNUKxr_cANy5Yn8vBkXY=(>MB{6u}W7T z?`mWrSC}&q<|R;Uvw9vRdZ&%T3)J#HqWWbq*&8dO8SyEyI)&V6HE)M+x&N1zbgpud z!o%xd)Km7px2vtpa1gjBHa!eJp<#CbP-aC+!*IipUGUp0S)YKq0Uor8_{0@cYeM8Chs@Z+hpnI)ZJV~A4sAvsMh$Y$ z?!KJJ=G}S7CMkn-+qoUbq@Dw3m)5S)XaC`zvsDuBBji&b_o1TN6yZFact%Er+p`1B znnzW6%Xa!}ea9jdPx`w_YwhQ+ro`%!oM7dC(5y7tP^zwt4d{j`#jKKN@^co`>8aiU(64D^b4>`k@kgekPuo>g1L$V4}u3TxUC)7C{*1 zj1GK`8IBEmp-qy!9hsA>#y5fs+YwDn9*Yi}4`)GG107*Owq#hOK&09R`v4rg-F^NDpyey?FwUU|g*c67$ z3J-F835rUHviYxRGaCkpW;!w}Aqr=X7|avU!q3U%P`nqwuOOa}BU+@R z)k~(MgVHtN3Fo%OA`FBAlN8QEX+xQ?E9&8>VYB1&u*uEBSfM1CfF+gEXzSl3gL^QD zpySUEK_36h8OVTg1~i|3*Zo7-Y?lC}0`x#h?msMqXY}Cb-N{*x$A34(0R~CXJ501Y z2F*RVZ?C}5LN&aZ5B_W*p#dv71%vec-xLBEcPh*>wRkh9`K^G1l0Vdid$6ZaIeH=Jw|Fgj)3w*7wZ1`USsw0$mu#-lD@t05hf8+}&@wopFl5v*_08ZL=q@1gahb<1CAIK5^`6$Tp=R<2c1?9 z5qPYMta{b&JPuYqr}2ESxxRS8`~7>qB`g^k8Q?PtG3n={_E>l1VW>(;Zd#M&o$og7 z9j7?oU2sRa_ELDsrqc`tM)wgE{E>pVIC_qWGpGo-;rjB|^TMkHS|yFwbdPjtx}P)L zeD90h>AEpO`eWupfz*qr5qX8zba^jd-WyD2ZOYcE z*pp9uh(#-(`fz)8uCCf@M^CTZq?HmK9r~cQ&qL~K#5cc|;;#*6L^>`uDpXmIMqtG+ z0sb$$O+%&S)=+3P2_90y`qpR6!vjK+H7e7K>aAgJzWG+)x3hIl^fGEd;{j^_LQ7aFOk5C7vYaMrCPMVbZqve88G!*%2$Ucrl**BJ`CuHS$Js`b{7vgP*X z@_6ri-(;D;f1}@Z+BlcrsjeZ=D86kx1%x+U{t@2BSe(22g%9fpAalIA9*uO3c$~HJ zYdSPE(jQW>WFk3aB8`KzVL`5`fNGUTDJhjR{D5%j0OVb{emxNn-h=-c|M{eBOIWqQex|ageu5ky+;a*-m#~9i>gR7R_{=WiPAz- z?6(`Nc8K(vJu1dou^@nGu0ExbDcoauW#(!uq}ymwge|Z!nnAtS8pAH}W#T&ybloxt z0A#SH$5D*&n1FW4t4-ly)Z(M?FT~;;x(^IM^7!Rof0>$rG!}A4EZ+CIiQE`fSU;nM z6Z4U$mb)l6Ki6zcR4X`Z@;trpb7$^*-+-?|F`d*&e+vpgx8l!q11~>lN+$}f0&!Kg7 zs_#!582*Iw>;ShrTPh6I^7|cK>@IXDJe8}HFaN_se(dz+f@#n$c;MznB@)gWPI4%@ z6jkcrHwU>_>I6KLP#?di45z7^st!P%ZH;(EZM z6CQKx7nRI{c9dnJ;rpRr1QI-vr}Q}-tCgt?NX93I-&AeJimB*)()aJm6er++7MErg zXB&x5Dx~Avl*Pv$2c8YdCm#(=y9Redskj67qY8u?-G16}v?xDUMoN_ge9P=A>)Twv z>+Q=_KolkQJ-3w7j#1V{CE|{A{8n$ufRA|hKseq#5M=W!;t{pHfe-DcAA(nhXEf}W z)grvRHY=A!zxd6Kru<|0&Bfvuu_h;DgaH(9SakM96g;slL~p57ox;2FzSGAr-l0@v2s%>yZPdpv}BKw_mnW2u!+|}rQG$1Q2yITpdSRPq`qMOxE%8j;tarGAPu=c ziFry$^47PX`1EV3zGss7m_Pm^=?o5J(U;G7hCP+G+C@T^h{$KW{n-;7h_wgd>dS!p zs8f$H=u}eW;gRuZoHM@FE0}+t3w{1(WV2I~3`#cU#Ryo0FJ5~c3gN#aH}U}iOFJ65 z=8AahbD$(vR^iyZWd(i(5fQj-ISai#d@n`AVY0}*i6;@kY43jX92`>@yctSi|M^-^ zIQdcHaVvy7z{CkDN0}qsxuC?&X6CRB3*t*@rbG!USTng%2_-rWo%Xi5qM|X-RH{7# zQr`l2(9RUb+(4E}7mZtbeV+j&-Cv517?Z5X5e|D7nYL$i!SRuw8l?5Na7Oc2%AUF1Iz0*tffrbEk&J zsQjJ)pBX5|#=ql9a~!`GxVn#s-e07?`L%}Fw|9u0HuWP7xNj_x_ER5A)ddB{%WzZq zovC&fT83C+3^1hzKxBNKSspir2pVIY-Q(u6`X$C_MjcB%%!D)~rcN=f%~~4dqGwC@ z*K{=u*p#MwKhtXFtBlKaaNMo+A~1D$kom@*PoL5{k4j(k$~zBla%knsW36522%2tL zoJi!867ivXUm6cJk&R^CE`IHYd3~RO-Mzh1$_!{Dh6T@n#l>g&#rQ#r{fm>IECd(K z_+uAW#N0OGJ99M!DZ*%!yJ>wfq~`Swm=K?}Zw*!7#xZ#GtQa#|**D5&REE<9g61Wi zcysZ^&|Qp0X?0wBEyAPjsL0QN_JI|1WyNiD`TC(oi zv6BrYW7CzERfk0sALvAxF0iyq^|WW;<%4;iekE{dD#3@i7^llQthEqZ2$-v@=zn<3 z%5y>ai|w!&rA*Ywr7+OmfF~kDc+HA$0(-XtWplpC{e$^a|F4xpRx@3&capCxqzw0CnSk?oOsTIBW`FOTymU|$KFBaP=qBgKZi$K(@ejEaxxSN|xr@_uk z{_wKw z*VQ3z+tXOIHCVrT%nUrvCoJ6zw^QB42?L$J)pKZ@#J(Cxpyw-2X+CjUY@HwO%E42x zzXudcif?8}tF}K-FvAJDZ`rSU$h*1VrVN^$F*qijEK}~yKigk|NfY&Lyr~rY3K!@h z_^ru_oyXy#X0}x~lHmjONS2r?mxrB%bg<}TiSBE!qhfe#$pRJ9=pQ@Edfj(wuX<&m zqYKq912k`YHGB~v1O&LV&*SfVPvK6>m zQ;=#JG?%2PS5#Vo8t#}00VeqLf@EP97NAX2lkndqrVN0qjcI8U@2mwxec{N({dbAX zZ-1MPBpu~qq{q>`h?&E>jpb7Uel z02X2}YCfyB`oyHy=9ls5tll<5e6Dr}xYPUqK0riO@*oj@4*9u%05COR> z)V&EfU}WdWh-tjQa~>Udy56j7$+< zMPr_uL0bg*yZ7xQ^t%JOO_U>p3-KU_QJkZqu7w!Dawy#Ec#|oG1U<|5aSAd%oAlP_ zyn^4nZ4*JiD>#RR<^hJ--T6k%h(yLM>e|=xJvlVTGhBi`tKkvUpGm5$K5<5{)0@#S zNL^<(h%iRV;ep%x0Qk^E0xT$7pqj-S$&L?n^NF8&-*6S!0xb^B3G?F;f;`o%7^60? zM;o4kmMF2v25o+y%r20=)0a~WD|cX!#XTWsk958`-s(C<;+bp#cWJEE_mZWzOXd#T zTEaTAW9B-WYtTrC0dSiR9GraAfP>RyL5rA~+|qoX{v&*y2=5=O3Pju~Df z6SHli@6I>%N&WhF@b9^`1JOdOXBRV)+j!m0V%kE^mk*CMp$ztX z!;OAOVOLzm+bQm-eI63qVk5*D%V3;gYrMad@!*H!mIJo zz=7!<0M12)RGg1196G=YS)GgS>jxacxF_6miO@XzPaMZ{8l<)`k?!8)Xb@ID%9u;i zfS!}BM`5eud}AWLlacn25$BGX|~F`PLHba%Xp^v+0~KPBruYC;0p|ixJ^4fSc{gc+;#*ftK=|h zCYFG;6N~&6>aSy1Q);28G%o9yd;UB2a#&-#bebBEXbYd z1GSH~5m-RiVqEa95BiWkc>Z((OaYLYYiOc!I*ezVBYtrDb+itzk<6mI302MN%*?9= z(_vbKNK82zvgW7Q#xTNYGB_vD48{hO=0$)`CyPHQ2Jn4K73fl9`&%Isr`XgJZtMxb zb#Q<)oh~;`WYV@fJl*}&in3d*XY~&q>sXuiPqL05*<7#^oVw*p-U){^{XRD`nG2X< zN`0y%PY?osgocQn!gb~6;_;%^DfLxN2H_~{d03~e@vBS36J+l@fQojeAEnK z=RjClgu<-MyIjgBL%glCm%n}61~ruq*jheYadoxts| z(8-uR=nF7Bgv&NuQug2nPxhu?-4>9y;UFLOZDeHX0YgrMmRaKKh zdZ|0lfd~$mNIXbB9-_}80X8JPk1E@|FXr%3YV2s1kQ_0e<8U4SQsemp2vGDVRUrVA zrS%_z9oFwKeAzB~OhGXnm+*~1S4Urjcs=mX@bo%erpds>#JsC0DWjmF<$;G{Yn2%h zDC={1v$PFc$Cf^U-{Gc@^oil%DukCZK)jw8J&#&J2>bZ4s%$`E8wfd z?PecWYnyQvvBun=Zy=!9;Pa*#(c|ap?_`K2;H3--9C=o@Sxd8D_AJTfqLu&>+;ye@ zI=>hw;&dylZf?p0x2<>#Q@?(@`|LvX4VJCfWx7?NW@hUjW|lv97LC7k(vaa+C_&|Aq=j+uT zOR-oRgK9^fUnz8|M{D6oz_R%WAo>L7n<{|1inWTcMX+DwkEW^sw-L3Y#PG#uVi!-F z+zy}pS*>YN+Mr;=gaeL6kHW+2g#Ib>Q@v`2d^J?;s-_PSIpUiOEr>66X0_dZfhDrq zVJ;SkyxHt%z8+_!r}y{tgp`yHjU8E!+N663ZPYo_+K_*=R>{g=rIrgOZFiV0Hx1GV z)_KX#V@nk~bB{~Z4~GcvBKLeEZ{oD_^H7#)`Jp@DAr4Y)zUIS)GS}ynJMl~=Adt%&aZjwkcD|~*2KYqb(^l0 z&f41A!6liWSiLvGkcdSM^RB~!4f=7Z9+Ogm^x=qkA`S~AstO7U@Dp#{%o@|9QP|Vl zC>GARrk0)yVeN50d;Xj{zchhOP&gVnvvzR_&CsHd`z~-UZL$USCW2c&?;ydeU17Exqe4X>o1P$0 zXY9u~1x3XP`-4Kh5nA_?u*!RR+0=Fa-A54#$DOJ#Vwci|8hMrF^zsEq8>2&8SKod(gO<-p zcpYkGX$N5i>$sZD=loLp+c!FuOO>F!^!W|X*w@dS_z><_!sk4o$FIpOO-p zs~zX{EolvQ_%sstLA4;Dh?a3Xjp|UwJn!GT0#55%n6HX@igW z0mz)xntM@N{akJd(DPkM%-b3q`M#g8!tw{!Nph} z&x;?cif%PKsHb$)-zjNn=_Y{BGitKLUq>baaKM2T@~vh_#5g7weK4^M+N^@$S-o7^Xv{=u0SyRIUJn-JyeJQ48&NFCLUbx?Uv~W-H&X42` zR=G{U($<%(lAbQl@f-q0)i$Su?C9ugiOi`*f9cGTz3pvf@VW=fGsG7h0*B)~W54r| zWHv+Pq9VQ{t&LIKG+|rLnYp>oP^Sgr<( z$BOCW6RL5IaI$q#^8pu&V~U1~vJEz1?=!}Nf7Z=;*@!0|lEFqtkSj7OiQy8J>DOW1 zK->GEtt#m0>3LWb=>x1Z1mNKj#((B1eeewtS5v0|kBvz-G?q+HC%%WdkD&2Mua*u6 zsf-Hq@Ojze5}kNK_g!VDwrg}!VUL%cU0sKoB8!%h@5NKeL^FtZ?W9LDMIT81fJtID z&ZNLR6ge)01}7`%7w+q%>Cxa;i!VJb0Z}cQ5J%p9Zy^sf@LV)9yEd}ib90Nhbd1f15FlT@wy^^QO{>e!aFEPDp<~vZg!1+~X`#E2$#_oaF z#VTXQgCWL)gM-8b7lFBpi&r9E9%?CUh8BmwJEZ$i{ys?X0JU3`fds6VIwUZW_z>Zh zd|aduO3X7NDXD@(3{MZ&*KG~grb4i7%YH5m6it^^j7yFzFvteX4sVQR-u03%%lB#qI9t8G*j2J=hJxrNQ`T}y)beY=TX#?x zuQ${A>52`wAi9UuNIuc_T&9{INuZ^N){DVdI_1=R0q;VB`N2}&1MI#%IF9qNkz}+f z7?j|nHb92#s;hHybnFdQ?A7~8pFQzqTwS^4Y`3SKwPc1NlcoA8CEYPE#X!4!(eLun zdft446eVQ`=ZL@P#U}M3DV-Ipv;g`q|Jw}5+=X|QmJWqh(L`F3!&=YIwhFQ~oAz3h zoY!KhFefG^v?N?EPaPVmt$2%{00R|ftvDH7ixRz-2t0P960J{%LZHrK_qBv@{AdFg zXzs0PsHmtYFe~FE!Q%gt799FmR3oFbqzY_yLTd5ebj5oE@(ssKG4~i?yeaSAts&tj z(JMlzBqAhj3~#=WPwWMXYCcV$wlTSa&9)@y8<0+e&=hrf$Ol=lzFJNF(F zcK(u*YFN)oO_T@z#cDt6o=(MpdJA>33{xa+5Ir}WN4n00{Ntks0qsaWHxB?ZI9y|I zQS$Qi98bw;%}wYumcF>YKy0O^lDtPK~6LlLpsMuO)a%!<_NnS$u1aQ=brBmV|0|oxh7Qe5qo(jR0;tj8DkGT zMGy&2qXDW?aUFINSs7W`Voybj`n_j%Q>`t+-zc_msi>$ESQeg<#Rv z*Vm8rzl_&XB;Yr~tU{0qL({HYWrqtyM~61Jb)Zf&_(4v{&g}(k#jqXY;|gr>z`*hr zK08Is9yc{Ej=~M8yH(i-Yv>Wha27fB4t}K;cU(Ic+Q-{x+Rq;ZJkzibLM0%4m;X~v zvLJXu2p!!8spHf9qfhHIaeNCNQnT#Jsr(XWq5OsG&Tz02h=}MQV6%XdbRdC`=BxXy zd#Ffonrs|4w_?ZJGp|XAg$C=KEyG?Ww7KsYalAf=c46>;jssCwKg!Lf7CU1%sDG!) z*A!IH=^5|;vMntS0>_(qj5CLg2H$gzwdc0K-=7|^IaNju+T{7uCIJ-=m!~XWZm;+J zhu+|1*67yQB@J&_l4Vwi-!)H_s7wxEI}%r3I&n*Ze`O;=Z|;{Xt=wTwTv1fqx^7@y zmJgs{u{OB)gKtIl9zNSku!R&o9+8s9f^4f5K_Mp(fSfeZn78!O;fIgH_X_+}om#GI zI|M^HA4l#a0E0vB#Aw&MD6IsIcgn2jXEB^KnEaz!b0p{A>^J+Ko;V)0wq+1UtUMZ=*9P)qYmNqL(fD$Hs3j&22< zsvTqRilB}s+ZIdD#66y);_1^0G&hRtu)=l1&LG@CbE21dm>{gH8Hjy7X5zEehgQGUM)$Go2Pob`&S%C>}EXN8-hP#jQKJ0{*f!X zThaFVx-46#xtT68afaa4*R0gk)Sj*!jc|v1-{zatSeIkow0&sz!v#eKoKabZfEL0^ zB}-l(i@L$tXL3GGrht9J{q!q~LuC{*EamyW>FoKD$^mWfZ~WFoJ(4M+RMj&98yS8T zI#adLzxQb0oyI4an(l6F%UztIBlEQ0!0UWBvhOBh?#3=Gth{|W1%#8OzBjW}|3GXh zY_B{8#n=PHwkOqwvCID%u3=&uoTi>>0*_mlfgS@diUnRp};A5>}K>CK_-~+unN7n1+r`7@0#;MUiP=Y&! z`9|QO=qFhk&`uL%=TJXBfbBpn(_Afz~ivpCj5rV>%?v_JvSmsbX&8uF0N7(`UwGsyx;m^t6 z9ab+e{W7u7vBCHQ#fD$r`v-Wv17lH-z+X&DkCXjDUa2tPw73YQ4gR2H2*F$M7ZtB^ zM4(sUFLwFgzYw?q5?BAHkXbsC&*1>Qg}El%h9uQ5KmY?}%5j6C?7OR;N)0XmPOP1) zE2^%puI8We&+0TWJv}|Jh(%0dP)}G{c|1N_b30HW%vnWWZqgwM*s5NqZ_*}N^?5%7 zGddo|@H=F-23^Ac6`85W{%;{O*bhx~j%Z1>m4h|DkYEEW=uy8U#DVVUJ6GZlzCzWh zGQ+&^@CG_8Bv1nNVfWhy{MJ$b7b8{jOM)0=xtb|LPA19xa^zS|5?^XH2kM<%>}KwHlvG}w2K$(4t=$tTGob>^mFV7 z<8m}MMl!Z`>K3yBPgl*uL&vXpqsd+!9|9K8_sd;e(UMaox>6h*M@PQVP;>@fR`K>6 zcvy_`A{j{u6u8!20G-EEIRadN?HUpZdr;7?3HaQ2%GrH8Gc4B2V@d+;>51K3b(cdd z;9&b+g*eCuLA~K{t>{(x>p}`?h2E~P>f3f0-Ov<)^^uGZnwc12K8G@B3R7MpoLW4! zRs!|ZY(VcD2c)$v;B}-s_&l(ztgL#5-}4X-3{%Ri_XlVWAi)n~pXpV%N_13S#l{vS zCJxPf-TPW91ggl7)ZbyuKE=-FaZ%XEV8}Zui)J8~eQd2@ZEWFcQ`PBY(IVr2)Y^u8I$2%o7S5 zLH`b%Rjrm9)ufdSC1x8oxs5+9Ymwb+`DK*M85>ez{Vk1OuhK#xx!F`IYm4B&C$3VdHmi(4jhU>=la{rJy+@z zge2Cdper)@4%;k0uuE0!S{jU5E{$UL#|?-}PR>V80Fmx9DMyuhi{1++Q^=q|A6Bvx%eklsNV}X@RgXJ?# zoi9YbUx7jkTk`}AJID=EVX!~hmU^^}M#geCZUddtM2@o=lq>4(N z`Ps;WvO!*VuCysPzf|ccFRbsyG1d@OQcpq$&Ptevi%Vr%83ayc>8MPnAt9OFf6H)U zXebhR)X^s4-cU^dl7mDLBG#x01Er51KabbZBhRzd0do$NgT{os8_taeEG*ZHV@4h{ zD6YUP=LV8Rd#0UQo@LXGbDq{dDJ?u&N(!`G4x^dlt55EB6s>pz9C!|t_?W@z^(Y9 z#^Cq6QaB5!+XXJj<39)(GbEV!1KOCFjwq-9xl46TzxiTu$ppl zo^JtD?L+=Lv42KvWg~MfwL6|iIRjt6K6d0HVX=ZqdQS0vGt7;rrLQ~#bef2?SO_$H>0pDU z`;!fRE&q}xahe3=-`ax9O%&Rv2`#rFA&=-69=!AY@YNu&!v-8MU(N|{KNP!F3;o4z zXc-KA0S{mN&}vvqNI^{KK@HB{Kh<|q@P@5rHQ9?-1gZWd{TT8e@Rlq1;>Q?hI2L7L zQhB10`|QI+6Y(griR@#`u$vkbWl#=06=Jvx&pjD{xE_hc9RiLHUpruFbCV_o7BnGm z1ILEQd66v;rIeEYLbpxT18ZAx_5f=lgWKied?wiC+-U^Dhn(V%recFtkn-F~NH!(B z1RENfwyZZiNU#slD*6=B0TJZE4K@0@4%r*9#!{HXfc&DnFinwUAI(ypBGu)Ug!lVj z|0UQKH!jw0{7C~2mRR+|*Yb=xwYj^!H=}v3qwD(`YVfQYdi)Jw0Tr;fCDP{P(U9mSk)FF^R zeBrW08}BgZH~f)c;tqn8AOQ&Su!et0Xeds6Nm$e2`RenkZ1S>Yu;#wSco8@%PJUrv z-?sX$?X@@-q?vW%b5*R0h$sXCc^4b92ZIhETea^cFX7Z}7l3WSs<78#^;DRf=g-sl zZOv-0pR&6>Jd4OcB|(Qc#dMf`pb2ZcT4V1FHBXD$o2!d$J*SiIJ-KDjr}TVlIcg-5 zhp2eX`J0jOoZe&{HoM-hWJ}v|@QQ#@C5`_T2`OpbPjf%WkikC~27tVcV>x84YY zT|Cs^v-dNng@*380&NH`HVM@=ZfeTfujj9LPbHhYCZ-qA-nTu;AmP&#P{$?ss*yC9*fR5a>6yxQ<38yw z^Y=mW)1~PfC;!)B_U-)(M6oDAeTSVGu#xyiqNcYf+ud8<%TAqRs9_Uies{D?1LzaL zfE+|bN=hvzip#(L)QhI}=7IE*$nAd#;DKUUj*(fh5fV?Z(3<$c0mEs2s^(G#vUv|1 zm{2VxLt)VD5pUn)PNJx}EJF@M& z#$EVtz}MnI(W9xMp%HK#I*(s9J|A*~AN+HrT{t7ikg2JmAwF_HRp)E3Yyo=P2|XR1 z)j@e7t{L$?_g`#Uk!{Wtt$zUD&IYfA$x z2p|%C9?5do060C5BS$07T`pb3JJ~8S4;~LIv@@@X5&NPLF@i;;eoZ)xWM%4QA42Lh%lC74*OH z$!t?^CwH@ButJ*tx)e2?Y{LNPj*n|^l_5xM-pW3V8bVLsl@>gJ1V{v!6?N&cd6$2Z zu>0|7w$0xduL;q?*CG9QJQifS%|tQageoHL~yFAHWXoKJNkOe8{B2jc^AR@4>E1 zfbSRX#d`8rHYp35h9+9+HmHA*S`auI&nW7Tuzxm00r&QfLjG}rzeo)c+?^u=IRp4V z8wirXU#L6haQxmQ=0gl{V(T0+^~irWFoC~#zani;ahHTsn2oU@ywL~E;`=f{k=@(?p~{Iv#QWGLVQpY{*n)_6RylP$r)77o}Zp8dT3 z=^!yN(W2Zk%$=mry39zcSc`GC+>f+Wr{SB4uElDGIM5$$24RT4^Ez30cYL|!y6k`Z zzEmIQ@E;8}=)F5=mzC>_OG@H_k2y~xyFQSMX>oRO0lGggwO81*jBJh%N)0cw0D0!~ z!vG+NcnxS1c4O~gk{EO~3YGxf#b&0G+y&QO@WHdYi*F?l5Kv&j6aPv)j18GcGX|0C zR)tVLD5=Q^keWON+p4O#8k*d(sIsLq2Z1Ykir@JfzFwm%M_&HIux5ssrp;mQfQ6Hj zDxc%Gca&0LS8wu>OLq00T4Z2gV6*_e>x4v=Oe}xO$lp-JkEL60vY8BWGUERYMw;0MbS<=a+g_bHRT`Mz5uS#=saKkG zz*eMJ2`UlNK=1y`1}G424|-}BuQmo7P*wqE&T?BRQ_Qz`r+}FT{R*DwS^f+0M0|cJ z#gB^=X?yg1XEV4JRYWBL17_0JJZ_YN=}D_F&wruw*ZuPrs5JAy^c4%nQKZ(^)(NZc zs{=UIe%D?rH#`oriN%jgB~`P8^Qz1QLQ>#0G}x^5{ef6(b#*eBOw>dCzAwVWr?p48^ySR~#q|+?E)WMS{&wv`xK1DzznB?EzMSavkkKuCG zXdQ{3(;2K+my znM8Bq{)f&6pn9Z{_YRL20GpG-w4JB-|MUSBfsdd>C52T$HP3XFHQ%GuhZ6MU(3TGP zu!B{v*~FA7UQG)=uu`ktWBTPD;A3~jEC)=Z>%`g*CcU2YfHncEqhjx%CgL;DN*oxR zO}p_p4u?us-lVu~poav*4e{TeZ@!Q1cTY`4!d&D3c6;sK81EG{m|T+$=C>9$A^Tly z(O>K~Iav}yJAl({FF|9@ak2H0d-t&HiQShXpAcluXqn#PFCU;|&<;~?%Tt&9TvElv z^hUU!858k2ve;w)80!inbUmM-)oU{i>L7&Z65b7eYlj7^oDISZE)^wxfSQ8x7wAX` z&{+nv;{YFbw%(a~9!m-S9PRv##F!|+jsNHdwm&@rC=*lYo*i~u5n?o24iHm+m{$*$ zQIQ3+=|(YI$%!Va3RD?67~`#mQ?tKX69^w|m>u6&akIoRe%IDX+%Z0+@R&k#Vu;MG|E0 z9x9=5YBw*MseHX0B;i02&lbMZYxyA)C#S|IO{y;6FwLgZowa2I(*jH^Ldx%;a~O~C z)+a74O%cGOl&!YKCb>2g4p0@~@oI6kebY;2x?b{T<-)Ds{Ob3T1XMEb_*P_OC|vPn zT^_yVq37+5j2QHRobK&CLPy`zI9!&hJ`Pj9Me>^G^GGER7^}2YBI0AyseN&NNDFwv zY*40=$=qzzH@MFJ`1h;W_u2K2ccz~BHci!b9Q;O{$$r--PfT?Ld=78xO~NBT6@&zfxuvDv2cARc;1`16Nr^E3eQ-N(3P&jYg!u6T6>1*~NaB zE5kz3Cc}S%HqUE^EYG9)SnLH4KHl5W=h;}pJEX>}F9nlli=C#MGyPRqoXWfMR;dRj z#K*?Y|6`*NB@518wY?U8TSNmXLVOG#U9t6$7z>MW2l=B>i{f=K=5qT;JQ#$FL%8uY z4No-s=5q0N(0qs7vfzF}DOPU`2M5QjefQnsK?R=eW&$hC@cW`K)E_{A8<9&(rXluE zL|$ZN%#jeld;Kz+11=aS2u%1tDqU85h3t0F_o_a$+R ziO&O|TWEzr%9$t##&tyf-0K|sy74qi*t1eu&~-EJp*`w^)$f!I4`etJs8vPXFpH+4 zaDj{|1l8_-fI~P?QSsh~_=y{Y;e1AbXz&pQgG%^WhyQXXd>&&^n`#K!`s61qIy7tG&~)U7*4+>2^Z>;qk{DPRpSQfN^X9m-=Gn z_lrpCzc3Q-vzdAUWRdDX% z3*?o%>i%#ll+3ttQIY?of&9okm)~}U#>Le&@nh^c!;&Q;U)^w>{{jpq4wvyK z^ejA;e{LZ<0S-k7Tv&hIb3b{+@U{DHFr{c8KYm?B6%pyhS6(RKPpA=2) zy|1`>w%dV(r_!RTDnFBqtQfOjL!74kHVm+(l0AfI?<&GNR8SBX>m|Prckr&d;M3dh zfF@id?$xy$Ia9yid5*FYE%s1#!z5+U(a~|0N|-LWreeIP%jx>nt5>?hEKDKO2<`JN zC||I5QEOSy=IZBo!k_h@b{_ADqTMM}HB|_+ zUV322D=tH_V98n~;v7kC{sJz>uiu@=lkaQYVFfz5#qmLQz6Mm+=#q5~KN8kAI?*ap~45>uqz*YbF zAFVX;3IGVzSVEC9w7`PQK(l|x;e=NL1WuFloEOy4J|3qU_g$e70sIERy`a?`h4%S* zLr0V~Qe;q4XHLtIF1tgv|F@5Lx3-D@H#Jn%;1CX^Qoc?Wy=I>IQp+{{HYzGCF)>ws z=m`s#4g%p{Xv_kh$X=@Rh#h{RItpXsHsL81`Dw|DipWC)GI(gH1)n8tXtYJCyBOC&r!D4jiGgD|3uh%gkl=YU8O}0Y4%=%0 z@wEyfI!QkrqQc#3as%+LvT!eyh;C{5D8RfmU(Ww3-rOlYJ-tvamP{*0S|K7*U*_r5 z4SnBX|0Hd>OOGPcQ}g$4Q@h3iRI&jUGy;j@cY~W!*`bBKOrz@oJ>hhG)`)DNp`jyO zo1P|L^}N28Tiv=E85vpKU62V6#`a|L2g;d?wG?A83$iCM&5KL*#f@_Iz-zkKEiEGR z_0B<|sHBJ1X`Eh$pqxN069f*{N*M}gV@K71en!-=%`J(FYCTPwX7vfhe#=?MG3swmTc#mR0Gn^)%^w2?ks?3<4on2M*MLZHnPPA(6-;i7$-GymZ{XtH^ zr!5HY5C4ZICFy?xAAA3&@DUHvV5kiA88(2P=R&yh%lj7~cVgt_<*hwNJHNZk$#-1Q z@c(tLC?=G9ng$Vig)Et9A?zc6X-sf-@V`VBT|vvboC5R5i}h-dMSKqvM?FA}j|W83yd5!zh?+O0ZJT69;+TUJ=?2lv9q;wTXf*tJq& z@&}BznXM`6wO-}9E3mV(UsQfh(b71Jln44L1T->f;h=cULc^w*RFPC!%faM4??Be6 zfE@{y?l=%UOpw5maV*VyF2=o*KI~Nia?|n^dS)Q&u)~wg*50d}CKCCnqOeKX8+{EeGB03~3Jm z4|hDSBS^viGlj1)oL)e=5r0%fRFqb6QCpX9kNwMM5#5yRLRhVbml3l!CuN>&>?kW3 z(4d$q04{C|3>y=mh1EGuR_i`DGjA>|91b(Ny;)dY+GnFB7nN4>??29ZH{}}?26DgV zPhdSXnfballwt!09J(HFVg)%ox_+qpn}XhmDu&g&$7;PmpCtE z846+CAyQCSvC_{<5y%fyEtq)x7}}2|;^-`oMPd_TwNI;lx-@g&@pZHS)?G}U0F?}z z-Itv}Qf4Q`1(A@D(8`vSIXoh!^TE#@G-4*fU?9?XK;8ZUYQ#35O=}vC#&s$0_PN7{FuxJbKf<@ zD5X(Du&A%rRFFsbxT#GG*?u<+(xK%Q0>i)9ZCfk+-!}}E<>fJ(;LMEaTEo}qFxN+8 z<4;j^nTX_<-XKi**B3WLi1RbnN+3j`s(n78&eoLNB1J^>ipx}S+;zN|IZQ2!hL5ay zL1^p!awf>0gAxnMNCW!|58zAUU-BM_6Mwjd9dvpt`Ok80UsMTsFrgA&-@p38B12Jrko!M&KfG;!(@AfhoI59vwaLlprz>1(b5T)H zXaIFwXKtyRyCJ<|Ze3`$n^7Av5SV3-iw)Ma} zTDyDYY-a(pOCw>^gs?DbxzxFpJwUl3@a^U{5_dwH%!Af^jF%I>!$*z?~J zzn4|%o^x16WslmSZwD0oQh>=ZLIG4Cf_4z@2U<5LeN}E>O`h4k$EJUPyXrnK^!p(B z!g+r8+vzf2uD=DY*1oM|Yy11fmB-9)qpLGAG=Kx0y55q03D~=8AJga7f_iFyc0L1j z)a*5mO`5as-T#06i=Mf@6o(wZ6JY|LX#1M%yT0i7v*R9xkez=TvGSjtXUK25b>K8# zUf#_7|Jm2pESxdpXO>yDa?Y1$vy)ywc7ABP5wY*j<(H<1r>9`kLHpCQcduTpU0GRm zF?l1;!FRKOn-7+3TaTq7M{CRN$MR3lwYnww-Ulw{Jb3h|tJJrT z@7T&xN?u%0+!~E_PB2SSOu^50)`{eM3kBu(d;SV}5G(9EXI8-NZMjdkIqM0Ci>sG~ z99dDim8ntqW@Sjzk22=`^b(;`>yj4=>Gl@y=iDfLXnkk;Vyna}D=r?{Cu6ZDc6V4s z^PJ_A`=K|OKJ0o1+B3{}sDx$F;^ZgC+nJ8n`1T*Uw!euZ>`+`nQ-y|o)fB~RZ*4!9 zbe%Y%0leS3tS?n~Th2mB&b|BlYHy`f1)s_D`I*p<2i`RDDawGxrXAEk9kKhI ziU);{G+&x$mfyD=IH$|>l6SX$+T%mq&-FXZ{}D6)=e;BO*?X-IKF!-_9D9C~L-j+s z$PHLW>_O&#;K>JUOaG&t!}z=>-l=!P2f4dZu7UGIlnz~&YfQ?_xyAF+={*P zb9v8o=0g{-+KLmLW4O8&(aSoP6PEiLvEp<2tgsm6U%)B!IQCz>puuNX;Cc$DKzYS4 z{=nNjq3h!t92!Ae%M7+;>`(wU#YI>`w}5Z+j0E~BCADda5^x*BLJoeuUBGF$gfO6` zXR<8L{!hAd_wLhe0rwUroZw#kGx&fgXfDa&Ah1uSQE|+I89c89+>>Sv>;W9jJ8>Zq zI-RCb0Tf_8FOd$N<7-R;9?-M!2Ct+Q?Br8cf1tnv$;Uh(PXbZE8<3-R17~ZX9fk!D zfDRL}NuC2fJ_=Y9b;*KeD9uw|7{F|`0SYvw_ZWkc5Xe~@fy1N$Z-6au$k{~7+xJ~> Date: Fri, 3 Oct 2025 11:47:05 +0100 Subject: [PATCH 55/64] Update guide --- docs/MigratingFromNavigation2.md | 76 ++++++++++++++++---------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index d536f14..b9865db 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -1,13 +1,13 @@ # Navigation 2 to 3 migration guide -## Overview {:#overview} +## Overview This is intended to be a general guide to [Navigation 2](https://developer.android.com/guide/navigation) to [Navigation 3](https://developer.android.com/guide/navigation/navigation-3) migration which can be applied to any project. It attempts to keep the project in a working state during migration (build succeeds, navigation tests pass) and does this by maintaining interoperability between Nav2 and Nav3. The guide assumes that the project is [modularized](https://developer.android.com/topic/modularization), and the suggested approach allows feature modules to adopt Nav3 on an incremental basis. Once all feature modules have migrated, the Nav2 code can be safely removed. If the codebase is not modularized, the steps for specific modules should be applied to the main `app` module. -### Features {:#features} +### Features This guide covers the migration of the following Nav2 features: @@ -21,21 +21,21 @@ The following features are not yet supported: - [Custom destination types](https://developer.android.com/guide/navigation/design/kotlin-dsl#custom) - Deeplinks -### Prerequisites {:#prerequisites} +### Prerequisites - Familiarity with [navigation terminology](https://developer.android.com/guide/navigation). - Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [`AndroidFragment`](https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1)) for interoperability with Compose. -- Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657){:.external} first ([example](https://github.com/android/nowinandroid/pull/1413){:.external}). -- Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt){:.external}. +- Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657)). +- Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt). - Your app must have a [minSdk](https://developer.android.com/guide/topics/manifest/uses-sdk-element#min) of 23 or above. -### Step-by-step code examples {:#step-by-step-code} +### Step-by-step code examples -A [migration recipe](https://github.com/android/nav3-recipes/tree/dt/2to3migration){:.external} exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. +A [migration recipe](https://github.com/android/nav3-recipes/tree/dt/2to3migration) exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. To use the migration recipe as a guide: -- Clone the [nav3-recipes repository](https://github.com/android/nav3-recipes){:.external}, load it into Android Studio and switch to the Android view in the project explorer +- Clone the [nav3-recipes repository](https://github.com/android/nav3-recipes), load it into Android Studio and switch to the Android view in the project explorer - Expand the `com.example.nav3recipes.migration` package - Open `start.StartMigrationActivity`. Familiarise yourself with the navigation structure and behavior defined in this activity. For simplicity, the recipe codebase is not modularized, however, it is structured in a way that should make it clear where the module boundaries would be in a real app. This is the starting point for migration. @@ -53,7 +53,7 @@ Tips for working with the migration recipe: - To run the migration tests only on a single activity, uncomment the other activities in the `data` function inside `MigrationActivityNavigationTest`. - The migration steps introduce a `Navigator` class. Setting its `shouldPrintDebugInfo` parameter to `true` will output lots of debug information to Logcat. -## Step 1. Add the Nav3 dependencies {:#step-1.} +## Step 1. Add the Nav3 dependencies The latest dependencies can be found here: [https://developer.android.com/guide/navigation/navigation-3/get-started](https://developer.android.com/guide/navigation/navigation-3/get-started) @@ -65,7 +65,7 @@ androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runt androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" } ``` -### 1.1 Create a common navigation module {:#1.1-create} +### 1.1 Create a common navigation module - If you don't have one already, create a :`core:navigation` module - Add the Nav3 runtime as a dependency using `api(libs.androidx.navigation3.runtime). This` allows modules depending on :core:navigation `to` use the Nav3 runtime API. @@ -82,24 +82,24 @@ dependencies { **Note**: Nav3 has two libraries: `runtime` and `ui`. Usually only the `app` module needs to depend on `navigation3.ui` which is why it isn't included in the :`core:navigation` dependencies above. -### 1.2 Update main app module {:#1.2-update} +### 1.2 Update main app module - Update the `app` module to depend on :`core:navigation` and on `androidx.navigation3.ui` - Update compileSdk to 36 or above - Update minSdk to 23 or above - Update AGP to 8.9.3 or above -## Step 2. Create a back stack and use it with NavDisplay {:#step-2.} +## Step 2. Create a back stack and use it with NavDisplay -### 2.1 Add the Navigator class {:#2.1-add} +### 2.1 Add the Navigator class Important: A fundamental difference between Nav2 and Nav3 is that **you own the back stack**. This means much of the logic and state that was previously managed by Nav2, must now be managed by you. This gives you greater flexibility and control, but also more responsibility. To aid with migration, a class which provides and manages a back stack named `Navigator` is provided for you. It is not part of the Nav3 library and it does not provide all the features of Nav2. Instead it is intended to be an assistant during migration, and after to be a starting point for you to implement your own navigation behavior and logic. -Copy the [`Navigator`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt){:.external} [class](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt){:.external} to the :`core:navigation` module. This class contains `backStack: SnapshotStateList` that can be used with `NavDisplay.It` will mirror `NavController`'s back stack ensuring that Nav2's state remains the source of truth throughout migration. After the migration is complete, the NavController mirroring code will be removed. +Copy the [`Navigator`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt) to the :`core:navigation` module. This class contains `backStack: SnapshotStateList` that can be used with `NavDisplay.It` will mirror `NavController`'s back stack ensuring that Nav2's state remains the source of truth throughout migration. After the migration is complete, the NavController mirroring code will be removed. -### 2.2 Make the Navigator available everywhere that NavController is {:#2.2-make} +### 2.2 Make the Navigator available everywhere that NavController is Goal: The `Navigator` class is available everywhere that `NavController` is used. @@ -115,7 +115,7 @@ val navigator = remember { Navigator(navController) } - Do a project-wide search for "NavController" and "NavHostController" - Update any classes or methods that accept a `NavController` or `NavHostController` to also accept `Navigator` as a parameter -### 2.3 Wrap NavHost with NavDisplay {:#2.3-wrap} +### 2.3 Wrap NavHost with NavDisplay Goal: `NavDisplay` displays your existing `NavHost` using a fallback `NavEntry`. @@ -142,11 +142,11 @@ NavDisplay( ) ``` -## Step 3. [Single feature] Migrate routes {:#step-3.} +## Step 3. [Single feature] Migrate routes Goal: Routes are moved into their own :`feature:api` module and their properties are modelled outside of `NavHost` -### 3.1 Split feature module into api and impl {:#3.1-split} +### 3.1 Split feature module into api and impl Choose **a single feature module** that does not contain the start destination for your app. The feature module containing the start destination will be migrated last. @@ -171,7 +171,7 @@ Update :`app` dependencies: - Update the :`app` module to depend on both :`:api` and :`:impl`. -### 3.2 Model nested navigation graphs {:#3.2-model} +### 3.2 Model nested navigation graphs Skip this section if you don't use nested navigation graphs. @@ -304,8 +304,8 @@ Taking the code example from above. The starting route is A. Review the provided `Navigator` class to ensure that it can model your app's current navigation behavior. In particular: -- Review the [`add`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142){:.external} [method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142){:.external} -- Note that `popUpTo` in the [`navigate`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121){:.external} [method](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121){:.external} will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. +- Review the [`add`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142) +- Note that `popUpTo` in the [`navigate`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121) will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. #### 3.2.2 Update routes to implement marker interfaces @@ -314,11 +314,11 @@ Steps: - Update each top level route so that it implements the `Route.TopLevel` interface provided by `Navigator.kt` - Update each shared route so that it implements the `Route.Shared` interface provided by `Navigator.kt` -## Step 4. [Single feature] Move destinations from NavHost to entryProvider {:#step-4.} +## Step 4. [Single feature] Move destinations from NavHost to entryProvider Goal: When navigating to a route, it is provided using `NavDisplay's entryProvider`. -### 4.1 Move composable content from NavHost into entryProvider {:#4.1-move} +### 4.1 Move composable content from NavHost into entryProvider Continue only with the feature module being migrated in the previous step. @@ -330,13 +330,13 @@ For each destination inside `NavHost`, do the following based the destination ty - `composable` - Copy the function into `entryProvider` and rename `composable` to `entry`, retaining the type parameter. Remove the composable content from the old `composable` leaving it empty i.e., `composable`{}. - `dialog` - Same as composable but add metadata to the entry as follows: entry(metadata `= DialogSceneStrategy.dialog()`) - If you haven't already, add `DialogSceneStrategy` to `NavDisplay's sceneStrategy` parameter. -- [`bottomSheet`](https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/package-summary#(androidx.navigation.NavGraphBuilder).bottomSheet(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2)) - [Follow the bottom sheet recipe here](https://github.com/android/nav3-recipes/pull/67){:.external}. This essentially the same as the instructions for `dialog` except that `BottomSheetSceneStrategy` is not part of the core Nav3 library and so should be copied/modified to your individual requirements. +- [`bottomSheet`](https://developer.android.com/reference/kotlin/androidx/compose/material/navigation/package-summary#(androidx.navigation.NavGraphBuilder).bottomSheet(kotlin.String,kotlin.collections.List,kotlin.collections.List,kotlin.Function2)) - [Follow the bottom sheet recipe here](https://github.com/android/nav3-recipes/pull/67). This essentially the same as the instructions for `dialog` except that `BottomSheetSceneStrategy` is not part of the core Nav3 library and so should be copied/modified to your individual requirements. #### 4.1.2 Obtain navigation arguments In Nav2, when navigation arguments are passed using the route instance, you must first obtain the route instance from `NavBackStackEntry` by calling `toRoute`. In Nav3, the route instance is directly accessible with `entry`'s lambda parameter so there's no need to obtain the route instance. -If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels](https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels){:.external} and apply the technique most appropriate to your codebase. +If using ViewModels to pass navigation arguments, please check the [Nav3 recipes for ViewModels](https://github.com/android/nav3-recipes/blob/main/README.md#passing-navigation-arguments-to-viewmodels) and apply the technique most appropriate to your codebase. #### 4.1.3 Code example @@ -427,7 +427,7 @@ private fun EntryProviderBuilder.featureBSection() { } ``` -### 4.3 In Navigator, convert NavBackStackEntry back to its route instance {:#4.3-navigator,} +### 4.3 In Navigator, convert NavBackStackEntry back to its route instance Steps: @@ -450,7 +450,7 @@ You should now be able to navigate to, and back from, the migrated destinations. **Note**: When navigating (both forward and back) between destinations handled by `NavHost` and `NavDisplay`, you may see the blank destination until the transition animation has completed. -## Step 5. [Single feature] Replace NavController with Navigator {:#step-5.} +## Step 5. [Single feature] Replace NavController with Navigator Goal: Within the migrated feature module, navigation events are handled by `Navigator` instead of `NavController` @@ -473,7 +473,7 @@ Remove Nav2 imports and module dependencies: At this point, this feature module has been fully migrated to Nav3. -## Step 6. Migrate all feature modules {:#step-6.} +## Step 6. Migrate all feature modules Goal: Feature modules use Nav3. They don't contain any Nav2 code. @@ -481,16 +481,16 @@ Complete steps 3-5 for each feature module. Start with the module with the least Ensure that shared entries are not duplicated. -## Step 7. Use Navigator.backStack as source of truth for navigation state {:#step-7.} +## Step 7. Use Navigator.backStack as source of truth for navigation state -### 7.1 Ensure Navigator is used instead of NavController everywhere {:#7.1-ensure} +### 7.1 Ensure Navigator is used instead of NavController everywhere Replace any remaining instances of: - `NavController.navigate` with `Navigator.navigate` - `NavController.popBackStack` with `Navigator.goBack` -### 7.2 Update Navigator to modify its back stack directly {:#7.2-update} +### 7.2 Update Navigator to modify its back stack directly - Open `Navigator` - In `navigate` and `goBack`: @@ -498,9 +498,9 @@ Replace any remaining instances of: - Uncomment the code that modifies the back stack directly - Remove all code which references `NavController` -The final `Navigator` [should look like this](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15){:.external}. +The final `Navigator` [should look like this](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15). -### 7.3 Set the app's start route {:#7.3-set} +### 7.3 Set the app's start route When creating the `Navigator` specify the starting route for your app. @@ -508,23 +508,23 @@ When creating the `Navigator` specify the starting route for your app. val navigator = remember { Navigator(navController, startRoute = RouteA) } ``` -### 7.4 Update common navigation UI components {:#7.4-update} +### 7.4 Update common navigation UI components -If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94){:.external}. +If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94). In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. `BaseRouteA` and `RouteA`). This is no longer necessary so remove any redundant types for the navigation graph from the :`api` modules. Ensure that the correct types are used to identify top level routes. -### 7.5 Remove the entryProvider fallback {:#7.5-remove} +### 7.5 Remove the entryProvider fallback Remove the `fallback` parameter from `entryProvider` as there are no longer any unmigrated routes that must be handled by `NavHost`. -### 7.6. Remove unused dependencies {:#7.6.-remove} +### 7.6. Remove unused dependencies - Remove all remaining Nav2 dependencies from the project - In :`core:navigation` remove any dependencies on :`feature:api` modules Congratulations! Your project is now migrated to Navigation 3. -## Next steps {:#next-steps} +## Next steps In the supplied `Navigator`, the type of items in the back stack is `Any`. You may now want to change this to use stronger types, for example the `NavKey` interface provided by Nav3. From f31ea9e09d3292c87cc9e4075791a0710c0896eb Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 11:58:43 +0100 Subject: [PATCH 56/64] Update guide --- docs/MigratingFromNavigation2.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index b9865db..998f471 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -1,5 +1,6 @@ - # Navigation 2 to 3 migration guide +**IMPORTANT:** This document is a 🚧work in progress🚧 and as such care should be taken when implementing the steps in this guide +in your own app. We welcome your feedback! ## Overview From f46b3fccf88b7bf407f97cfefe6583568d91911f Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 12:00:29 +0100 Subject: [PATCH 57/64] Update guide --- docs/MigratingFromNavigation2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index 998f471..d304b75 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -26,7 +26,7 @@ The following features are not yet supported: - Familiarity with [navigation terminology](https://developer.android.com/guide/navigation). - Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [`AndroidFragment`](https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1)) for interoperability with Compose. -- Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657)). +- Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657) first ([example](https://github.com/android/nowinandroid/pull/1413)). - Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt). - Your app must have a [minSdk](https://developer.android.com/guide/topics/manifest/uses-sdk-element#min) of 23 or above. From 26133a4d8755d1a96188e08b51266c97f75d07c1 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 12:20:30 +0100 Subject: [PATCH 58/64] Remove navigator package --- app/src/main/AndroidManifest.xml | 5 - .../nav3recipes/navigator/basic/Navigator.kt | 131 ------------ .../navigator/basic/NavigatorActivity.kt | 172 ---------------- .../navigator/basic/NavigatorV2.kt | 194 ------------------ 4 files changed, 502 deletions(-) delete mode 100644 app/src/main/java/com/example/nav3recipes/navigator/basic/Navigator.kt delete mode 100644 app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt delete mode 100644 app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorV2.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 05c12e4..6413184 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -51,11 +51,6 @@ android:exported="true" android:label="@string/app_name" android:theme="@style/Theme.Nav3Recipes"/> - (startRoute = A) // back stack is [A] - * navigator.navigate(B) // back stack [A, B] - * navigator.navigate(C) // back stack [A, C] - B is popped before C is added - * - * When set to `true`, the resulting back stack would be [A, B, C] - * ``` - * - * @see `NavigatorTest`. - */ -class Navigator( - private val startRoute: T, - private val canTopLevelRoutesExistTogether: Boolean = false -) { - - val backStack = mutableStateListOf(startRoute) - var topLevelRoute by mutableStateOf(startRoute) - private set - - // Maintain a stack for each top level route - private var topLevelStacks : LinkedHashMap> = linkedMapOf( - startRoute to mutableListOf(startRoute) - ) - - // Maintain a map of shared routes to their parent stacks - private var sharedRoutes : MutableMap = mutableMapOf() - - private fun updateBackStack() = - backStack.apply { - clear() - addAll(topLevelStacks.flatMap { it.value }) - } - - private fun navigateToTopLevel(route: T){ - - if (route == startRoute){ - clearAllExceptStartStack() - } else { - - // Get the existing stack or create a new one. - val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) - - if (!canTopLevelRoutesExistTogether) { - clearAllExceptStartStack() - } - - topLevelStacks.put(route, topLevelStack) - } - - topLevelRoute = route - } - - private fun clearAllExceptStartStack(){ - // Remove all other top level stacks, except the start stack - val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) - topLevelStacks.clear() - topLevelStacks.put(startRoute, startStack) - } - - /** - * Navigate to the given route. - */ - fun navigate(route: T){ - if (route.isTopLevel){ - navigateToTopLevel(route) - } else { - if (route.isShared){ - // If the key is already in a stack, remove it - val oldParent = sharedRoutes[route] - if (oldParent != null) { - topLevelStacks[oldParent]?.remove(route) - } - sharedRoutes[route] = topLevelRoute - } - topLevelStacks[topLevelRoute]?.add(route) - } - updateBackStack() - } - - /** - * Go back to the previous route. - */ - fun goBack(){ - if (backStack.size <= 1){ - return - } - val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() - // If the removed key was a top level key, remove the associated top level stack - topLevelStacks.remove(removedKey) - topLevelRoute = topLevelStacks.keys.last() - updateBackStack() - } -} - -@Serializable -abstract class Route( - val isTopLevel : Boolean = false, - val isShared : Boolean = false -) diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt deleted file mode 100644 index 0c5d74e..0000000 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorActivity.kt +++ /dev/null @@ -1,172 +0,0 @@ -/* - * Copyright 2025 The Android Open Source Project - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package com.example.nav3recipes.navigator.basic - -import android.os.Bundle -import androidx.activity.ComponentActivity -import androidx.activity.compose.setContent -import androidx.compose.foundation.layout.padding -import androidx.compose.material.icons.Icons -import androidx.compose.material.icons.filled.Face -import androidx.compose.material.icons.filled.Home -import androidx.compose.material.icons.filled.PlayArrow -import androidx.compose.material.icons.filled.Search -import androidx.compose.material3.Button -import androidx.compose.material3.ExperimentalMaterial3Api -import androidx.compose.material3.Icon -import androidx.compose.material3.IconButton -import androidx.compose.material3.NavigationBar -import androidx.compose.material3.NavigationBarItem -import androidx.compose.material3.Scaffold -import androidx.compose.material3.Text -import androidx.compose.material3.TextField -import androidx.compose.material3.TopAppBar -import androidx.compose.runtime.Composable -import androidx.compose.runtime.getValue -import androidx.compose.runtime.mutableStateOf -import androidx.compose.runtime.remember -import androidx.compose.runtime.saveable.rememberSaveable -import androidx.compose.runtime.setValue -import androidx.compose.ui.Modifier -import androidx.compose.ui.graphics.vector.ImageVector -import androidx.navigation3.runtime.entry -import androidx.navigation3.runtime.entryProvider -import androidx.navigation3.ui.NavDisplay -import com.example.nav3recipes.content.ContentBlue -import com.example.nav3recipes.content.ContentGreen -import com.example.nav3recipes.content.ContentPink -import com.example.nav3recipes.content.ContentPurple -import com.example.nav3recipes.content.ContentRed -import com.example.nav3recipes.ui.setEdgeToEdgeConfig -import kotlinx.serialization.Serializable - -@Serializable -private data object Home : Route(isTopLevel = true) -@Serializable -private data object ChatList : Route(isTopLevel = true) - -@Serializable -private data object ChatDetail : Route() -@Serializable -private data object Camera : Route(isTopLevel = true) -@Serializable -private data object Search : Route(isShared = true) - -private val TOP_LEVEL_ROUTES : List> = listOf( - NavBarItem(Home, icon = Icons.Default.Home, description = "Home"), - NavBarItem(ChatList, icon = Icons.Default.Face, description = "Chat list"), - NavBarItem(Camera, icon = Icons.Default.PlayArrow, description = "Camera") -) - -class NavigatorActivity : ComponentActivity() { - override fun onCreate(savedInstanceState: Bundle?) { - setEdgeToEdgeConfig() - super.onCreate(savedInstanceState) - setContent { - val navigator = remember { Navigator(Home) } - - Scaffold( - topBar = { - TopAppBarWithSearch { navigator.navigate(Search) } - }, - bottomBar = { - NavigationBar { - TOP_LEVEL_ROUTES.forEach { topLevelRoute -> - val isSelected = topLevelRoute.route == navigator.topLevelRoute - NavigationBarItem( - selected = isSelected, - onClick = { - navigator.navigate(topLevelRoute.route) - }, - icon = { - Icon( - imageVector = topLevelRoute.icon, - contentDescription = topLevelRoute.description - ) - } - ) - } - } - } - ) { paddingValues -> - NavDisplay( - modifier = Modifier.padding(paddingValues), - backStack = navigator.backStack, - onBack = { navigator.goBack() }, - entryProvider = entryProvider { - entry{ - ContentRed("Home screen") - } - entry{ - ContentGreen("Chat list screen"){ - Button(onClick = { navigator.navigate(ChatDetail) }) { - Text("Go to conversation") - } - } - } - entry{ - ContentBlue("Chat detail screen") - - } - entry{ - ContentPurple("Camera screen") - } - entry{ - ContentPink("Search screen"){ - var text by rememberSaveable { mutableStateOf("") } - TextField( - value = text, - onValueChange = { newText -> text = newText}, - label = { Text("Enter search here") }, - singleLine = true - ) - } - } - }, - ) - } - } - } -} - -@OptIn(ExperimentalMaterial3Api::class) -@Composable -fun TopAppBarWithSearch( - onSearchClick: () -> Unit -) { - TopAppBar( - title = { - Text("Navigator Activity") - }, - actions = { - IconButton(onClick = onSearchClick) { - Icon( - imageVector = Icons.Filled.Search, - contentDescription = "Search" - ) - } - - }, - ) -} - -class NavBarItem( - val route: T, - val icon: ImageVector, - val description: String -) - diff --git a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorV2.kt b/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorV2.kt deleted file mode 100644 index ea9d446..0000000 --- a/app/src/main/java/com/example/nav3recipes/navigator/basic/NavigatorV2.kt +++ /dev/null @@ -1,194 +0,0 @@ -package com.example.nav3recipes.navigator.basic - -import android.annotation.SuppressLint -import androidx.compose.runtime.getValue -import androidx.compose.runtime.mutableStateListOf -import androidx.compose.runtime.mutableStateOf -import androidx.compose.runtime.setValue -import androidx.navigation.NavBackStackEntry -import androidx.navigation.NavDestination.Companion.hasRoute -import androidx.navigation.NavHostController -import androidx.navigation.toRoute -import com.example.nav3recipes.migration.step4.RouteB -import com.example.nav3recipes.migration.step4.RouteB1 -import com.example.nav3recipes.migration.step4.RouteD -import com.example.nav3recipes.migration.step4.RouteE -import kotlinx.coroutines.CoroutineScope -import kotlinx.coroutines.Job -import kotlinx.coroutines.launch - -/** - * Navigator that mirrors `NavController`'s back stack - */ -@SuppressLint("RestrictedApi") -class NavigatorV2( - private val navController: NavHostController, - private val startRoute: Any = Unit, - private val canTopLevelRoutesExistTogether: Boolean = false -) { - - val backStack = mutableStateListOf(startRoute) - var topLevelRoute by mutableStateOf(startRoute) - private set - - // Maintain a stack for each top level route - private lateinit var topLevelStacks : MutableMap> - - // Maintain a map of shared routes to their parent stacks - private var sharedRoutes: MutableMap = mutableMapOf() - - val coroutineScope = CoroutineScope(Job()) - - init { - inititalizeTopLevelStacks() - coroutineScope.launch { - navController.currentBackStack.collect { nav2BackStack -> - inititalizeTopLevelStacks() - println("Top level stacks reset, parsing Nav2 back stack $nav2BackStack") - printTopLevelStacks() - - nav2BackStack.forEach { entry -> - val destination = entry.destination - - if (destination.navigatorName == "composable" || destination.navigatorName == "dialog"){ - val route = - if (destination.hasRoute()) { - entry.toRoute() - } else if (destination.hasRoute()) { - entry.toRoute() - } else if (destination.hasRoute()) { - entry.toRoute() - } else if (destination.hasRoute()) { - entry.toRoute() - } else { - // Non migrated top level route - entry - } - add(route) - } else { - println("Ignoring $entry") - } - } - printTopLevelStacks() - updateBackStack() - } - } - } - - private fun updateBackStack() { - backStack.apply { - clear() - val entries = topLevelStacks.flatMap { it.value } - addAll(entries) - } - printBackStack() - } - - private fun printBackStack() { - println("Back stack: ") - backStack.print() - println("---") - } - - private fun printTopLevelStacks() { - - println("Top level stacks: ") - topLevelStacks.forEach { topLevelStack -> - print("${topLevelStack.key} => ") - topLevelStack.value.print() - } - println("---") - } - - private fun List.print() { - print("[") - forEach { entry -> - if (entry is NavBackStackEntry){ - print("Unmigrated route: ${entry.destination.route}, ") - } else { - print("Migrated route: $entry, ") - } - } - print("]\n") - } - - private fun addTopLevel(route: Any) { - if (route == startRoute) { - clearAllExceptStartStack() - } else { - - // Get the existing stack or create a new one. - val topLevelStack = topLevelStacks.remove(route) ?: mutableListOf(route) - - if (!canTopLevelRoutesExistTogether) { - clearAllExceptStartStack() - } - - topLevelStacks.put(route, topLevelStack) - println("Added top level route $route") - } - topLevelRoute = route - } - - private fun clearAllExceptStartStack() { - // Remove all other top level stacks, except the start stack - val startStack = topLevelStacks[startRoute] ?: mutableListOf(startRoute) - topLevelStacks.clear() - topLevelStacks.put(startRoute, startStack) - } - - private fun inititalizeTopLevelStacks() { - topLevelStacks = mutableMapOf(startRoute to mutableListOf(startRoute)) - topLevelRoute = startRoute - } - - private fun add(route: Any) { - println("Attempting to add $route") - if (route is RouteV2.TopLevel) { - println("$route is a top level route") - addTopLevel(route) - } else { - if (route is RouteV2.Shared) { - println("$route is a shared route") - // If the key is already in a stack, remove it - val oldParent = sharedRoutes[route] - if (oldParent != null) { - topLevelStacks[oldParent]?.remove(route) - } - sharedRoutes[route] = topLevelRoute - } else { - println("$route is a normal route") - } - val hasBeenAdded = topLevelStacks[topLevelRoute]?.add(route) ?: false - println("Added $route to $topLevelRoute stack: $hasBeenAdded") - } - } - - /** - * Navigate to the given route. - */ - fun navigate(route: Any) { - add(route) - updateBackStack() - } - - /** - * Go back to the previous route. - */ - fun goBack() { - if (backStack.size <= 1) { - return - } - val removedKey = topLevelStacks[topLevelRoute]?.removeLastOrNull() - // If the removed key was a top level key, remove the associated top level stack - topLevelStacks.remove(removedKey) - topLevelRoute = topLevelStacks.keys.last() - updateBackStack() - } -} - -sealed interface RouteV2 { - interface TopLevel : RouteV2 - interface Dialog : RouteV2 - interface Shared : RouteV2 -} From 495c65be70bccd71ec62410ac2886dd972c117ed Mon Sep 17 00:00:00 2001 From: jbw0033 Date: Fri, 3 Oct 2025 12:14:48 +0000 Subject: [PATCH 59/64] Fix errors in Bottomsheet Recipe Fix imports and remove extra name attribute in manifest. --- app/src/main/AndroidManifest.xml | 1 - .../example/nav3recipes/bottomsheet/BottomSheetActivity.kt | 1 - .../nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt | 6 +++--- 3 files changed, 3 insertions(+), 5 deletions(-) diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 6a360a6..68c4ad5 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -70,7 +70,6 @@ android:exported="true" android:theme="@style/Theme.Nav3Recipes"/> diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt index 57b43b7..46348e3 100644 --- a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetActivity.kt @@ -28,7 +28,6 @@ import androidx.compose.ui.Modifier import androidx.compose.ui.draw.clip import androidx.compose.ui.unit.dp import androidx.navigation3.runtime.NavKey -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.runtime.rememberNavBackStack import androidx.navigation3.ui.NavDisplay diff --git a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt index 1a79615..f72b24d 100644 --- a/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt +++ b/app/src/main/java/com/example/nav3recipes/bottomsheet/BottomSheetSceneStrategy.kt @@ -5,9 +5,9 @@ import androidx.compose.material3.ModalBottomSheet import androidx.compose.material3.ModalBottomSheetProperties import androidx.compose.runtime.Composable import androidx.navigation3.runtime.NavEntry -import androidx.navigation3.ui.OverlayScene -import androidx.navigation3.ui.Scene -import androidx.navigation3.ui.SceneStrategy +import androidx.navigation3.scene.OverlayScene +import androidx.navigation3.scene.Scene +import androidx.navigation3.scene.SceneStrategy /** An [OverlayScene] that renders an [entry] within a [ModalBottomSheet]. */ @OptIn(ExperimentalMaterial3Api::class) From 4beb9c0095ed61b3c91d6a4474cf9c986315bacf Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 14:40:41 +0100 Subject: [PATCH 60/64] Refactor to render NavDisplay on top of NavHost, rather than wrapping it --- .../MigrationActivityNavigationTest.kt | 8 +- .../nav3recipes/migration/step2/Navigator.kt | 3 +- .../migration/step2/Step2MigrationActivity.kt | 84 ++++++------ .../nav3recipes/migration/step3/Navigator.kt | 3 +- .../migration/step3/Step3MigrationActivity.kt | 77 +++++------ .../nav3recipes/migration/step4/Navigator.kt | 3 +- .../migration/step4/Step4MigrationActivity.kt | 121 ++++++++++-------- .../nav3recipes/migration/step5/Navigator.kt | 3 +- .../migration/step5/Step5MigrationActivity.kt | 83 ++++++------ .../nav3recipes/migration/step6/Navigator.kt | 3 +- .../migration/step6/Step6MigrationActivity.kt | 111 ++++++++-------- docs/MigratingFromNavigation2.md | 40 +++--- 12 files changed, 288 insertions(+), 251 deletions(-) diff --git a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt index ce57b61..b294d7b 100644 --- a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +++ b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt @@ -35,13 +35,13 @@ class MigrationActivityNavigationTest(activityClass: Class> { return listOf( - arrayOf(StartMigrationActivity::class.java), + /*arrayOf(StartMigrationActivity::class.java), arrayOf(Step2MigrationActivity::class.java), arrayOf(Step3MigrationActivity::class.java), - arrayOf(Step4MigrationActivity::class.java), + arrayOf(Step4MigrationActivity::class.java),*/ arrayOf(Step5MigrationActivity::class.java), - arrayOf(Step6MigrationActivity::class.java), - arrayOf(Step7MigrationActivity::class.java) + /*arrayOf(Step6MigrationActivity::class.java), + arrayOf(Step7MigrationActivity::class.java)*/ ) } } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt index d6133c6..50817e1 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt @@ -21,6 +21,7 @@ import kotlinx.coroutines.launch */ @SuppressLint("RestrictedApi") class Navigator( + coroutineScope: CoroutineScope, private val navController: NavHostController, private val startRoute: Any = Unit, private val canTopLevelRoutesExistTogether: Boolean = false, @@ -37,7 +38,7 @@ class Navigator( // Maintain a map of shared routes to their parent stacks private var sharedRoutes: MutableMap = mutableMapOf() - val coroutineScope = CoroutineScope(Job()) + //val coroutineScope = CoroutineScope(Job()) init { inititalizeTopLevelStacks() diff --git a/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt index 98c2047..c9d57a9 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step2/Step2MigrationActivity.kt @@ -20,6 +20,7 @@ import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.padding import androidx.compose.material.icons.Icons @@ -34,6 +35,7 @@ import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.runtime.getValue import androidx.compose.runtime.remember +import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color @@ -65,24 +67,31 @@ import kotlin.reflect.KClass @Serializable private data object BaseRouteA + @Serializable private data object RouteA + @Serializable private data object RouteA1 @Serializable private data object BaseRouteB + @Serializable private data object RouteB + @Serializable private data class RouteB1(val id: String) @Serializable private data object BaseRouteC + @Serializable private data object RouteC + @Serializable private data object RouteD + @Serializable private data object RouteE @@ -103,8 +112,9 @@ class Step2MigrationActivity : ComponentActivity() { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) setContent { + val coroutineScope = rememberCoroutineScope() val navController = rememberNavController() - val navigator = remember { Navigator(navController) } + val navigator = remember { Navigator(coroutineScope, navController) } val currentBackStackEntry by navController.currentBackStackEntryAsState() Scaffold(bottomBar = { @@ -132,44 +142,44 @@ class Step2MigrationActivity : ComponentActivity() { }) { paddingValues -> - NavDisplay( - backStack = navigator.backStack, - onBack = { navigator.goBack() }, - entryProvider = entryProvider( - fallback = { key -> - NavEntry(key = key) { - NavHost( - navController = navController, - startDestination = BaseRouteA, - modifier = Modifier.padding(paddingValues) - ) { - featureASection( - onSubRouteClick = { navController.navigate(RouteA1) }, - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - featureBSection( - onDetailClick = { id -> navController.navigate(RouteB1(id)) }, - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - featureCSection( - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - dialog { key -> - Text( - modifier = Modifier.background(Color.White), - text = "Route D title (dialog)" - ) - } - } - } - } + Box(modifier = Modifier.padding(paddingValues)) { + NavHost( + navController = navController, + startDestination = BaseRouteA, ) { - // No nav entries added yet. + featureASection( + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureBSection( + onDetailClick = { id -> navController.navigate(RouteB1(id)) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureCSection( + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + dialog { key -> + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } } - ) + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) {} + } + ) { + // No nav entries added yet. + } + ) + } } } } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt index 392d153..c40ba69 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Navigator.kt @@ -22,6 +22,7 @@ import kotlinx.coroutines.launch */ @SuppressLint("RestrictedApi") internal class Navigator( + coroutineScope: CoroutineScope, private val navController: NavHostController, private val startRoute: Any = Unit, private val canTopLevelRoutesExistTogether: Boolean = false, @@ -38,8 +39,6 @@ internal class Navigator( // Maintain a map of shared routes to their parent stacks private var sharedRoutes: MutableMap = mutableMapOf() - val coroutineScope = CoroutineScope(Job()) - init { inititalizeTopLevelStacks() coroutineScope.launch { diff --git a/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt index 86118c8..599fd59 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step3/Step3MigrationActivity.kt @@ -20,6 +20,7 @@ import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.padding import androidx.compose.material.icons.Icons @@ -34,6 +35,7 @@ import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.runtime.getValue import androidx.compose.runtime.remember +import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color @@ -103,8 +105,9 @@ class Step3MigrationActivity : ComponentActivity() { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) setContent { + val coroutineScope = rememberCoroutineScope() val navController = rememberNavController() - val navigator = remember { Navigator(navController) } + val navigator = remember { Navigator(coroutineScope, navController) } val currentBackStackEntry by navController.currentBackStackEntryAsState() Scaffold(bottomBar = { @@ -132,44 +135,44 @@ class Step3MigrationActivity : ComponentActivity() { }) { paddingValues -> - NavDisplay( - backStack = navigator.backStack, - onBack = { navigator.goBack() }, - entryProvider = entryProvider( - fallback = { key -> - NavEntry(key = key) { - NavHost( - navController = navController, - startDestination = BaseRouteA, - modifier = Modifier.padding(paddingValues) - ) { - featureASection( - onSubRouteClick = { navController.navigate(RouteA1) }, - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - featureBSection( - onDetailClick = { id -> navController.navigate(RouteB1(id)) }, - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - featureCSection( - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - dialog { key -> - Text( - modifier = Modifier.background(Color.White), - text = "Route D title (dialog)" - ) - } - } - } - } + Box(modifier = Modifier.padding(paddingValues)) { + NavHost( + navController = navController, + startDestination = BaseRouteA ) { - // No nav entries added yet. + featureASection( + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureBSection( + onDetailClick = { id -> navController.navigate(RouteB1(id)) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + featureCSection( + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + dialog { key -> + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } } - ) + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) {} + } + ) { + // No nav entries added yet. + } + ) + } } } } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt index 8eae6ad..6ab878a 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step4/Navigator.kt @@ -19,6 +19,7 @@ import kotlinx.coroutines.launch */ @SuppressLint("RestrictedApi") internal class Navigator( + coroutineScope: CoroutineScope, private val navController: NavHostController, private val startRoute: Any = Unit, private val canTopLevelRoutesExistTogether: Boolean = false, @@ -35,8 +36,6 @@ internal class Navigator( // Maintain a map of shared routes to their parent stacks private var sharedRoutes: MutableMap = mutableMapOf() - val coroutineScope = CoroutineScope(Job()) - init { inititalizeTopLevelStacks() coroutineScope.launch { diff --git a/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt index 522b3c5..46c0a26 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt @@ -20,6 +20,7 @@ import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.padding import androidx.compose.material.icons.Icons @@ -34,6 +35,7 @@ import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.runtime.getValue import androidx.compose.runtime.remember +import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color @@ -66,24 +68,31 @@ import kotlin.reflect.KClass @Serializable data object BaseRouteA + @Serializable data object RouteA + @Serializable data object RouteA1 @Serializable data object BaseRouteB + @Serializable data object RouteB : Route.TopLevel + @Serializable data class RouteB1(val id: String) @Serializable data object BaseRouteC + @Serializable data object RouteC + @Serializable data object RouteD + @Serializable data object RouteE @@ -101,12 +110,16 @@ data class NavBarItem( class Step4MigrationActivity : ComponentActivity() { + override fun onCreate(savedInstanceState: Bundle?) { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) + setContent { + val coroutineScope = rememberCoroutineScope() val navController = rememberNavController() - val navigator = remember { Navigator(navController, shouldPrintDebugInfo = true) } + val navigator = + remember { Navigator(coroutineScope, navController, shouldPrintDebugInfo = true) } val currentBackStackEntry by navController.currentBackStackEntryAsState() Scaffold(bottomBar = { @@ -134,48 +147,48 @@ class Step4MigrationActivity : ComponentActivity() { }) { paddingValues -> - NavDisplay( - backStack = navigator.backStack, - onBack = { navigator.goBack() }, - entryProvider = entryProvider( - fallback = { key -> - NavEntry(key = key) { - NavHost( - navController = navController, - startDestination = BaseRouteA, - modifier = Modifier.padding(paddingValues) - ) { - featureASection( - onSubRouteClick = { navController.navigate(RouteA1) }, - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - navigation(startDestination = RouteB) { - composable {} - composable {} - composable {} - } - featureCSection( - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - dialog { key -> - Text( - modifier = Modifier.background(Color.White), - text = "Route D title (dialog)" - ) - } - } - } - } + Box(modifier = Modifier.padding(paddingValues)) { + NavHost( + navController = navController, + startDestination = BaseRouteA ) { - featureBSection( - onDetailClick = { id -> navController.navigate(RouteB1(id)) }, + featureASection( + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + navigation(startDestination = RouteB) { + composable {} + composable {} + composable {} + } + featureCSection( onDialogClick = { navController.navigate(RouteD) }, onOtherClick = { navController.navigate(RouteE) } ) + dialog { key -> + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } } - ) + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) {} + } + ) { + featureBSection( + onDetailClick = { id -> navController.navigate(RouteB1(id)) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + } + ) + } } } } @@ -212,26 +225,26 @@ private fun EntryProviderBuilder.featureBSection( onDialogClick: () -> Unit, onOtherClick: () -> Unit ) { - entry { - ContentGreen("Route B title") { - Column(horizontalAlignment = Alignment.CenterHorizontally) { - Button(onClick = { onDetailClick("ABC") }) { - Text("Go to B1") - } - Button(onClick = onDialogClick) { - Text("Open dialog D") - } - Button(onClick = onOtherClick) { - Text("Go to E") - } + entry { + ContentGreen("Route B title") { + Column(horizontalAlignment = Alignment.CenterHorizontally) { + Button(onClick = { onDetailClick("ABC") }) { + Text("Go to B1") + } + Button(onClick = onDialogClick) { + Text("Open dialog D") + } + Button(onClick = onOtherClick) { + Text("Go to E") } } } - entry { key -> - ContentPurple("Route B1 title. ID: ${key.id}") - } - entry { ContentBlue("Route E title") } } + entry { key -> + ContentPurple("Route B1 title. ID: ${key.id}") + } + entry { ContentBlue("Route E title") } +} private fun NavGraphBuilder.featureCSection( onDialogClick: () -> Unit, diff --git a/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt index c351a19..6913714 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step5/Navigator.kt @@ -19,6 +19,7 @@ import kotlinx.coroutines.launch */ @SuppressLint("RestrictedApi") internal class Navigator( + coroutineScope: CoroutineScope, private val navController: NavHostController, private val startRoute: Any = Unit, private val canTopLevelRoutesExistTogether: Boolean = false, @@ -35,8 +36,6 @@ internal class Navigator( // Maintain a map of shared routes to their parent stacks private var sharedRoutes: MutableMap = mutableMapOf() - val coroutineScope = CoroutineScope(Job()) - init { inititalizeTopLevelStacks() coroutineScope.launch { diff --git a/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt index cbe3cf1..9533bff 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt @@ -20,6 +20,7 @@ import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.padding import androidx.compose.material.icons.Icons @@ -34,6 +35,7 @@ import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.runtime.getValue import androidx.compose.runtime.remember +import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color @@ -105,8 +107,9 @@ class Step5MigrationActivity : ComponentActivity() { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) setContent { + val coroutineScope = rememberCoroutineScope() val navController = rememberNavController() - val navigator = remember { Navigator(navController, shouldPrintDebugInfo = true) } + val navigator = remember { Navigator(coroutineScope, navController, shouldPrintDebugInfo = true) } val currentBackStackEntry by navController.currentBackStackEntryAsState() Scaffold(bottomBar = { @@ -134,48 +137,48 @@ class Step5MigrationActivity : ComponentActivity() { }) { paddingValues -> - NavDisplay( - backStack = navigator.backStack, - onBack = { navigator.goBack() }, - entryProvider = entryProvider( - fallback = { key -> - NavEntry(key = key) { - NavHost( - navController = navController, - startDestination = BaseRouteA, - modifier = Modifier.padding(paddingValues) - ) { - featureASection( - onSubRouteClick = { navController.navigate(RouteA1) }, - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - navigation(startDestination = RouteB) { - composable {} - composable {} - composable {} - } - featureCSection( - onDialogClick = { navController.navigate(RouteD) }, - onOtherClick = { navController.navigate(RouteE) } - ) - dialog { key -> - Text( - modifier = Modifier.background(Color.White), - text = "Route D title (dialog)" - ) - } - } - } - } + Box(modifier = Modifier.padding(paddingValues)) { + NavHost( + navController = navController, + startDestination = BaseRouteA ) { - featureBSection( - onDetailClick = { id -> navigator.navigate(RouteB1(id)) }, - onDialogClick = { navigator.navigate(RouteD) }, - onOtherClick = { navigator.navigate(RouteE) } + featureASection( + onSubRouteClick = { navController.navigate(RouteA1) }, + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } + ) + navigation(startDestination = RouteB) { + composable {} + composable {} + composable {} + } + featureCSection( + onDialogClick = { navController.navigate(RouteD) }, + onOtherClick = { navController.navigate(RouteE) } ) + dialog { key -> + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } } - ) + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) {} + } + ) { + featureBSection( + onDetailClick = { id -> navigator.navigate(RouteB1(id)) }, + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + } + ) + } } } } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt b/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt index 90c5db7..59ed462 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step6/Navigator.kt @@ -19,6 +19,7 @@ import kotlinx.coroutines.launch */ @SuppressLint("RestrictedApi") internal class Navigator( + coroutineScope: CoroutineScope, private val navController: NavHostController, private val startRoute: Any = Unit, private val canTopLevelRoutesExistTogether: Boolean = false, @@ -35,8 +36,6 @@ internal class Navigator( // Maintain a map of shared routes to their parent stacks private var sharedRoutes: MutableMap = mutableMapOf() - val coroutineScope = CoroutineScope(Job()) - init { inititalizeTopLevelStacks() coroutineScope.launch { diff --git a/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt index d792894..cdf7212 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt @@ -20,6 +20,7 @@ import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.background +import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.padding import androidx.compose.material.icons.Icons @@ -34,6 +35,7 @@ import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.runtime.getValue import androidx.compose.runtime.remember +import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.ui.Alignment import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color @@ -41,7 +43,6 @@ import androidx.compose.ui.graphics.vector.ImageVector import androidx.navigation.NavDestination import androidx.navigation.NavDestination.Companion.hasRoute import androidx.navigation.NavDestination.Companion.hierarchy -import androidx.navigation.NavGraphBuilder import androidx.navigation.compose.NavHost import androidx.navigation.compose.composable import androidx.navigation.compose.currentBackStackEntryAsState @@ -106,8 +107,9 @@ class Step6MigrationActivity : ComponentActivity() { setEdgeToEdgeConfig() super.onCreate(savedInstanceState) setContent { + val coroutineScope = rememberCoroutineScope() val navController = rememberNavController() - val navigator = remember { Navigator(navController) } + val navigator = remember { Navigator(coroutineScope, navController) } val currentBackStackEntry by navController.currentBackStackEntryAsState() Scaffold(bottomBar = { @@ -135,59 +137,64 @@ class Step6MigrationActivity : ComponentActivity() { }) { paddingValues -> - NavDisplay( - backStack = navigator.backStack, - onBack = { navigator.goBack() }, - sceneStrategy = remember { DialogSceneStrategy() }, - entryProvider = entryProvider( - fallback = { key -> - NavEntry(key = key) { - NavHost( - navController = navController, - startDestination = BaseRouteA, - modifier = Modifier.padding(paddingValues) - ) { - navigation(startDestination = RouteA) { - composable {} - composable {} - composable {} - } - navigation(startDestination = RouteB) { - composable {} - composable {} - composable {} - } - navigation(startDestination = RouteC) { - composable {} - composable {} - } - dialog {} - } - } - } + Box(modifier = Modifier.padding(paddingValues)) { + // Base Layer: Legacy NavHost is always in the composition tree. + NavHost( + navController = navController, + startDestination = BaseRouteA ) { - featureASection( - onSubRouteClick = { navigator.navigate(RouteA1) }, - onDialogClick = { navigator.navigate(RouteD) }, - onOtherClick = { navigator.navigate(RouteE) } - ) - featureBSection( - onDetailClick = { id -> navigator.navigate(RouteB1(id)) }, - onDialogClick = { navigator.navigate(RouteD) }, - onOtherClick = { navigator.navigate(RouteE) } - ) - featureCSection( - onDialogClick = { navigator.navigate(RouteD) }, - onOtherClick = { navigator.navigate(RouteE) } - ) - entry(metadata = DialogSceneStrategy.dialog()) { - Text( - modifier = Modifier.background(Color.White), - text = "Route D title (dialog)" - ) + // All routes are now rendered by NavDisplay, so these are all empty. + navigation(startDestination = RouteA) { + composable {} + composable {} + composable {} + } + navigation(startDestination = RouteB) { + composable {} + composable {} + composable {} } + navigation(startDestination = RouteC) { + composable {} + composable {} + } + dialog {} } - ) + + // Overlay Layer: NavDisplay for all screens. + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + sceneStrategy = remember { DialogSceneStrategy() }, + entryProvider = entryProvider( + fallback = { key -> + // Should ideally not be called if all routes are migrated. + NavEntry(key = key) {} + } + ) { + featureASection( + onSubRouteClick = { navigator.navigate(RouteA1) }, + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + featureBSection( + onDetailClick = { id -> navigator.navigate(RouteB1(id)) }, + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + featureCSection( + onDialogClick = { navigator.navigate(RouteD) }, + onOtherClick = { navigator.navigate(RouteE) } + ) + entry(metadata = DialogSceneStrategy.dialog()) { + Text( + modifier = Modifier.background(Color.White), + text = "Route D title (dialog)" + ) + } + } + ) + } } } } diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index d304b75..43803d0 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -116,31 +116,35 @@ val navigator = remember { Navigator(navController) } - Do a project-wide search for "NavController" and "NavHostController" - Update any classes or methods that accept a `NavController` or `NavHostController` to also accept `Navigator` as a parameter -### 2.3 Wrap NavHost with NavDisplay +### 2.3 Add a `NavDisplay` on top of `NavHost` -Goal: `NavDisplay` displays your existing `NavHost` using a fallback `NavEntry`. +Goal: `NavDisplay` is displayed transparently on top of your existing `NavHost` -- Wrap `NavHost` with a `NavDisplay` +The idea here is to let `NavHost` render all the legacy routes and `NavDisplay` render migrated routes. When `NavDisplay` encounters a legacy route it will render nothing, allowing the original `NavHost` to render the route instead. + +- Wrap your existing `NavHost` with a `Box` +- Add a `NavDisplay` inside the `Box` under the `NavHost` - Pass your `Navigator`'s back stack to the `NavDisplay` - Set `NavDisplay.onBack` to call `navigator.goBack()` -- Create an `entryProvider` with a `fallback` lambda that always displays the existing `NavHost` +- Create an `entryProvider` with a `fallback` lambda that has no composable content causing the existing `NavHost` to be displayed Example: ``` -NavDisplay( - backStack = navigator.backStack, - onBack = { navigator.goBack() }, - entryProvider = entryProvider( - fallback = { key -> - NavEntry(key = key) { - NavHost(...) - } - }, - ) { - // No Nav3 entries yet - }, -) +Box { + NavHost(...) + NavDisplay( + backStack = navigator.backStack, + onBack = { navigator.goBack() }, + entryProvider = entryProvider( + fallback = { key -> + NavEntry(key = key) {} + } + ) { + // No nav entries added yet. + } + ) +} ``` ## Step 3. [Single feature] Migrate routes @@ -317,7 +321,7 @@ Steps: ## Step 4. [Single feature] Move destinations from NavHost to entryProvider -Goal: When navigating to a route, it is provided using `NavDisplay's entryProvider`. +Goal: When navigating to a migrated route, it is provided using `NavDisplay's entryProvider`. ### 4.1 Move composable content from NavHost into entryProvider From beeeddc2129a48661745fa40ce182a02c7d48adc Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 14:49:22 +0100 Subject: [PATCH 61/64] Update to use alpha10 API --- .../nav3recipes/MigrationActivityNavigationTest.kt | 8 ++++---- .../nav3recipes/migration/step4/Step4MigrationActivity.kt | 1 - .../nav3recipes/migration/step5/Step5MigrationActivity.kt | 1 - .../nav3recipes/migration/step6/Step6MigrationActivity.kt | 3 +-- .../nav3recipes/migration/step7/Step7MigrationActivity.kt | 3 +-- 5 files changed, 6 insertions(+), 10 deletions(-) diff --git a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt index b294d7b..ce57b61 100644 --- a/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt +++ b/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt @@ -35,13 +35,13 @@ class MigrationActivityNavigationTest(activityClass: Class> { return listOf( - /*arrayOf(StartMigrationActivity::class.java), + arrayOf(StartMigrationActivity::class.java), arrayOf(Step2MigrationActivity::class.java), arrayOf(Step3MigrationActivity::class.java), - arrayOf(Step4MigrationActivity::class.java),*/ + arrayOf(Step4MigrationActivity::class.java), arrayOf(Step5MigrationActivity::class.java), - /*arrayOf(Step6MigrationActivity::class.java), - arrayOf(Step7MigrationActivity::class.java)*/ + arrayOf(Step6MigrationActivity::class.java), + arrayOf(Step7MigrationActivity::class.java) ) } } diff --git a/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt index 46c0a26..3b8f4cf 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step4/Step4MigrationActivity.kt @@ -53,7 +53,6 @@ import androidx.navigation.compose.rememberNavController import androidx.navigation.navOptions import androidx.navigation3.runtime.EntryProviderBuilder import androidx.navigation3.runtime.NavEntry -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.ui.NavDisplay import com.example.nav3recipes.content.ContentBlue diff --git a/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt index 9533bff..58ef24b 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step5/Step5MigrationActivity.kt @@ -53,7 +53,6 @@ import androidx.navigation.compose.rememberNavController import androidx.navigation.navOptions import androidx.navigation3.runtime.EntryProviderBuilder import androidx.navigation3.runtime.NavEntry -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider import androidx.navigation3.ui.NavDisplay import com.example.nav3recipes.content.ContentBlue diff --git a/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt index cdf7212..fa1ec1c 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step6/Step6MigrationActivity.kt @@ -52,9 +52,8 @@ import androidx.navigation.compose.rememberNavController import androidx.navigation.navOptions import androidx.navigation3.runtime.EntryProviderBuilder import androidx.navigation3.runtime.NavEntry -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider -import androidx.navigation3.ui.DialogSceneStrategy +import androidx.navigation3.scene.DialogSceneStrategy import androidx.navigation3.ui.NavDisplay import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen diff --git a/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt index e1ee813..7cac64a 100644 --- a/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt +++ b/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt @@ -38,9 +38,8 @@ import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color import androidx.compose.ui.graphics.vector.ImageVector import androidx.navigation3.runtime.EntryProviderBuilder -import androidx.navigation3.runtime.entry import androidx.navigation3.runtime.entryProvider -import androidx.navigation3.ui.DialogSceneStrategy +import androidx.navigation3.scene.DialogSceneStrategy import androidx.navigation3.ui.NavDisplay import com.example.nav3recipes.content.ContentBlue import com.example.nav3recipes.content.ContentGreen From 78dd22b002ca9786f7c2c7dd6cbce6bd35ab40c7 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 17:43:09 +0100 Subject: [PATCH 62/64] Update links in migration guide --- docs/MigratingFromNavigation2.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index 43803d0..7819c22 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -27,12 +27,12 @@ The following features are not yet supported: - Familiarity with [navigation terminology](https://developer.android.com/guide/navigation). - Destinations are Composable functions. Nav3 is designed exclusively for Compose. Fragment destinations can be wrapped with [`AndroidFragment`](https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment(androidx.compose.ui.Modifier,androidx.fragment.compose.FragmentState,android.os.Bundle,kotlin.Function1)) for interoperability with Compose. - Routes are strongly typed. If you are using string-based routes, [migrate to type-safe routes](https://medium.com/androiddevelopers/type-safe-navigation-for-compose-105325a97657) first ([example](https://github.com/android/nowinandroid/pull/1413)). -- Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt). +- Optional but highly recommended: test coverage that verifies existing navigation behavior. These will ensure that during migration, navigation behavior is not changed. See [here for an example of navigation tests](https://github.com/android/nav3-recipes/blob/main/app/src/androidTest/java/com/example/nav3recipes/MigrationActivityNavigationTest.kt). - Your app must have a [minSdk](https://developer.android.com/guide/topics/manifest/uses-sdk-element#min) of 23 or above. ### Step-by-step code examples -A [migration recipe](https://github.com/android/nav3-recipes/tree/dt/2to3migration) exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. +A [migration recipe](https://github.com/android/nav3-recipes/tree/main) exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. To use the migration recipe as a guide: @@ -98,7 +98,7 @@ Important: A fundamental difference between Nav2 and Nav3 is that **you own the To aid with migration, a class which provides and manages a back stack named `Navigator` is provided for you. It is not part of the Nav3 library and it does not provide all the features of Nav2. Instead it is intended to be an assistant during migration, and after to be a starting point for you to implement your own navigation behavior and logic. -Copy the [`Navigator`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt) to the :`core:navigation` module. This class contains `backStack: SnapshotStateList` that can be used with `NavDisplay.It` will mirror `NavController`'s back stack ensuring that Nav2's state remains the source of truth throughout migration. After the migration is complete, the NavController mirroring code will be removed. +Copy the [`Navigator`](https://github.com/android/nav3-recipes/blob/main/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt) to the :`core:navigation` module. This class contains `backStack: SnapshotStateList` that can be used with `NavDisplay.It` will mirror `NavController`'s back stack ensuring that Nav2's state remains the source of truth throughout migration. After the migration is complete, the NavController mirroring code will be removed. ### 2.2 Make the Navigator available everywhere that NavController is @@ -309,8 +309,8 @@ Taking the code example from above. The starting route is A. Review the provided `Navigator` class to ensure that it can model your app's current navigation behavior. In particular: -- Review the [`add`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142) -- Note that `popUpTo` in the [`navigate`](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121) will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. +- Review the [`add`](https://github.com/android/nav3-recipes/blob/main/app/src/main/java/com/example/nav3recipes/migration/step2/Navigator.kt#L142) +- Note that `popUpTo` in the [`navigate`](https://github.com/android/nav3-recipes/blob/main/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L121) will be ignored when switching to Nav3 in the final step. There is no equivalent to `popUpTo` in Nav3 because you control the back stack. The supplied `Navigator` class does, however, include logic to pop all top level stacks up to the starting stack when navigating to a new top level route. This behavior can be toggled using `canTopLevelRoutesExistTogether`. #### 3.2.2 Update routes to implement marker interfaces @@ -503,7 +503,7 @@ Replace any remaining instances of: - Uncomment the code that modifies the back stack directly - Remove all code which references `NavController` -The final `Navigator` [should look like this](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15). +The final `Navigator` [should look like this](https://github.com/android/nav3-recipes/blob/main/app/src/main/java/com/example/nav3recipes/migration/step7/Navigator.kt#L15). ### 7.3 Set the app's start route @@ -515,7 +515,7 @@ val navigator = remember { Navigator(navController, startRoute = RouteA) } ### 7.4 Update common navigation UI components -If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here](https://github.com/android/nav3-recipes/blob/dt/2to3migration/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94). +If using a common navigation component, such as a `NavBar`, change the logic for when a top level route is selected to use `Navigator.topLevelRoute`. [See example here](https://github.com/android/nav3-recipes/blob/main/app/src/main/java/com/example/nav3recipes/migration/step7/Step7MigrationActivity.kt#L94). In Nav2, it was necessary to have a type for both the navigation graph and the start destination of that graph (e.g. `BaseRouteA` and `RouteA`). This is no longer necessary so remove any redundant types for the navigation graph from the :`api` modules. Ensure that the correct types are used to identify top level routes. From 08b63ff010bf709b562d52031d1a0a606963da06 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 17:44:47 +0100 Subject: [PATCH 63/64] Fix link to migration package --- docs/MigratingFromNavigation2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index 7819c22..d23d921 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -32,7 +32,7 @@ The following features are not yet supported: ### Step-by-step code examples -A [migration recipe](https://github.com/android/nav3-recipes/tree/main) exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. +A [migration recipe](https://github.com/android/nav3-recipes/tree/main/app/src/main/java/com/example/nav3recipes/migration) exists to accompany this guide. It starts with an activity containing only Nav2 code. The end state of each migration step is represented by another activity. Instrumented tests verify the navigation behavior in every step. To use the migration recipe as a guide: From 28947aa115f6117e8d9c34f529b12cd0f2ae4605 Mon Sep 17 00:00:00 2001 From: Don Turner Date: Fri, 3 Oct 2025 17:46:16 +0100 Subject: [PATCH 64/64] Fix version --- docs/MigratingFromNavigation2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/MigratingFromNavigation2.md b/docs/MigratingFromNavigation2.md index d23d921..735c974 100644 --- a/docs/MigratingFromNavigation2.md +++ b/docs/MigratingFromNavigation2.md @@ -61,7 +61,7 @@ The latest dependencies can be found here: [https://developer.android.com/guide/ - Update `lib.versions.toml` to include the Nav3 dependencies. Use the [latest version from here](https://developer.android.com/jetpack/androidx/releases/navigation3). ``` -androidxNavigation3 = "1.0.0-alpha11" +androidxNavigation3 = "1.0.0-alpha10" androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "androidxNavigation3" } androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "androidxNavigation3" } ```