androidx.navigationevent.compose

@Composable
fun NavigationBackHandler(
    state: NavigationEventState<NavigationEventInfo>,
    isBackEnabled: Boolean = true,
    onBackCancelled: () -> Unit = {},
    onBackCompleted: () -> Unit
): Unit

A composable that handles only back navigation gestures, driven by a manually hoisted NavigationEventState.

This is a convenience wrapper around the core NavigationEventHandler overload for cases where forward navigation is not relevant. Use this overload when hoisting state (e.g., for custom animations).

Refer to the primary NavigationEventHandler KDoc for details on precedence, unconditional usage, and timing considerations.

@Composable
fun NavigationEventDispatcherOwner(
    enabled: Boolean = true,
    parent: NavigationEventDispatcherOwner? = checkNotNull(LocalNavigationEventDispatcherOwner.current) {
            "No NavigationEventDispatcherOwner provided in LocalNavigationEventDispatcherOwner. " +
                "If you intended to create a root dispatcher, explicitly pass null as the parent."
        },
    content: @Composable () -> Unit
): Unit

Creates a new navigation scope by providing a NavigationEventDispatcher to descendant composables.

This composable creates a dispatcher that links to any parent dispatcher found in the composition, forming a parent-child relationship. If no parent exists, it automatically becomes a new root dispatcher, this is the top-most parent in a hierarchy. This is useful for isolating navigation handling within specific UI sections, such as a self-contained feature screen or tab.

The dispatcher's lifecycle is automatically managed. It is created only once and automatically disposed of when the composable leaves the composition, preventing memory leaks.

When used to create a root dispatcher, you must use a NavigationEventInput to send it events. Otherwise, the dispatcher will be detached and will not receive events.

Null parent: If parent is EXPLICITLY null, this creates a root dispatcher that runs independently. By default, it requires a parent from the LocalNavigationEventDispatcherOwner and will throw an IllegalStateException if one is not present.

@Composable
fun NavigationEventHandler(
    state: NavigationEventState<NavigationEventInfo>,
    isForwardEnabled: Boolean = true,
    onForwardCancelled: () -> Unit = {},
    onForwardCompleted: () -> Unit = {},
    isBackEnabled: Boolean = true,
    onBackCancelled: () -> Unit = {},
    onBackCompleted: () -> Unit = {}
): Unit

A composable that handles navigation events using simple lambda handlers, driven by a manually hoisted NavigationEventState.

This is the core implementation of the navigation event handler. This overload must be used when you need to hoist the NavigationEventState (by calling rememberNavigationEventState at a higher level). Hoisting is necessary when other composables need to react to the gesture's NavigationEventTransitionState (held within the state object), for example, to drive custom animations.

Precedence

When multiple NavigationEventHandler are present in the composition, the one that is composed last among all enabled handlers will be invoked.

Usage

It is important to call this composable unconditionally. Use isBackEnabled and isForwardEnabled to control whether the handler is active. This is preferable to conditionally calling NavigationEventHandler (e.g., inside an if block), as conditional calls can change the order of composition, leading to unpredictable behavior where different handlers are invoked after recomposition.

Timing Consideration

There are cases where a predictive back or forward gesture may be dispatched within a rendering frame before the corresponding enabled flag is updated, which can cause unexpected behavior (see b/375343407, b/384186542). For example, if isBackEnabled is set to false, a back gesture initiated in the same frame may still trigger this handler because the system sees the stale true value.

@Composable
fun NavigationForwardHandler(
    state: NavigationEventState<NavigationEventInfo>,
    isForwardEnabled: Boolean = true,
    onForwardCancelled: () -> Unit = {},
    onForwardCompleted: () -> Unit
): Unit

A composable that handles only forward navigation gestures, driven by a manually hoisted NavigationEventState.

This is a convenience wrapper around the core NavigationEventHandler overload for cases where back navigation is not relevant. Use this overload when hoisting state.

Refer to the primary NavigationEventHandler KDoc for details on precedence, unconditional usage, and timing considerations.

@Composable
fun <T : NavigationEventInfo> rememberNavigationEventState(
    currentInfo: T,
    backInfo: List<T> = emptyList(),
    forwardInfo: List<T> = emptyList()
): NavigationEventState<T>

Remembers and returns a NavigationEventState instance.

This composable creates and remembers a NavigationEventState object, which holds a NavigationEventHandler internally. This is the state object that can be passed to NavigationEventHandler (the composable) to "hoist" the state.

The state's handler info (currentInfo, backInfo, forwardInfo) is kept in sync with the provided parameters via a SideEffect.