# NavigationManager

Artifact: [androidx.car.app:app](https://developer.android.com/jetpack/androidx/releases/car-app) [View Source](https://cs.android.com/search?q=file:androidx/car/app/navigation/NavigationManager.java+class:androidx.car.app.navigation.NavigationManager) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

*** ** * ** ***


```
public class NavigationManager implements Manager
```

<br />

Known direct subclasses [TestNavigationManager](https://developer.android.com/reference/androidx/car/app/testing/navigation/TestNavigationManager)

|---|---|
| `https://developer.android.com/reference/androidx/car/app/testing/navigation/TestNavigationManager` | The `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager` that is used for testing. |

*** ** * ** ***

Manager for communicating navigation related events with the host.

Navigation apps must use this interface to coordinate with the car system for navigation specific resources such as vehicle cluster and heads-up displays.

When a navigation app receives a user action to start navigating, it should call `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#navigationStarted()` to indicate it is currently navigating. When the app receives a user action to end navigation or when the destination is reached, `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#navigationEnded()` should be called.

Navigation apps must also register a `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback` to handle callbacks to `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback#onStopNavigation()` issued by the host.

## Summary

| ### Public methods |
|---|---|
| `boolean` | `@https://developer.android.com/reference/androidx/car/app/annotations/ExperimentalCarApi @https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 9) https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#canSetVoiceAssistantCapabilities()()` Returns whether the host supports setting voice assistant capabilities. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#clearNavigationManagerCallback()()` Clears the callback for receiving navigation manager events. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#navigationEnded()()` Notifies the host that the app has ended active navigation. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#navigationStarted()()` Notifies the host that the app has started active navigation. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#setNavigationManagerCallback(androidx.car.app.navigation.NavigationManagerCallback)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback callback )` Sets a callback to start receiving navigation manager events. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#setNavigationManagerCallback(java.util.concurrent.Executor,androidx.car.app.navigation.NavigationManagerCallback)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback callback )` Sets a callback to start receiving navigation manager events. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/MainThread @https://developer.android.com/reference/androidx/car/app/annotations/ExperimentalCarApi @https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 9) https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#setVoiceAssistantCapabilities(androidx.car.app.navigation.model.NavigationVoiceAssistantCapabilities)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationVoiceAssistantCapabilities capabilities )` Sends the voice assistant capabilities and consent state of the navigation app to the host. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/MainThread https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#updateTrip(androidx.car.app.navigation.model.Trip)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/navigation/model/Trip trip)` Sends the destinations, steps, and trip estimates to the host. |

## Public methods

### canSetVoiceAssistantCapabilities

Added in [1.9.0-alpha03](https://developer.android.com/jetpack/androidx/releases/car-app#1.9.0-alpha03)

```
@ExperimentalCarApi
@RequiresCarApi(value = 9)
public boolean canSetVoiceAssistantCapabilities()
```

Returns whether the host supports setting voice assistant capabilities.

Third-party navigation apps should call this method before attempting to build or send a `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationVoiceAssistantCapabilities` object, as it is only supported on specific host platforms (e.g., Android Automotive OS).

| Returns |
|---|---|
| `boolean` | `true` if the current host supports voice assistant capabilities, `false` otherwise. |

### clearNavigationManagerCallback

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

```
@MainThread
public void clearNavigationManagerCallback()
```

Clears the callback for receiving navigation manager events.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if navigation is started (see `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#navigationStarted()` for more info), or if the current thread is not the main thread |

### navigationEnded

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

```
@MainThread
public void navigationEnded()
```

Notifies the host that the app has ended active navigation.

Only one app may be actively navigating in the car at any time and ownership is managed by the host. The app must call this method to inform the system that it has ended navigation, for example, in response to the user cancelling navigation or upon reaching the destination.

This method is idempotent.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if the current thread is not the main thread |

### navigationStarted

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

```
@MainThread
public void navigationStarted()
```

Notifies the host that the app has started active navigation.

Only one app may be actively navigating in the car at any time and ownership is managed by the host. The app must call this method to inform the system that it has started navigation in response to user action.

This function can only called if `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#setNavigationManagerCallback(androidx.car.app.navigation.NavigationManagerCallback)` has been called with a non-`null` value. The callback is required so that a signal to stop navigation from the host can be handled using `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback#onStopNavigation()`.

This method is idempotent.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if no navigation manager callback has been set, or if the current thread is not the main thread |

### setNavigationManagerCallback

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

```
@MainThread
public void setNavigationManagerCallback(
    @NonNull NavigationManagerCallback callback
)
```

Sets a callback to start receiving navigation manager events. Note that the callback events will be executed on the main thread using `https://developer.android.com/reference/android/os/Looper.html#getMainLooper()`. To specify the execution thread, use `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#setNavigationManagerCallback(java.util.concurrent.Executor,androidx.car.app.navigation.NavigationManagerCallback)`.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback callback` | the `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback` to use |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if the current thread is not the main thread |

### setNavigationManagerCallback

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

```
@MainThread
public void setNavigationManagerCallback(
    @NonNull Executor executor,
    @NonNull NavigationManagerCallback callback
)
```

Sets a callback to start receiving navigation manager events.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor` | the executor which will be used for invoking the callback |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback callback` | the `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback` to use |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if the current thread is not the main thread |

### setVoiceAssistantCapabilities

Added in [1.9.0-alpha03](https://developer.android.com/jetpack/androidx/releases/car-app#1.9.0-alpha03)

```
@MainThread
@ExperimentalCarApi
@RequiresCarApi(value = 9)
public void setVoiceAssistantCapabilities(
    @NonNull NavigationVoiceAssistantCapabilities capabilities
)
```

Sends the voice assistant capabilities and consent state of the navigation app to the host.

This allows the app to dynamically toggle whether the voice assistant can access the active navigation state, and declares the actions and disruptions the app supports.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationVoiceAssistantCapabilities capabilities` | The capabilities and consent state to send to the host. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if the current thread is not the main thread, or if the host does not support voice assistant capabilities |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if the provided capabilities cannot be serialized |
| `https://developer.android.com/reference/androidx/car/app/HostException` | if the call is invoked by an app that is not declared as a navigation app in the manifest |

### updateTrip

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

```
@MainThread
public void updateTrip(@NonNull Trip trip)
```

Sends the destinations, steps, and trip estimates to the host.

The data **may** be rendered at different places in the car such as the instrument cluster screen or the heads-up display.

This method should only be invoked once the navigation app has called `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#navigationStarted()`, or else the updates will be dropped by the host. Once the app has called `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#navigationEnded()` or received `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManagerCallback#onStopNavigation()` it should stop sending updates.

As the location changes, and in accordance with speed and rounded distance changes, the `https://developer.android.com/reference/androidx/car/app/navigation/model/TravelEstimate`s in the provided `https://developer.android.com/reference/androidx/car/app/navigation/model/Trip` should be rebuilt and this method called again. For example, when the next step is greater than 10 kilometers away and the display unit is kilometers, updates should occur roughly every kilometer.

Data provided to the cluster display depends on the vehicle capabilities. In some instances the information may not be shown at all. On some vehicles `https://developer.android.com/reference/androidx/car/app/navigation/model/Maneuver`s of unknown type may be skipped while on other displays the associated icon may be shown.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/navigation/model/Trip trip` | destination, steps, and trip estimates to be sent to the host |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/HostException` | if the call is invoked by an app that is not declared as a navigation app in the manifest |
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if the call occurs when navigation is not started (see `https://developer.android.com/reference/androidx/car/app/navigation/NavigationManager#navigationStarted()` for more info), or if the current thread is not the main thread |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if any of the destinations, steps, or trip position is not well formed |