NavigationEventDispatcher

public final class NavigationEventDispatcher

A dispatcher for navigation events that can be organized hierarchically.

This class acts as a localized entry point for registering NavigationEventCallback instances and dispatching navigation events within a specific UI scope, such as a composable or a fragment.

Dispatchers can be linked in a parent-child hierarchy. This structure allows for a sophisticated system where nested UI components can handle navigation events independently while still respecting the state of their parent. The core logic is delegated to a single, shared NavigationEventProcessor instance across the entire hierarchy, ensuring consistent event handling.

It is important to call dispose when the owner of this dispatcher is destroyed (e.g., in a DisposableEffect) to unregister callbacks and prevent memory leaks.

Summary

Public constructors
NavigationEventDispatcher(Function0<Unit> fallbackOnBackPressed)

Creates a root NavigationEventDispatcher.

Creates a child NavigationEventDispatcher linked to a parent.

Public methods
final void

Adds a new NavigationEventCallback to receive navigation events.
final void

Adds an input, registering it with the shared processor and binding it to this dispatcher's lifecycle.
final void

Removes this dispatcher and its entire chain of descendants from the hierarchy.
final @NonNull StateFlow<@NonNull NavigationEventState<@NonNull NavigationEventInfo>>

The StateFlow from the highest-priority, enabled navigation callback.
final @NonNull StateFlow<@NonNull NavigationEventState<@NonNull T>>
<T extends NavigationEventInfo> getState(
    @NonNull CoroutineScope scope,
    @NonNull T initialInfo
)

Creates a StateFlow that only emits states for a specific NavigationEventInfo type.
final boolean

Returns true if there is at least one NavigationEventCallback.isEnabled callback registered with this dispatcher.
final boolean

Controls whether this dispatcher is active and will process navigation events.
final void

Removes and detaches an input from this dispatcher and the shared processor.
final void
setEnabled(boolean isEnabled)

Controls whether this dispatcher is active and will process navigation events.

Public constructors

Added in 1.0.0-alpha07
public NavigationEventDispatcher(Function0<Unit> fallbackOnBackPressed)

Creates a root NavigationEventDispatcher.

This constructor is used to establish the top-level dispatcher for a new navigation hierarchy, typically within a scope like an Activity or a top-level composable. It creates its own internal NavigationEventProcessor.

Parameters
Function0<Unit> fallbackOnBackPressed

An optional lambda to be invoked if a navigation event completes and no registered NavigationEventCallback handles it. This provides a default "back" action for the entire hierarchy.
Added in 1.0.0-alpha07
public NavigationEventDispatcher(
    @NonNull NavigationEventDispatcher parentDispatcher
)

Creates a child NavigationEventDispatcher linked to a parent.

This constructor is used to create nested dispatchers within an existing hierarchy. The new dispatcher will share the same underlying NavigationEventProcessor as its parent, allowing it to participate in the same event stream.

Parameters
@NonNull NavigationEventDispatcher parentDispatcher

The parent NavigationEventDispatcher to which this new dispatcher will be attached.

Public methods

addCallback

Added in 1.0.0-alpha07
@MainThread
public final void addCallback(
    @NonNull NavigationEventCallback<@NonNull ?> callback,
    @NonNull NavigationEventPriority priority
)

Adds a new NavigationEventCallback to receive navigation events.

Callbacks are invoked based on priority, and then by recency. All Overlay callbacks are called before any Default callbacks. Within each priority group, callbacks are invoked in a Last-In, First-Out (LIFO) order—the most recently added callback is called first.

All callbacks are invoked on the main thread. To stop receiving events, a callback must be removed via NavigationEventCallback.remove.

Parameters
@NonNull NavigationEventCallback<@NonNull ?> callback

The callback instance to be added.
@NonNull NavigationEventPriority priority

The priority of the callback, determining its invocation order relative to others. See NavigationEventPriority.
Throws
kotlin.IllegalArgumentException

if the given callback is already registered with a different dispatcher.
kotlin.IllegalStateException

if the dispatcher has already been disposed.

addInput

Added in 1.0.0-alpha07
@MainThread
public final void addInput(@NonNull NavigationEventInput input)

Adds an input, registering it with the shared processor and binding it to this dispatcher's lifecycle.

The input is registered globally with the sharedProcessor to receive system-wide state updates (e.g., whether any callbacks are enabled). It is also tracked locally by this dispatcher for lifecycle management.

The input's NavigationEventInput.onAdded method is invoked immediately upon addition. It will be automatically detached when this dispatcher dispose is called.

Parameters
@NonNull NavigationEventInput input

