The common interface of the default navigation implementations for different three-pane scaffolds.

In general, we suggest you to use rememberListDetailPaneScaffoldNavigator or rememberSupportingPaneScaffoldNavigator to get remembered default instances of this interface for ListDetailPaneScaffold and SupportingPaneScaffold, respectively. Those default implementations work independently from any navigation frameworks.

If you need to integrate with existing navigation frameworks or implement your own custom navigation logic, usually creating whole new APIs that's tailored for your own solution will be recommended, instead of implementing this interface. But we recommend you refer to the API design and the default implementation to get better understanding and address the intricacies of navigation in an adaptive scenario.

Parameters
<T : Any?>

the type representing the content, or id of the content, for a navigation destination. This type must be storable in a Bundle. Used to customize navigation behavior (for example, BackNavigationBehavior). If this customization is unneeded, you can pass Nothing.

Summary

Public functions
Boolean
canNavigateBack(backNavigationBehavior: BackNavigationBehavior)

Returns true if there is a previous destination to navigate back to.
Cmn
Boolean
navigateBack(backNavigationBehavior: BackNavigationBehavior)

Navigates to the previous destination.
Cmn
Unit
navigateTo(pane: ThreePaneScaffoldRole, content: T?)

Navigates to a new destination.
Cmn

Public properties
ThreePaneScaffoldDestinationItem<T>?

The current destination as tracked by the navigator.
Cmn
Boolean

Indicates if the navigator should be aware of pane destination history when deciding the result ThreePaneScaffoldValue by a navigation operation.
Cmn
PaneScaffoldDirective

The current layout directives that the associated three pane scaffold needs to follow.
Cmn
ThreePaneScaffoldValue

The current layout value of the associated three pane scaffold value, which represents unique layout states of the scaffold.
Cmn

Public functions

canNavigateBack

Cmn
Added in 1.0.0-alpha11
fun canNavigateBack(
    backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
): Boolean

Returns true if there is a previous destination to navigate back to.

Implementors of this interface should ensure the logic of this function is consistent with navigateBack.

Parameters
backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange

the behavior describing which backstack entries may be skipped during the back navigation. See BackNavigationBehavior.
Cmn
Added in 1.0.0-alpha11
fun navigateBack(
    backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
): Boolean

Navigates to the previous destination. Returns true if there is a previous destination to navigate back to.

Implementors of this interface should ensure the logic of this function is consistent with canNavigateBack.

Parameters
backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange

the behavior describing which backstack entries may be skipped during the back navigation. See BackNavigationBehavior.
Cmn
Added in 1.0.0-alpha11
fun navigateTo(pane: ThreePaneScaffoldRole, content: T? = null): Unit

Navigates to a new destination. The new destination is supposed to have the highest priority when calculating the new scaffoldValue.

Implementors of this interface should ensure the new destination pane will be expanded or adapted in a reasonable way so it provides users the sense that the new destination is the pane currently being used.

Parameters
pane: ThreePaneScaffoldRole

the new destination pane.
content: T? = null

the optional content, or an id representing the content of the new destination.

Public properties

currentDestination

Cmn
Added in 1.0.0-alpha11
val currentDestination: ThreePaneScaffoldDestinationItem<T>?

The current destination as tracked by the navigator.

Implementors of this interface should ensure this value is updated whenever a navigation operation is performed.

isDestinationHistoryAware

Cmn
Added in 1.0.0-alpha11
var isDestinationHistoryAware: Boolean

Indicates if the navigator should be aware of pane destination history when deciding the result ThreePaneScaffoldValue by a navigation operation. If the value is false, only the current destination will be considered in the scaffold value calculation.

See also
calculateThreePaneScaffoldValue

for more detailed explanation about history awareness.

scaffoldDirective

Cmn
Added in 1.0.0-alpha11
val scaffoldDirective: PaneScaffoldDirective

The current layout directives that the associated three pane scaffold needs to follow. It's supposed to be automatically updated when the window configuration changes.

scaffoldValue

Cmn
Added in 1.0.0-alpha11
val scaffoldValue: ThreePaneScaffoldValue

The current layout value of the associated three pane scaffold value, which represents unique layout states of the scaffold.