Lifecycle¶

Nodes have their own lifecycles, directly using the related classes of androidx.lifecycle.

Capping¶

No node can be in a higher lifecycle state than any of its parents or the Android Activity it lives in.

On-screen & off-screen¶

NavModel controls which children should be rendered on the screen and which should not with NavModel.screenState. The behaviour is customisable in BaseNavModel via OnScreenStateResolver.

When a NavElement of the node is marked as on-screen, its lifecycle follows the parent node's lifecycle. The rendering status does not affect it – the node might not be added to Compose view and still be in a RESUMED state.

When a NavElement of the node is marked as off-screen, the following might happen:

Its lifecycle is capped with CREATED (or STOPPED) in case of ChildEntry.KeepMode.KEEP.
The node is destroyed and its state is saved in case of ChildEntry.KeepMode.SUSPEND.

ChildEntry.KeepMode settings can be configured for each ParentNode individually or globally via Appyx.defaultChildKeepMode.

When a node is removed completely from NavModel, it will be in DESTROYED state.

Lifecycle changes¶

The lifecycle state can be affected by:

The NavModel of the parent (adding or removing child Nodes and changing their on-screen status)
The parent's lifecycle state capping its children (transitive in the tree)
Android lifecycle (Activity) capping the whole tree

Back stack node lifecycle¶

An example demonstrating the above:

Note that NavModels might have their slight differences (e.g. whether their operations remove a Node only from the view, or completely destroy it).

In the case of the back stack:

The Push operation adds a new element and stashes the currently active one – the stashed one will be removed from the view & STOPPED
The Pop operation removes an element, the child Node will be DESTROYED