# NavigationEventHandler

Artifact: [androidx.navigationevent:navigationevent](https://developer.android.com/jetpack/androidx/releases/navigationevent) [View Source](https://cs.android.com/search?q=file:androidx/navigationevent/NavigationEventHandler.kt+class:androidx.navigationevent.NavigationEventHandler) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

*** ** * ** ***


```
public abstract class NavigationEventHandler<T extends NavigationEventInfo>
```

<br />

Known direct subclasses [TestNavigationEventHandler](https://developer.android.com/reference/androidx/navigationevent/testing/TestNavigationEventHandler)

|---|---|
| `https://developer.android.com/reference/androidx/navigationevent/testing/TestNavigationEventHandler` | A test implementation of `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler` that records received events and invocation counts. |

*** ** * ** ***

Base class for handling navigation gestures dispatched by a `https://developer.android.com/reference/androidx/navigationevent/NavigationEventDispatcher`.

A `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler` defines how an active component responds to system navigation gestures (such as predictive back) and exposes the directional context needed to represent the app's current navigation affordances:

- `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#backInfo()`: Contextual information describing what is available when navigating back.

- `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#currentInfo()`: The single active destination represented by this handler.

- `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#forwardInfo()`: Contextual information describing what is available when navigating forward.

Subclasses can override lifecycle methods (e.g., `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onBackStarted(androidx.navigationevent.NavigationEvent)`, `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onBackProgressed(androidx.navigationevent.NavigationEvent)`, `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onBackCompleted()`, `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onBackCancelled()`, and their forward equivalents) to respond to gesture progression and terminal outcomes.

A handler must be registered with a `https://developer.android.com/reference/androidx/navigationevent/NavigationEventDispatcher` to receive events. It will only be invoked while both the dispatcher and this handler are enabled.

| Parameters |
|---|---|
| `<T extends https://developer.android.com/reference/androidx/navigationevent/NavigationEventInfo>` | The type of `https://developer.android.com/reference/androidx/navigationevent/NavigationEventInfo` associated with this handler. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/navigationevent/NavigationEventDispatcher` |   |
| `https://developer.android.com/reference/androidx/navigationevent/NavigationEventInput` |   |

## Summary

| ### Public constructors |
|---|
| `<T extends https://developer.android.com/reference/androidx/navigationevent/NavigationEventInfo> https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#NavigationEventHandler(androidx.navigationevent.NavigationEventInfo,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull T initialInfo, boolean isBackEnabled )` Creates a handler that is only enabled for back navigation gestures. |
| `<T extends https://developer.android.com/reference/androidx/navigationevent/NavigationEventInfo> https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#NavigationEventHandler(androidx.navigationevent.NavigationEventInfo,kotlin.Boolean,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull T initialInfo, boolean isBackEnabled, boolean isForwardEnabled )` |

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull T>` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#getBackInfo()()` Contextual information describing the application's *back* state for this handler. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull T` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#getCurrentInfo()()` The contextual information representing the active destination for this handler. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull T>` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#getForwardInfo()()` Contextual information describing the application's *forward* state for this handler. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigationevent/NavigationEventTransitionState` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#getTransitionState()()` The current transition state of this specific handler (e.g., `https://developer.android.com/reference/androidx/navigationevent/NavigationEventTransitionState.Idle` or `https://developer.android.com/reference/androidx/navigationevent/NavigationEventTransitionState.InProgress`). |
| `final boolean` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#isBackEnabled()()` Controls whether this handler is active and should be considered for back event dispatching. |
| `final boolean` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#isForwardEnabled()()` Controls whether this handler is active and should be considered for forward event dispatching. |
| `final void` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#remove()()` Removes this handler from the `https://developer.android.com/reference/androidx/navigationevent/NavigationEventDispatcher` it is registered with. |
| `final void` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#setBackEnabled(kotlin.Boolean)(boolean value)` Controls whether this handler is active and should be considered for back event dispatching. |
| `final void` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#setForwardEnabled(kotlin.Boolean)(boolean value)` Controls whether this handler is active and should be considered for forward event dispatching. |
| `final void` | `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#setInfo(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)( @https://developer.android.com/reference/androidx/annotation/NonNull T currentInfo, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull T> backInfo, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull T> forwardInfo )` Sets the directional navigation context for this handler. |

| ### Protected methods |
|---|---|
| `void` | `@https://developer.android.com/reference/androidx/annotation/EmptySuper https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onBackCancelled()()` Override this to handle the cancellation of a back navigation event. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/EmptySuper https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onBackCompleted()()` Override this to handle the completion of a back navigation event. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/EmptySuper https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onBackProgressed(androidx.navigationevent.NavigationEvent)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigationevent/NavigationEvent event)` Override this to handle the progress of an ongoing back navigation event. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/EmptySuper https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onBackStarted(androidx.navigationevent.NavigationEvent)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigationevent/NavigationEvent event)` Override this to handle the beginning of a back navigation event. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/EmptySuper https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onForwardCancelled()()` Override this to handle the cancellation of a forward navigation event. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/EmptySuper https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onForwardCompleted()()` Override this to handle the completion of a forward navigation event. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/EmptySuper https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onForwardProgressed(androidx.navigationevent.NavigationEvent)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigationevent/NavigationEvent event)` Override this to handle the progress of an ongoing forward navigation event. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/EmptySuper https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onForwardStarted(androidx.navigationevent.NavigationEvent)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigationevent/NavigationEvent event)` Override this to handle the beginning of a forward navigation event. |

## Public constructors

### 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.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull T initialInfo` | The initial value for `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#currentInfo()`. |
| `boolean isBackEnabled` | If `true`, this handler will process back navigation gestures. |

