Migrate Navigation back stack, migration, and configuration change snippets - #1229

Code snippets are for:

• https://developer.android.com/guide/navigation/backstack
• https://developer.android.com/guide/navigation/backstack/multi-back-stacks
• https://developer.android.com/guide/navigation/migrate
• https://developer.android.com/guide/navigation/responsive/config-changes

This PR adds 11 region tags, one for each code block it migrates from these pages. 9 are in :views: 8 XML resources and 1 Kotlin block. The other 2 are Kotlin blocks in :compose:snippets. Each page gets its own sub-package, and each graph or menu that the guide prints as a complete file gets its own file.

• Backstack page (:compose:snippets, navigation/backstack/BackStack.kt): android_compose_navigation_backstack_pop_back_stack and android_compose_navigation_backstack_pop_up_to. Both are plain NavController calls. They go in the same module as the page's other Kotlin, which is a Compose example.
• Multi-back-stacks page (:views):
  • nav_graph_multi_back_stacks.xml: android_views_navigation_multi_back_stacks_action
• Migrate page (:views):
  • navigation/migrate/MigrateToNavigation.kt: android_views_navigation_migrate_host_layout
  • nav_graph_migrate_product_list.xml: android_views_navigation_migrate_product_list_graph
  • menu/menu_migrate_activity_main_drawer.xml: android_views_navigation_migrate_drawer_menu
  • nav_graph_migrate_activity_main.xml: android_views_navigation_migrate_drawer_graph
  • nav_graph_migrate_graph_b.xml: android_views_navigation_migrate_graph_b
  • nav_graph_migrate_graph_b_before_combining.xml: android_views_navigation_migrate_graph_b_before_combining
  • nav_graph_migrate_combined.xml: android_views_navigation_migrate_combined_graph
• Config-changes page (:views):
  • nav_graph_config_changes.xml: android_views_navigation_config_changes_destination_label

Dependencies and supporting code

• views/build.gradle.kts and gradle/libs.versions.toml: these files add androidx.navigation:navigation-fragment-ktx, using the androidx-navigation version that's already in the catalog. The two lines are identical to the ones Migrate activity and dialog destination, action, and NavController snippets #1220 and Migrate navigation graph design, Kotlin DSL, nested graph, and Navigation Editor snippets #1221 add, so whichever of these PRs merges first, the others drop the duplicates when they rebase. The library provides the app: attributes that the graphs use (startDestination, destination, argType, popUpTo, popUpToSaveState, and restoreState) and the navigator behind their <fragment> destinations. Nothing else is added. :views already depends on appcompat and material, which cover the Migrate page's AppCompatActivity and menu, and :compose:snippets already depends on navigation-compose.
• The Backstack page's Kotlin regions sit in small private functions that take the navController the page's code assumes.
• nav_graph_multi_back_stacks.xml: the Multi-back-stacks page prints only the <action> element. The file adds a <navigation> root around the region, with two nested graphs, first_stack (start destination first_stack_start_destination) and second_stack, so @id/second_stack and @id/first_stack_start_destination resolve. The action is a global action in that root.
• nav_graph_config_changes.xml: the Config-changes page prints <navigation ...>. An XML start tag can't hold a comment or an exclude, so the region's <navigation> is a nested graph without attributes, inside a root <navigation> that declares the android and tools namespaces (see the list of modifications).
• MigrateToNavigation.kt: the page's ... line just before the comment is a plain exclude that hides super.onCreate(savedInstanceState), which lint's MissingSuperCall check requires.

Compile-driven resources. The snippets need these files to compile, so the files have no region tags:

• views/src/main/res/layout/product_list_host.xml: the Migrate page's Kotlin snippet calls setContentView(R.layout.product_list_host). The page forces the file name. The content is the page's own product_list_host layout from "Create a New Layout to Host the UI", which stays on the guide page.
• views/src/main/res/values/migrate.xml: the strings menu_home, menu_gallery, menu_slideshow, and menu_tools, for the Migrate page's drawer menu (android:title="@string/menu_*"). The names come from the page.
• views/src/main/res/drawable/ic_menu_camera.xml, ic_menu_gallery.xml, ic_menu_slideshow.xml, and ic_menu_manage.xml: the menu's android:icon="@drawable/ic_menu_*" attributes need them. The names come from the page. Each file is a whole Material Icons source file from google/material-design-icons (Apache License 2.0, commit 10ecc147), with this repository's license header added:
  • ic_menu_camera.xml: android/image/photo_camera/materialicons/black/res/drawable/baseline_photo_camera_24.xml
  • ic_menu_gallery.xml: android/image/photo_library/materialicons/black/res/drawable/baseline_photo_library_24.xml
  • ic_menu_slideshow.xml: android/image/slideshow/materialicons/black/res/drawable/baseline_slideshow_24.xml
  • ic_menu_manage.xml: android/action/build/materialicons/black/res/drawable/baseline_build_24.xml
