Migrating to DestinationNavigator2¶
DestinationNavigator will be deprecated and removed in a future release. Its
two jobs are split into two types:
DestinationNavigator2for back stack navigation and navigation results. It is available on all platforms.PlatformNavigatorfor activity and permission navigation. On Android it is anActivityNavigator.
Follow the migration steps as indicated below:
Behavior changes¶
navigateBack,navigateUp,navigateBackToandnavigate { ... }are ignored while the destination is not the current one. WithDestinationNavigatorthey always ran. Code that relies on these calls while another destination is on top will stop working. For example, closing the screen in reaction to aFlowor another async event while a dialog or bottom sheet is shown on top of it. The calls are not queued, so they do not run later either. Check such code before migrating.registerForNavigationResultwith the destination’s own route type no longer throws when the destination has already left the back stack. Previously this could cause a crash when a result was received after the destination left the back stack. Workarounds for that crash, likeby lazy,try/catchor nullable result requests, can be removed.
Navigator without platform navigation¶
This covers navigators that only use back stack navigation and navigation results.
Before:
@SingleIn(ExampleRoute::class)
@ForScope(ExampleRoute::class)
@ContributesBinding(ExampleRoute::class)
class ExampleNavigator(
hostNavigator: HostNavigator,
) : DestinationNavigator(hostNavigator) {
val colorResult = registerForNavigationResult<ExampleRoute, Color>()
fun showColorPicker() {
navigateTo(ColorPickerRoute(colorResult.key))
}
fun close() {
navigateBack()
}
}
After:
@Inject
class ExampleNavigator(
navigator: DestinationNavigator2,
) : DestinationNavigator2 by navigator {
val colorResult = registerForNavigationResult<ExampleRoute, Color>()
fun showColorPicker() {
navigateTo(ColorPickerRoute(colorResult.key))
}
fun close() {
navigateBack()
}
}
Steps:
- Replace the
HostNavigatorparameter withDestinationNavigator2and delegate to it withby. - Remove
@ContributesBindingand@ForScope. ADestinationNavigatorbinding is no longer needed. Keep@SingleIn(ExampleRoute::class)only if the navigator holds state that must be shared.
Tests:
val hostNavigator = TestHostNavigator()
val navigator = ExampleNavigator(hostNavigator.destinationNavigator())
hostNavigator.test {
navigator.close()
awaitNavigateBack()
}
Before, tests passed the TestHostNavigator to the constructor and called
navigator.test { }. Now call hostNavigator.test { }.
Navigator with platform navigation and results¶
This covers navigators that also navigate to activities or request permissions.
Move that part into a separate class that injects PlatformNavigator.
Before:
@SingleIn(ExampleRoute::class)
@ForScope(ExampleRoute::class)
@ContributesBinding(ExampleRoute::class)
class ExampleNavigator(
hostNavigator: HostNavigator,
) : DestinationNavigator(hostNavigator) {
val colorResult = registerForNavigationResult<ExampleRoute, Color>()
val cameraPermissionRequest = registerForPermissionsResult()
fun showColorPicker() {
navigateTo(ColorPickerRoute(colorResult.key))
}
fun requestCameraPermission() {
requestPermissions(cameraPermissionRequest, Manifest.permission.CAMERA)
}
fun openAppSettings() {
navigateTo(AppSettingsRoute)
}
}
After:
@SingleIn(ExampleRoute::class)
@Inject
class ExampleActivityNavigator(
@ForScope(ExampleRoute::class)
private val platformNavigator: PlatformNavigator,
) {
val cameraPermissionRequest =
platformNavigator.registerForPermissionsResult()
fun requestCameraPermission() {
platformNavigator.requestPermissions(
cameraPermissionRequest,
Manifest.permission.CAMERA,
)
}
fun openAppSettings() {
platformNavigator.navigateTo(AppSettingsRoute)
}
}
@Inject
class ExampleNavigator(
navigator: DestinationNavigator2,
val activityNavigator: ExampleActivityNavigator,
) : DestinationNavigator2 by navigator {
val colorResult = registerForNavigationResult<ExampleRoute, Color>()
fun showColorPicker() {
navigateTo(ColorPickerRoute(colorResult.key))
}
}
Steps:
- Do the steps from the previous section for
ExampleNavigator. - Move
registerForActivityResult,registerForPermissionsResultand everynavigateTo,navigateForResultorrequestPermissionscall for an activity route or permission into a new class that injects@ForScope(ExampleRoute::class) PlatformNavigator. - Annotate the new class with
@SingleIn(ExampleRoute::class). It must be scoped to the destination to avoid registering its requests again when the UI is recreated. - Inject the new class directly into
ExampleNavigatoror the state machine, as shown above. It must be created before the screen is shown, because it registers its requests when it is created. Do not inject it asLazyorProvider, which delays creating it.
The state machine can keep using ExampleNavigator only. It calls
navigator.activityNavigator.requestCameraPermission(), or ExampleNavigator
can forward the call with its own function.
Tests:
val hostNavigator = TestHostNavigator()
val platformNavigator = hostNavigator.platformNavigator()
val navigator = ExampleNavigator(
hostNavigator.destinationNavigator(),
ExampleActivityNavigator(platformNavigator),
)
platformNavigator.test {
navigator.activityNavigator.requestCameraPermission()
awaitRequestPermissions(
navigator.activityNavigator.cameraPermissionRequest,
Manifest.permission.CAMERA,
)
}
hostNavigator.test {
navigator.showColorPicker()
awaitNavigateTo(ColorPickerRoute(navigator.colorResult.key))
}
Use platformNavigator.test { } for activity and permission events and
hostNavigator.test { } for back stack events. hostNavigator.test { } does
not see activity or permission events. Results are sent the same way as before,
for example
navigator.activityNavigator.cameraPermissionRequest.sendResult(...).