The input to add.
Throws
kotlin.IllegalStateException

if the dispatcher has already been disposed or if input is already added to a dispatcher.
See also
removeInput
onRemoved

dispose

Added in 1.0.0-alpha07
@MainThread
public final void dispose()

Removes this dispatcher and its entire chain of descendants from the hierarchy.

This is the primary cleanup method and should be called when the component owning this dispatcher is destroyed (e.g., in DisposableEffect in Compose).

This is a terminal operation; once a dispatcher is disposed, it cannot be reused.

Calling this method triggers a comprehensive, iterative cleanup:

  1. It iteratively processes and disposes of all child dispatchers and their descendants, ensuring a complete top-down cleanup of the entire sub-hierarchy without recursion.

  2. For each dispatcher, it first detaches all registered NavigationEventInput instances by calling NavigationEventInput.onRemoved. This severs their lifecycle link to the dispatcher and allows them to release any tied resources.

  3. It then removes all NavigationEventCallback instances registered with that dispatcher from the shared processor, preventing memory leaks.

  4. Finally, it removes the dispatcher from its parent's list of children, fully dismantling the hierarchy.

Throws
kotlin.IllegalStateException

if the dispatcher has already been disposed.

getState

Added in 1.0.0-alpha07
public final @NonNull StateFlow<@NonNull NavigationEventState<@NonNull NavigationEventInfo>> getState()

The StateFlow from the highest-priority, enabled navigation callback.

This represents the navigation state of the currently active component.

getState

public final @NonNull StateFlow<@NonNull NavigationEventState<@NonNull T>> <T extends NavigationEventInfo> getState(
    @NonNull CoroutineScope scope,
    @NonNull T initialInfo
)

Creates a StateFlow that only emits states for a specific NavigationEventInfo type.

Parameters
<T extends NavigationEventInfo>

The NavigationEventInfo type to filter for.
@NonNull CoroutineScope scope

The CoroutineScope in which the new StateFlow is created.
@NonNull T initialInfo

The initial NavigationEventInfo of type T to be used when the StateFlow starts.
Returns
@NonNull StateFlow<@NonNull NavigationEventState<@NonNull T>>

A StateFlow that emits values only when the state's destination is of type T.

hasEnabledCallbacks

Added in 1.0.0-alpha07
public final boolean hasEnabledCallbacks()

Returns true if there is at least one NavigationEventCallback.isEnabled callback registered with this dispatcher.

Returns
boolean

True if there is at least one enabled callback.

isEnabled

Added in 1.0.0-alpha07
public final boolean isEnabled()

Controls whether this dispatcher is active and will process navigation events.

A dispatcher's effective enabled state is hierarchical. It depends on both its own local isEnabled state and the state of its parent.

Getting the value:

  • This will return false if the parentDispatcher exists and its isEnabled state is false, regardless of this dispatcher's own setting. This provides a simple way to disable an entire branch of a navigation hierarchy by disabling its root.

  • If there is no parent or the parent is enabled, it will return the local value of this property (true by default).

Setting the value:

  • This only updates the local enabled state for this specific dispatcher. The getter will always re-evaluate the effective state based on the parent.

For this dispatcher to be truly active, its local isEnabled property must be true, and the isEnabled properties of all its ancestors must also be true.

removeInput

Added in 1.0.0-alpha07
@MainThread
public final void removeInput(@NonNull NavigationEventInput input)

Removes and detaches an input from this dispatcher and the shared processor.

This severs the input's lifecycle link to the dispatcher. Its NavigationEventInput.onRemoved method is invoked, and it will no longer receive lifecycle calls or global state updates from the processor.

Parameters
@NonNull NavigationEventInput input

The input to remove.
Throws
kotlin.IllegalStateException

if the dispatcher has already been disposed.
See also
addInput
onAdded

setEnabled

Added in 1.0.0-alpha07
public final void setEnabled(boolean isEnabled)

Controls whether this dispatcher is active and will process navigation events.

A dispatcher's effective enabled state is hierarchical. It depends on both its own local isEnabled state and the state of its parent.

Getting the value:

  • This will return false if the parentDispatcher exists and its isEnabled state is false, regardless of this dispatcher's own setting. This provides a simple way to disable an entire branch of a navigation hierarchy by disabling its root.

  • If there is no parent or the parent is enabled, it will return the local value of this property (true by default).

Setting the value:

  • This only updates the local enabled state for this specific dispatcher. The getter will always re-evaluate the effective state based on the parent.

For this dispatcher to be truly active, its local isEnabled property must be true, and the isEnabled properties of all its ancestors must also be true.