Skip to content

Navigation with Child Stack

The PanelsNavigator

All navigation in Child Panels is performed using the PanelsNavigator interface, which is extended by the PanelsNavigation interface.

PanelsNavigator contains the navigate method with the following arguments:

  • transformer - converts the current Panels state to a new one.
  • onComplete - called when navigation is finished.

There is also navigate extension function without the onComplete callback, for convenience.

Creating the navigation
// In your component class
val navigation = PanelsNavigation<Configuration>()

The navigation process

During the navigation process, the Child Panels navigation model compares the new state with the previous one. It ensures that all removed components are destroyed, and all created components have correct lifecycle states

The Child Panels navigation model usually performs the navigation synchronously, which means that by the time the navigate method returns, the navigation is finished and all component lifecycles are moved into required states. However, the navigation is performed asynchronously in case of recursive invocations - e.g. navigate is called from onResume lifecycle callback of a component being pushed. All recursive invocations are queued and performed one by one once the current navigation is finished.

PanelsNavigator extension functions

There are PanelsNavigator extension functions to simplify the navigation. Some of which were already used in the Child Panels Overview example.

Sets the provided Main, Details and Extra configurations.

Illustration 1

Before
{Main1, Details1, Extra1, SINGLE}

navigation.navigate(main = Main2, details = Details2, extra = Extra2)
After
{Main2, Details2, Extra2, SINGLE}

Illustration 2

Before
{Main1, Details1, Extra1, SINGLE}

navigation.navigate(main = Main2, details = null, extra = null)
After
{Main2, null, null, SINGLE}

Sets the provided Details and Extra configurations.

Illustration 1

Before
{Main1, Details1, Extra1, SINGLE}

navigation.navigate(details = Details2, extra = Extra2)
After
{Main1, Details2, Extra2, SINGLE}

Illustration 2

Before
{Main1, Details1, Extra1, SINGLE}

navigation.navigate(details = null, extra = null)
After
{Main1, null, null, SINGLE}

Sets the provided Extra configuration.

Illustration 2

Before
{Main1, Details1, Extra1, SINGLE}

navigation.navigate(extra = Extra2)
After
{Main1, Details1, Extra2, SINGLE}

Illustration 2

Before
{Main1, Details1, Extra1, SINGLE}

navigation.navigate(extra = null)
After
{Main1, Details1, null, SINGLE}

activateMain(main)

Activates the Main component represented by the specified main configuration, and dismisses (destroys) any currently active Main component.

Illustration

Before
{Main1, Details1, Extra1, SINGLE}

navigation.activateMain(main = Main2)
After
{Main2, Details1, Extra1, SINGLE}

activateDetails(details)

Activates the Details component represented by the specified details configuration, and dismisses (destroys) any currently active Details component.

Illustration 1

Before
{Main1, null, Extra1, SINGLE}

navigation.activateDetails(details = Details1)
After
{Main1, Details1, Extra1, SINGLE}

Illustration 2

Before
{Main1, Details1, Extra1, SINGLE}

navigation.activateDetails(details = Details2)
After
{Main1, Details2, Extra1, SINGLE}

dismissDetails()

Dismisses (destroys) the currently active Details component, if any.

Illustration 1

Before
{Main1, Details1, Extra1, SINGLE}

navigation.dismissDetails()
After
{Main1, null, Extra1, SINGLE}

Illustration 2

Before
{Main1, null, Extra1, SINGLE}

navigation.dismissDetails()
After
{Main1, null, Extra1, SINGLE}

activateExtra(extra)

Activates the Extra component represented by the specified extra configuration, and dismisses (destroys) any currently active Extra component.

Illustration 1

Before
{Main1, Details1, null, SINGLE}

navigation.activateExtra(extra = Extra1)
After
{Main1, Details1, Extra1, SINGLE}

Illustration 2

Before
{Main1, Details1, Extra1, SINGLE}

navigation.activateExtra(extra = Extra2)
After
{Main1, Details1, Extra2, SINGLE}

dismissExtra()

Dismisses (destroys) the currently active Extra component, if any.

Illustration 1

Before
{Main1, Details1, Extra1, SINGLE}

navigation.dismissExtra()
After
{Main1, Details1, null, SINGLE}

Illustration 2

Before
{Main1, Details1, null, SINGLE}

navigation.dismissExtra()
After
{Main1, Details1, null, SINGLE}

pop()

Dismisses the Extra component (if it exists) or the Details component (if it exists).

Illustration 1

Before
{Main1, Details1, Extra1, SINGLE}

navigation.pop()
After
{Main1, Details1, null, SINGLE}

Illustration 2

Before
{Main1, Details1, null, SINGLE}

navigation.pop()
After
{Main1, null, null, SINGLE}

Illustration 3

Before
{Main1, null, null, SINGLE}

navigation.pop()
After
{Main1, null, null, SINGLE}

setMode(mode)

Sets Panels.mode to the specified mode value and updates component lifecycles accordingly.

Illustration

Before
{Main1, Details1, Extra1, SINGLE}

navigation.setMode(ChildPanelsMode.DUAL)
After
{Main1, Details1, Extra1, DUAL}