StackNavigator

In package com.nhaarman.acorn.navigation

class com.nhaarman.acorn.navigation.StackNavigator

An abstract Navigator class that uses a stack to navigate through Scenes.

This Navigator supports basic pop and push operations to manipulate the stack. Implementers must implement initialStack to provide the initial stack to work with.

This Navigator is able to save and restore its instance state in saveInstanceState, but does not implement SavableNavigator itself. You can opt in to this state saving by explicitly implementing the SavableNavigator interface.

Constructors

constructor(savedState: NavigatorState?)

An abstract Navigator class that uses a stack to navigate through Scenes.

This Navigator supports basic pop and push operations to manipulate the stack. Implementers must implement initialStack to provide the initial stack to work with.

This Navigator is able to save and restore its instance state in saveInstanceState, but does not implement SavableNavigator itself. You can opt in to this state saving by explicitly implementing the SavableNavigator interface.

Parameters:
  • savedState: NavigatorState?

    An optional instance that contains saved state as returned by saveInstanceState.

Methods

protected abstract fun initialStack(): List

Creates the initial stack of Scenes for this StackNavigator.

The last Scene in the resulting list is regarded as the top element.

Parameters:
  • No parameters
protected abstract fun instantiateScene(sceneClass: KClass, state: SceneState?): Scene

Instantiates a Scene instance for given sceneClass and state.

This function is called when restoring the StackNavigator from a saved state.

Parameters:
  • sceneClass: KClass

    The class of the Scene to instantiate.

  • state: SceneState?

    The saved state of the Scene if applicable. This will be the instance as returned from SavableScene.saveInstanceState if its state was saved.

open fun addNavigatorEventsListener(listener: Events): DisposableHandle

Registers given listener with this Navigator.

Parameters:
fun push(scene: Scene)

Pushes given scene onto the stack.

If this Navigator is currently active, the current Scene will be stopped, and given scene will receive a call to Scene.onStart.

If this Navigator is currently inactive, no Scene lifecycle events will be called at all. Starting this Navigator will trigger a call to the Scene.onStart method of given scene.

Calling this method when this Navigator has been destroyed will have no effect.

Parameters:
  • scene: Scene

    The Scene instance to push.

fun pop()

Pops the top most Scene off the stack.

If this Navigator is currently active, the current child Scene will be stopped and destroyed. If the stack becomes empty, this Navigator will be destroyed, otherwise the new top Scene will be started.

If this Navigator is currently inactive and there is only one element on the stack, the Navigator will be destroyed. Otherwise, the current Scene will be destroyed. Starting this Navigator will trigger a call to the Scene.onStart method of the new top Scene.

Calling this method when the receiving Navigator has been destroyed will have no effect.

Parameters:
  • No parameters
fun replace(scene: Scene)

Replaces the top most Scene with given scene.

If this Navigator is currently active, the current active child Scene will be stopped and destroyed, and given scene will be started.

If this Navigator is currently inactive, the current active child Scene will be destroyed. Starting this Navigator will trigger a call to the Scene.onStart method of given scene.

Parameters:
fun finish()

Finishes this Navigator.

If this Navigator is currently active, the current Scene will go through its destroying lifecycle calling Scene.onStop and Scene.onDestroy.

If this Navigator is currently not active, the current Scene will only have its Scene.onDestroy method called.

Calling this method when the Navigator has been destroyed will have no effect.

Parameters:
  • No parameters
open fun onStart()

Starts this Navigator.

Calling this method when the Navigator is not started or destroyed triggers a call to Scene.onStart for the Scene that is currently active in the Navigator. Listeners registered with addNavigatorEventsListener will be notified of that Scene through Events.scene.

Calling this method when the Navigator is started or destroyed has no effect.

Parameters:
  • No parameters
open fun onStop()

Stops this Navigator.

Calling this method when the Navigator is started triggers a call to Scene.onStop for any Scenes that are currently active in the Navigator.

Calling this method when the Navigator is stopped or destroyed has no effect.

Parameters:
  • No parameters
open fun onDestroy()

Destroys this Navigator.

Calling this method when the Navigator is started will trigger a call to Scene.onStop for the Scene that is currently active in the Navigator. Furthermore, a call to Scene.onDestroy is triggered for every Scene this Navigator is managing.

Calling this method when the Navigator is stopped triggers a call to Scene.onDestroy for every Scene this Navigator is managing.

Calling this method when the Navigator is destroyed has no effect.

When this method has been called, the Navigator must be considered as dead, and no calls to onStart or onStop should be done anymore.

Parameters:
  • No parameters
open fun onBackPressed(): Boolean

Invoked when the user presses the back button.

Parameters:
  • No parameters
open fun isDestroyed(): Boolean

Returns whether this Navigator has been destroyed.

Parameters:
  • No parameters
open fun saveInstanceState(): NavigatorState
Parameters:
  • No parameters