There are some base Navigator implementations to help you get started. Each of these implementations provide a default saveInstanceState() implementation allow their state to be saved, and each has their own strategy to do this. None of them actually implement SavableNavigator however, you can opt into their state saving ability by explicitly implementing the SavableNavigator interface.

SingleSceneNavigator¹

The SingleSceneNavigator is a very basic Navigator that is only able to host a single Scene during its lifetime, without ever navigating to a different Scene. This class can sometimes come in useful when composing Navigators.

The SingleSceneNavigator provides a single abstract createScene method that needs to be overridden, which provides the Scene to use in this Navigator. If the Navigator is restored from a saved state and the Scene implements SavableScene, the createScene method will be called with the instance that was returned in SavableScene#saveInstanceState.

1 class MyHelloWorldNavigator(
2     savedState: NavigatorState?
3 ) : SingleSceneNavigator(savedState) {
4 
5     override fun createScene(state: SceneState?) : Scene<out Container> {
6         return HelloWorldScene(state)
7     }
8 }

The SingleSceneNavigator will automatically save its own and the Scene's instance state when necessary, and reconstruct itself from any saved state passed to its constructor.

ReplacingNavigator¹

The ReplacingNavigator is a Navigator that can switch between several different Scenes, but has no back behavior. When the user presses the back button, the Navigator will always directly finish regardless of how many Scenes it has seen.

The ReplacingNavigator provides an abstract method initialScene that needs to be overridden, which provides the initial Scene to use when not restored from a saved state. When the ReplacingNavigator is restored from a saved state, this method will not be called.

Instead to support state restoration, this ReplacingNavigator provides an abstract instantiateScene method which takes in a KClass<Scene<*>> and an optional SceneState instance. Since state saving can occur at any time, users of the ReplacingNavigator must be able to handle all Scenes used in it, even if the Scene itself does not implement SavableScene.

 1 class MyNavigator(
 2     savedState: NavigatorState?
 3 ) : ReplacingNavigator(savedState) {
 4 
 5     override fun initialScene() : Scene<out Container> {
 6         return MyFirstScene()
 7     }
 8 
 9     fun onEvent() {
10         replace(MySecondScene())
11     }
12 
13     override fun instantiateScene(
14         sceneClass: KClass<out Scene<*>>,
15         state: SceneState?
16     ) : Scene<out Container> {
17         return when(sceneClass) {
18             MyFirstScene::class -> MyFirstScene(state)
19             MySecondScene::class -> MySecondScene(state)
20             else -> error("Unknown scene class: $sceneClass")
21         }
22     }
23 }

To switch Scenes in the ReplacingNavigator, the class provides a replace method. When calling this method, the ReplacingNavigator will handle the previous and new Scenes' lifecycle methods appropriately and notify any listeners of the change in scenery.

StackNavigator¹

The StackNavigator base class is the class you'll feel most familiar with, as it uses a stack to model its internal state. You can push Scenes on the stack, pop them off, or replace the top Scene with another one. Pressing the back button will pop the top Scene off the stack.

The StackNavigator provides an abstract method initialStack that needs to be overridden, which provides the initial Scene stack to use when not restored from a saved state. When the StackNavigator is restored from a saved state, this method will not be called.

Instead to support state restoration, this StackNavigator provides an abstract instantiateScene method which takes in a KClass<Scene<*>> and an optional SceneState instance. Since state saving can occur at any time, users of the StackNavigator must be able to handle all Scenes used in it, even if the Scene itself does not implement SavableScene. The StackNavigator will take care of preserving the order of the stack.

 1 class MyNavigator(
 2     savedState: NavigatorState?
 3 ) : StackNavigator(savedState) {
 4 
 5     override fun initialStack() : List<Scene<out Container>> {
 6         return listOf(MyFirstScene())
 7     }
 8 
 9     fun onEvent() {
10         push(MySecondScene())
11     }
12 
13     override fun instantiateScene(
14         sceneClass: KClass<out Scene<*>>,
15         state: SceneState?
16     ) : Scene<out Container> {
17         return when(sceneClass) {
18             MyFirstScene::class -> MyFirstScene(state)
19             MySecondScene::class -> MySecondScene(state)
20             else -> error("Unknown scene class: $sceneClass")
21         }
22     }
23 }

To manipulate the stack in the StackNavigator, the class provides three methods: push, pop, and replace. When calling one of these methods, the StackNavigator will handle the Scenes' lifecycle methods appropriately and will notify any listeners of the change in scenery.

1: This class is available in the ext-acorn artifact.