• views/src/main/res/values/config_changes.xml: the string my_dest_label (My destination), for the Config-changes page's android:label="@string/my_dest_label". The name comes from the page.
• compose/snippets/src/main/res/values/backstack.xml: the id destinationId, for R.id.destinationId in the Backstack page's popBackStack() call. The page doesn't print a graph that declares it. The name comes from the page.
• No layout files were added for the graphs' tools:layout references, which only drive the Navigation Editor preview. The build and lint pass without them.

List of modifications (visible diffs vs. the page)

• Backstack page, android_compose_navigation_backstack_pop_up_to: each of the three comments now ends with a full stop.

• Multi-back-stacks page, android_views_navigation_multi_back_stacks_action: the page wraps the attribute values in curly quotes (”). That isn't valid XML, so aapt2 can't compile the snippet as printed. All 10 curly quotes are now straight quotes ("). Nothing else changed.

• Migrate page, android_views_navigation_migrate_host_layout: the three standalone ... lines render as // .... The one before the comment is the exclude described above. The comment Replace setContentView(R.layout.product_list) with the line below now ends with a full stop.

• Config-changes page, android_views_navigation_config_changes_destination_label: <navigation ...> renders as <navigation>. The ... sits inside an XML start tag, where neither a comment nor an exclude can go. The trailing ... line is now a <!-- ... --> comment. Like the page, the snippet has no closing </navigation>.

• Everything else is copied verbatim. That includes:

  • the file-label comments (<!-- activity_main_drawer.xml -->, <!-- activity_main_graph.xml -->, <!-- Graph B -->, and <!-- Combined Graph A and B -->)
  • the page's class names in android:name
  • the quote characters in the Backstack page's comment
  • the page's indentation

  7 of the 11 regions render identically to the page. spotlessApply made no changes.

Lint reports 0 errors. Three warnings point at new files:

• 2 InvalidNavigation warnings ("No start destination specified") in nav_graph_config_changes.xml. The nested <navigation> that renders as the page's <navigation ...> can't carry attributes, and the hidden root only declares the namespaces.
• 1 MergeRootFrame warning in product_list_host.xml, which keeps the page's FrameLayout.

Snippets not migrated

None of these blocks triggers the guide linter's GitHub-snippet check, so none needs a suppression. Where a Kotlin block stays on the guide page, its Java tab stays with it.

• Backstack page (5 blocks):
  • "Handle a failed pop back" Kotlin and Java tabs: will be migrated in a follow-up pull request. The Kotlin starts with a ... placeholder and calls finish(), so it needs an activity around it.
  • "Save state when popping up" Kotlin block: will be migrated in a follow-up pull request. It needs a route value and an A route type that the page doesn't define.
  • "Compose example" MyAppNavHost block: will be migrated in a follow-up pull request. It needs A, B, and DestinationB, which the page doesn't define, and the DestinationB(/* ... */) placeholder needs a ruling.
  • "XML example" <action> block: will be migrated in a follow-up pull request. app:restoreState=”true” uses curly quotes, which isn't valid XML, and the page bolds the app:popUpToSaveState line.
• Multi-back-stacks page (2 blocks): the NavOptions Kotlin and Java blocks will be migrated in a follow-up pull request. The Kotlin needs selectedBottomNavRoute, which the page doesn't define.
• Migrate page (41 blocks):
  • The 3 layout blocks (product_list_host FrameLayout, FragmentContainerView, and the FrameLayout with the NavHostFragment): View-based code.
  • The 18 Kotlin/Java pairs (the ProductListActivity, ProductListFragment, MainActivity, ProductDetailsActivity, and ProductDetailsFragment code, the product click callback, and the navigateToProductDetails() functions): View-based code (activities and fragments).
  • The two "Graph A" navigation graphs (under "Add activity destinations" and "Combine activities"): will be migrated in a follow-up pull request.
  • The Java version of the migrated Kotlin block isn't migrated. The companion guide change removes the Java version.
• Config-changes page (5 blocks):
  • The 3 navigation_activity.xml layout blocks: View-based code.
  • The MainActivity Kotlin and Java blocks: View-based code.

Heads-up, unrelated to this PR and left untouched: spotlessApply logs "Skipping 'build.gradle.kts' because it does not converge" for compose/snippets/build.gradle.kts, which is the same on main.

Build: ./gradlew :views:spotlessApply :compose:snippets:spotlessApply made no changes. Then ./gradlew :views:build and ./gradlew :compose:snippets:build pass.

Companion CL: cl/1008093242