ThreePaneScaffoldNavigator

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 key/id 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 Any.

Summary

Public functions
Boolean
canNavigateBack(backNavigationBehavior: BackNavigationBehavior)

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

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

Navigates to a new destination.
Cmn
ThreePaneScaffoldValue
peekPreviousScaffoldValue(
    backNavigationBehavior: BackNavigationBehavior
)

Returns the scaffold value associated with the previous destination, assuming there is a previous destination to navigate back to.
Cmn
suspend Unit
seekBack(
    backNavigationBehavior: BackNavigationBehavior,
    fraction: @FloatRange(from = 0.0, to = 1.0) Float
)

Seeks the scaffoldState transition to the previous destination, as in a predictive back animation.
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
ThreePaneScaffoldState

The current state of the associated three pane scaffold, used to query the transition between layout states.
Cmn
ThreePaneScaffoldValue

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

Public functions

canNavigateBack

Cmn 
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 
suspend 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.1.0-alpha04
suspend fun navigateTo(pane: ThreePaneScaffoldRole, contentKey: 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.
contentKey: T? = null

the optional key or id representing the content of the new destination.

peekPreviousScaffoldValue

Cmn 
fun peekPreviousScaffoldValue(
    backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
): ThreePaneScaffoldValue

Returns the scaffold value associated with the previous destination, assuming there is a previous destination to navigate back to. If not, this is the same as scaffoldValue.

Parameters
backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange

the behavior describing which backstack entries may be skipped during the back navigation. See BackNavigationBehavior.

seekBack

Cmn 
suspend fun seekBack(
    backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange,
    fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f
): Unit

Seeks the scaffoldState transition to the previous destination, as in a predictive back animation.

This does not affect the current scaffoldValue or backstack. To do so, call navigateBack when the back navigation action is finalized.

Parameters
backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange

the behavior describing which backstack entries may be skipped during the back navigation. See BackNavigationBehavior.
fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f

the progress fraction of the transition of backwards navigation.

Public properties

currentDestination

Cmn
Added in 1.0.0
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
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
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.

scaffoldState

Cmn
Added in 1.1.0-alpha04
val scaffoldState: ThreePaneScaffoldState

The current state of the associated three pane scaffold, used to query the transition between layout states.

scaffoldValue

Cmn
Added in 1.0.0
val scaffoldValue: ThreePaneScaffoldValue

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