Migrate NavOptions, pass data, conditional navigation, animate transitions, and programmatic navigation snippets - #1227

Code snippets are for:

• https://developer.android.com/guide/navigation/use-graph/navoptions
• https://developer.android.com/guide/navigation/use-graph/pass-data
• https://developer.android.com/guide/navigation/use-graph/conditional
• https://developer.android.com/guide/navigation/use-graph/animate-transitions
• https://developer.android.com/guide/navigation/use-graph/programmatic

Companion CL: cl/1007653640

This PR adds 10 region tags to :views, one for each code block it migrates from these pages: 7 navigation graph XML blocks and 3 Kotlin blocks. Each navigation graph document that a guide prints gets its own file in views/src/main/res/navigation/. The two excerpts that the Pass-data page prints from one graph share a file.

views/... is views/src/main/java/com/example/example/snippet/views.

Dependencies added to :views

• androidx.navigation:navigation-fragment-ktx, as a new androidx-navigation-fragment-ktx catalog entry on the existing androidx-navigation version. The catalog and Gradle lines are identical to the ones in Migrate activity and dialog destination, action, and NavController snippets #1220 and Migrate navigation graph design, Kotlin DSL, nested graph, and Navigation Editor snippets #1221, so whichever of these PRs merges first, the others drop the duplicate lines when they rebase. Directly or through the Navigation runtime library it brings in, it provides:
  • Fragment.findNavController() and NavController.navigate() in the three Navoptions Kotlin snippets, and the navOptions {} builder with its anim {} block.
  • The <navigation>, <fragment>, <action>, and <argument> elements and their app: attributes (startDestination, destination, enterAnim, exitAnim, popEnterAnim, popExitAnim, popUpTo, popUpToInclusive, argType) in the six graph files.
• androidx.navigation:navigation-ui, as a new androidx-navigation-ui catalog entry on the same version. The Navoptions page's graph uses the library's default transition animations, @anim/nav_default_enter_anim, @anim/nav_default_exit_anim, @anim/nav_default_pop_enter_anim, and @anim/nav_default_pop_exit_anim. They come from this artifact, and resource linking fails without it. It's the artifact the Navigation dependency instructions list.

No other dependency or plugin is added.

Supporting code and resources

Everything in this section sits outside the region tags, so none of it shows on the guide pages.

• NavigateWithOptions.kt: each region sits in a small private function. navController and deepLinkUri (a Uri) are parameters. The two regions that call findNavController() without a receiver are private Fragment extension functions, so the call resolves to the Fragment extension.
• nav_graph_pass_data.xml: the Pass-data page prints only a <fragment> and an <action> from one graph. The file adds the <navigation> root (the namespaces and app:startDestination="@id/myFragment") around both regions. The <action> is a global action whose destination is the region's myFragment.
• nav_graph_pass_data_global_action.xml: the page's ... line is a plain exclude that hides a mainFragment destination, which app:startDestination="@id/mainFragment" needs. It renders as ..., like the page.
• nav_graph_animate_transitions.xml: the Animate-transitions page prints only the <fragment> element. The file adds the <navigation> root (with the android, app, and tools namespaces) around the region, and a confirmationFragment destination after it, so that the action's app:destination="@id/confirmationFragment" resolves.
• The tools:layout references only affect the Navigation Editor preview, so no layout files are added for them. The class names in android:name are kept as printed.

Compile-driven resources (required for the snippets to compile, no region tags):

• views/src/main/res/values/navoptions.xml: the id action_fragmentOne_to_fragmentTwo, for R.id.action_fragmentOne_to_fragmentTwo in the Navoptions page's programmatic Kotlin snippet. The page's graph doesn't contain that action, so the id is declared on its own. The name comes from the page.
• views/src/main/res/anim/slide_in_right.xml, slide_out_left.xml, slide_in_left.xml, and slide_out_right.xml: the Animate-transitions page's action references @anim/slide_in_right, @anim/slide_out_left, @anim/slide_in_left, and @anim/slide_out_right, and resource linking fails while they're undefined. Nothing in this repository or in :views' dependencies provides them. The names come from the page. Each file is a single <translate> animation written for this PR: the view slides in from, or out to, the side its name says, over @android:integer/config_mediumAnimTime.

