NavigationEventHandler

<T : NavigationEventInfo> NavigationEventHandler(
    initialInfo: T,
    isBackEnabled: Boolean
)

Creates a handler that is only enabled for back navigation gestures.

Forward navigation will be disabled by default.

fun remove(): Unit

Removes this handler from the NavigationEventDispatcher it is registered with. If the handler is not registered, this call does nothing.

fun setInfo(
    currentInfo: T,
    backInfo: List<T> = emptyList(),
    forwardInfo: List<T> = emptyList()
): Unit

Sets the directional navigation context for this handler.

Updates the three pieces of contextual information used to describe navigation affordances:

• currentInfo: the active destination.

• backInfo: contextual information for back navigation (nearest-first).

• forwardInfo: contextual information for forward navigation (nearest-first).

The lists are app-defined NavigationEventInfo values (e.g., titles or metadata) that help the UI present navigation affordances or previews. An empty list indicates no affordance in that direction.

@EmptySuper
protected open fun onBackCancelled(): Unit

Override this to handle the cancellation of a back navigation event.

This is called when the user cancels the navigation action, signaling that the UI should return to its original state.

@EmptySuper
protected open fun onBackCompleted(): Unit

Override this to handle the completion of a back navigation event.

This is called when the user commits to the back navigation action, signaling that the navigation should be finalized.

The default implementation throws an UnsupportedOperationException. Any handler that can be completed must override this method to handle the navigation.

@EmptySuper
protected open fun onBackProgressed(event: NavigationEvent): Unit

Override this to handle the progress of an ongoing back navigation event.

This is called repeatedly during a gesture-driven back navigation to update the UI in real-time based on the user's input.

@EmptySuper
protected open fun onBackStarted(event: NavigationEvent): Unit

Override this to handle the beginning of a back navigation event.

This is called when a user action initiates a back navigation. It's the ideal place to prepare UI elements for a transition.

@EmptySuper
protected open fun onForwardCancelled(): Unit

Override this to handle the cancellation of a forward navigation event.

This is called when the user cancels the navigation action, signaling that the UI should return to its original state.

@EmptySuper
protected open fun onForwardCompleted(): Unit

Override this to handle the completion of a forward navigation event.

This is called when the user commits to the forward navigation action, signaling that the navigation should be finalized.

The default implementation throws an UnsupportedOperationException. Any handler that can be completed must override this method to handle the navigation.

@EmptySuper
protected open fun onForwardProgressed(event: NavigationEvent): Unit

Override this to handle the progress of an ongoing forward navigation event.

This is called repeatedly during a gesture-driven forward navigation to update the UI in real-time based on the user's input.

@EmptySuper
protected open fun onForwardStarted(event: NavigationEvent): Unit

Override this to handle the beginning of a forward navigation event.

This is called when a user action initiates a forward navigation. It's the ideal place to prepare UI elements for a transition.

val backInfo: List<T>

Contextual information describing the application's back state for this handler.

This is not a back stack. Instead, it contains app-defined NavigationEventInfo values (for example, titles or metadata) that help render back affordances in the UI. The list may be empty if no back navigation is possible in this scope.

val currentInfo: T

The contextual information representing the active destination for this handler.

This is always a single value, provided by the currently active handler, and reflects the foreground navigation state at this point in time.

val forwardInfo: List<T>

Contextual information describing the application's forward state for this handler.

This is not a forward stack. Instead, it contains app-defined NavigationEventInfo values that help render forward affordances in the UI. The list may be empty if no forward navigation is possible in this scope.

var isBackEnabled: Boolean

Controls whether this handler is active and should be considered for back event dispatching.

A handler's effective enabled state is hierarchical; it is directly influenced by the NavigationEventDispatcher it is registered with.

Getting the value:

• This will return false if the associated dispatcher exists and its isEnabled state is false, regardless of the handler's own local setting. This provides a powerful mechanism to disable a whole group of handlers at once by simply disabling their dispatcher.

• Otherwise, it returns the handler's own locally stored state.

Setting the value:

• This updates the local enabled state of the handler itself.

• More importantly, it immediately notifies the dispatcher (if one is attached) that its list of enabled handlers might have changed, prompting a re-evaluation. This ensures the system's state remains consistent and responsive to changes.

For a handler to be truly active, both its local isEnabled property and its dispatcher's isEnabled property must evaluate to true.

var isForwardEnabled: Boolean

Controls whether this handler is active and should be considered for forward event dispatching.

A handler's effective enabled state is hierarchical; it is directly influenced by the NavigationEventDispatcher it is registered with.

Getting the value:

• This will return false if the associated dispatcher exists and its isEnabled state is false, regardless of the handler's own local setting.

• Otherwise, it returns the handler's own locally stored state.

Setting the value:

• This updates the local enabled state of the handler itself.

• It immediately notifies the dispatcher (if one is attached) that its list of enabled handlers might have changed, prompting a re-evaluation.

For a handler to be truly active for forward events, both its local isForwardEnabled property and its dispatcher's isEnabled property must evaluate to true.

val transitionState: NavigationEventTransitionState

The current transition state of this specific handler (e.g., Idle or InProgress).

This state is updated by the dispatcher before the corresponding on... lifecycle methods (e.g., onBackStarted) are called.