### NavigationEventHandler

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

| Parameters |
|---|---|
| `<T extends https://developer.android.com/reference/androidx/navigationevent/NavigationEventInfo>` | The type of `https://developer.android.com/reference/androidx/navigationevent/NavigationEventInfo` associated with this handler. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull T initialInfo` | The initial value for `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#currentInfo()`. |
| `boolean isBackEnabled` | If `true`, this handler will process back navigation gestures. |
| `boolean isForwardEnabled` | If `true`, this handler will process forward navigation gestures. |

## Public methods

### getBackInfo

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
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 `https://developer.android.com/reference/androidx/navigationevent/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.

### getCurrentInfo

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
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.

### getForwardInfo

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
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 `https://developer.android.com/reference/androidx/navigationevent/NavigationEventInfo` values that help render forward affordances in the UI. The list may be empty if no forward navigation is possible in this scope.

### getTransitionState

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
public final @NonNull NavigationEventTransitionState getTransitionState()
```

The current transition state of this specific handler (e.g., `https://developer.android.com/reference/androidx/navigationevent/NavigationEventTransitionState.Idle` or `https://developer.android.com/reference/androidx/navigationevent/NavigationEventTransitionState.InProgress`).

This state is updated by the dispatcher *before* the corresponding `on...` lifecycle methods (e.g., `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#onBackStarted(androidx.navigationevent.NavigationEvent)`) are called.

### isBackEnabled

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
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 `https://developer.android.com/reference/androidx/navigationevent/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`.

### isForwardEnabled

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
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 `https://developer.android.com/reference/androidx/navigationevent/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`.

### remove

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
public final void remove()
```

Removes this handler from the `https://developer.android.com/reference/androidx/navigationevent/NavigationEventDispatcher` it is registered with. If the handler is not registered, this call does nothing.

### setBackEnabled

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
public final void setBackEnabled(boolean value)
```

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 `https://developer.android.com/reference/androidx/navigationevent/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`.

### setForwardEnabled

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
public final void setForwardEnabled(boolean value)
```

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 `https://developer.android.com/reference/androidx/navigationevent/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`.

### setInfo

```
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:

- `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#setInfo(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)`: the active destination.

- `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#setInfo(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)`: contextual information for back navigation (nearest-first).

- `https://developer.android.com/reference/androidx/navigationevent/NavigationEventHandler#setInfo(androidx.navigationevent.NavigationEventInfo,kotlin.collections.List,kotlin.collections.List)`: contextual information for forward navigation (nearest-first).

The lists are app-defined `https://developer.android.com/reference/androidx/navigationevent/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.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull T currentInfo` | The contextual information representing the active destination. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull T> backInfo` | Context describing what is available when navigating back (nearest-first). |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull T> forwardInfo` | Context describing what is available when navigating forward (nearest-first). |

## Protected methods

### onBackCancelled

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@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.

### onBackCompleted

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@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 `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unsupported-operation-exception/index.html`. Any handler that can be completed **must** override this method to handle the navigation.

### onBackProgressed

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@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.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigationevent/NavigationEvent event` | The `https://developer.android.com/reference/androidx/navigationevent/NavigationEvent` containing progress information. |

### onBackStarted

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@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.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigationevent/NavigationEvent event` | The `https://developer.android.com/reference/androidx/navigationevent/NavigationEvent` that triggered this handler. |

### onForwardCancelled

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@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.

### onForwardCompleted

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@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 `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unsupported-operation-exception/index.html`. Any handler that can be completed **must** override this method to handle the navigation.

### onForwardProgressed

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@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.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigationevent/NavigationEvent event` | The `https://developer.android.com/reference/androidx/navigationevent/NavigationEvent` containing progress information. |

### onForwardStarted

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/navigationevent#1.0.0)

```
@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.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/navigationevent/NavigationEvent event` | The `https://developer.android.com/reference/androidx/navigationevent/NavigationEvent` that triggered this handler. |