List of modifications (visible diffs vs. the page)

• Navoptions, Pass-data (global action), and Programmatic pages: the page's graphs start with <?xml version="1.0" encoding="utf-8"?>. That line has to be the first line of the file, ahead of the license header, so it can't be inside a region. These 3 regions start at <navigation.
• Navoptions page, android_views_navigation_navoptions_programmatic: spotlessApply indents the call's three arguments by 4 spaces and lines up the closing brace of the navOptions {} block with them. On the page, the arguments started at the same column as findNavController(), and the closing brace was indented 2 spaces. The line count is unchanged.
• Navoptions page, android_views_navigation_navoptions_programmatic and android_views_navigation_navoptions_deep_link: the comment Use the Kotlin DSL for building NavOptions now ends with a full stop.
• Pass-data (global action), Animate-transitions, and Programmatic pages: the lines that the page prints in bold stay highlighted: android:id="@+id/main_nav"; the four app:*Anim attributes; and app:startDestination plus the home destination's android:id and android:name. The companion CL passes their line numbers to the snippet include.
• Everything else is copied verbatim, including the page's class names, ids, and indentation. The Navoptions navigate() line and the Pass-data <fragment> excerpt render without the extra leading spaces that the page printed before them.

Snippets not migrated

• Navoptions page: the Java versions of the two migrated Kotlin blocks. The companion CL removes them, so the page shows only the Kotlin snippets.
• Pass-data page:
  • Safe Args code, which stays on the page: the onClick() block that calls SpecifyAmountFragmentDirections, and the navArgs() block that reads ConfirmationFragmentArgs. The Safe Args Gradle plugin generates these classes, and this repository doesn't apply that plugin.
  • Fragment-based code: the two blocks under "Pass data between destinations with Bundle objects" (bundleOf() with navigate(), and reading the argument into a TextView).
  • The @Keep ParcelableArg block: will be migrated in a follow-up pull request. Its { ... } class body is a placeholder that needs a ruling on how to show it.
  • The proguard-rules.pro block: ProGuard/R8 keep rules, which are tool configuration and stay on the page.
• Safe-args page: both onClick() examples (the "Safe Args example" and the one under "Ensure type safety by using Safe Args") stay on the page. They call classes that the Safe Args Gradle plugin generates, and this repository doesn't apply that plugin.
• Conditional page: the five ProfileFragment and LoginFragment Kotlin blocks are Fragment-based code.
• Animate-transitions page:
  • Fragment-based code: the shared element block for a fragment destination (FragmentNavigatorExtras).
  • View-based code: the shared element block for an activity destination (ActivityOptions) and the finish() override, which are Activity code.
• Programmatic page:
  • Fragment-based code: NavHostFragment.create(), the two onViewCreated() blocks (returning a result, and dialog destinations), the two navGraphViewModels() blocks, and the NavHostFragment block under "Modifying inflated navigation graphs".
  • Will be migrated in a follow-up pull request: the LiveData observer on a NavBackStackEntry, and previousBackStackEntry?.savedStateHandle?.set().
• The Java versions of the Kotlin blocks above stay on the pages with their Kotlin blocks.

The follow-up pull request will add those blocks to :views, next to this PR's files.

Heads-up, unrelated to this PR and left untouched: spotlessApply logs "Skipping 'build.gradle.kts' because it does not converge" for views/build.gradle.kts, which has a nonstandard license header on main.

Build: ./gradlew :views:spotlessApply (one formatting change, listed above; a second run changes nothing), then ./gradlew :views:build passes. The added files have no compiler warnings and no lint findings.