NavigationEventHandler

public <T extends NavigationEventInfo> NavigationEventHandler(
    @NonNull T initialInfo,
    boolean isBackEnabled
)

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

Forward navigation will be disabled by default.

public final @NonNull List<@NonNull T> getBackInfo()

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.

public final @NonNull T getCurrentInfo()

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.

public final @NonNull List<@NonNull T> getForwardInfo()

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.

public final @NonNull NavigationEventTransitionState getTransitionState()

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.

public final boolean isBackEnabled()

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.

public final boolean isForwardEnabled()

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.

public final void remove()

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

public final void setBackEnabled(boolean isBackEnabled)

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.

public final void setForwardEnabled(boolean isForwardEnabled)

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.

public final void setInfo(
    @NonNull T currentInfo,
    @NonNull List<@NonNull T> backInfo,
    @NonNull List<@NonNull T> forwardInfo
)

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 void onBackCancelled()

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 void onBackCompleted()

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 void onBackProgressed(@NonNull NavigationEvent event)

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 void onBackStarted(@NonNull NavigationEvent event)

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 void onForwardCancelled()

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 void onForwardCompleted()

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 void onForwardProgressed(@NonNull NavigationEvent event)

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 void onForwardStarted(@NonNull NavigationEvent event)

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.