2. Basic Usage

How to manipulate the backstack?

The Backstack provides 3 primary operators for manipulating state.

• goTo(): if state does not previously exist in the backstack, then adds it to the stack. Otherwise navigate back to given state.
• goBack(): returns boolean if StateChange is in progress, or if there are more than 1 entries in history (and handled the back press). Otherwise, return false.
• setHistory(): sets the state to the provided elements, with the direction that is specified.

Typically, setHistory() is used with History (or HistoryBuilder) class, which allows you to construct the History<T> with a builder pattern.

There are also secondary operators, namely:

• goUp()
• goUpChain()
• replaceTop()
• jumpToRoot()
• moveToFront()

You can obtain the Backstack from Navigator.getBackstack(context), or backstackDelegate.getBackstack(), depending on which class you use to integrate the BackstackManager.

Handling state changes

When the state stored by the backstack is modified (meaning when you navigated from some view to another), the StateChanger is called to let you handle this state change. The state change contains the previous keys, and the new keys.

When the state change is completed, the completion callback must be called. This callback enables asynchronous state changes as well. As long as a state change is in progress, other state changes are enqueued.

It's important to handle the case where the top previous and the top new keys are the same, typically it is implemented as no-op.

if(stateChange.topNewState().equals(stateChange.topPreviousState()) {
    completionCallback.stateChangeComplete();
    return;
}
// handle state change
completionCallback.stateChangeComplete();