# NavigationTemplate

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/model/NavigationTemplate.java+class:androidx.car.app.navigation.model.NavigationTemplate) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

*** ** * ** ***


```
@CarProtocol
public final class NavigationTemplate implements Template
```

<br />

*** ** * ** ***

A template for showing navigation information.

This template has two independent sections which can be updated:

- Navigation information such as routing instructions or navigation-related messages.
- Travel estimates to the destination.

To update the template as the user navigates, call `https://developer.android.com/reference/androidx/car/app/Screen#invalidate()` to provide the host with a new template with the updated information.

The template itself does not expose a drawing surface. In order to draw on the canvas, use `https://developer.android.com/reference/androidx/car/app/AppManager#setSurfaceCallback(androidx.car.app.SurfaceCallback)`.

See `https://developer.android.com/reference/androidx/car/app/notification/CarAppExtender` for how to show alerts with notifications. Frequent alert notifications distract the driver and are discouraged.

#### Pan and Zoom

This template allows an app to provide pan and zoom functionality. To support pan and zoom, respond to the user input in `https://developer.android.com/reference/androidx/car/app/SurfaceCallback` methods, such as:

- `https://developer.android.com/reference/androidx/car/app/SurfaceCallback#onScroll(float,float)`
- `https://developer.android.com/reference/androidx/car/app/SurfaceCallback#onFling(float,float)`
- `https://developer.android.com/reference/androidx/car/app/SurfaceCallback#onScale(float,float,float)`

In order to receive the callbacks, add an `https://developer.android.com/reference/androidx/car/app/model/Action#PAN()` button in a map `https://developer.android.com/reference/androidx/car/app/model/ActionStrip` via the `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate.Builder#setMapActionStrip(androidx.car.app.model.ActionStrip)` method:

```
...
Action panAction = new Action.Builder(Action.PAN).setIcon(myPanIcon).build();
ActionStrip mapActionStrip = new ActionStrip.Builder().addAction(panAction).build();
NavigationTemplate.Builder builder = new NavigationTemplate.Builder();
builder.setMapActionStrip(mapActionStrip);
...
```
When the user presses the `https://developer.android.com/reference/androidx/car/app/model/Action#PAN()` button, the host enters the pan mode. In this mode, the host translates the user input from non-touch input devices, such as rotary controllers and touchpads, and calls the appropriate `https://developer.android.com/reference/androidx/car/app/SurfaceCallback` methods. Respond to the user action to enter or exit the pan mode via `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate.Builder#setPanModeListener(androidx.car.app.navigation.model.PanModeListener)`.

If the app does not include this button in the map `https://developer.android.com/reference/androidx/car/app/model/ActionStrip`, the app will not receive the user input for panning gestures from `https://developer.android.com/reference/androidx/car/app/SurfaceCallback` methods, and the host will exit any previously activated pan mode.

The host may hide the pan button in some head units in which the user does not need it. Also, the host may hide other UI components in the template while the user is in the pan mode.

Note that not all head units support touch gestures, and not all touch screens support multi-touch gestures. Therefore, some `https://developer.android.com/reference/androidx/car/app/SurfaceCallback` methods may not be called in some cars. In order to support different head units, use the buttons in the map action strip to provide necessary functionality, such as the zoom-in and zoom-out buttons.

#### Template Restrictions

In regard to template refreshes, as described in `https://developer.android.com/reference/androidx/car/app/Screen#onGetTemplate()`, this template supports any content changes as refreshes. This allows apps to interactively update the turn-by-turn instructions without the templates being counted against the template quota.

Further, this template is considered a view that the user will stay and consume contents from, and the host will reset the template quota once an app reaches this template.

In order to use this template your car app **MUST** declare that it uses the `
androidx.car.app.NAVIGATION_TEMPLATES` permission in the manifest.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate.Builder` A builder of `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate`. |
| `public interface https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate.NavigationInfo` Represents navigation information such as routing instructions or navigation-related messages. |

| ### Public methods |
|---|---|
| `boolean` | `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#equals(java.lang.Object)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/Object.html other)` |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/model/ActionStrip` | `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getActionStrip()()` Returns the `https://developer.android.com/reference/androidx/car/app/model/ActionStrip` for this template or `null` if not set. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/model/CarColor` | `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getBackgroundColor()()` Returns the background color used for the navigation information or `null` if set to the default value. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/navigation/model/TravelEstimate` | `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getDestinationTravelEstimate()()` Returns the `https://developer.android.com/reference/androidx/car/app/navigation/model/TravelEstimate` to the final destination or `null` if there is no travel estimate information. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/model/ActionStrip` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 2) https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getMapActionStrip()()` Returns the map `https://developer.android.com/reference/androidx/car/app/model/ActionStrip` for this template or `null` if not set. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate.NavigationInfo` | `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getNavigationInfo()()` Returns the navigation information displayed on the template or `null` if there is no navigation information on top of the map. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/navigation/model/PanModeDelegate` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 2) https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getPanModeDelegate()()` Returns the `https://developer.android.com/reference/androidx/car/app/navigation/model/PanModeDelegate` that should be called when the user interacts with pan mode on this template, or `null` if a `https://developer.android.com/reference/androidx/car/app/navigation/model/PanModeListener` was not set. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/model/Toggle` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 2) [getPanModeToggle](https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getPanModeToggle())()` **This method is deprecated.** use `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getPanModeDelegate()` <br /> |
| `int` | `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#hashCode()()` |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#toString()()` |

## Public methods

### equals

```
public boolean equals(@Nullable Object other)
```

### getActionStrip

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

```
public @Nullable ActionStrip getActionStrip()
```

Returns the `https://developer.android.com/reference/androidx/car/app/model/ActionStrip` for this template or `null` if not set.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate.Builder#setActionStrip(androidx.car.app.model.ActionStrip)` |   |

### getBackgroundColor

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

```
public @Nullable CarColor getBackgroundColor()
```

Returns the background color used for the navigation information or `null` if set to the default value.

### getDestinationTravelEstimate

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

```
public @Nullable TravelEstimate getDestinationTravelEstimate()
```

Returns the `https://developer.android.com/reference/androidx/car/app/navigation/model/TravelEstimate` to the final destination or `null` if there is no travel estimate information.

### getMapActionStrip

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

```
@RequiresCarApi(value = 2)
public @Nullable ActionStrip getMapActionStrip()
```

Returns the map `https://developer.android.com/reference/androidx/car/app/model/ActionStrip` for this template or `null` if not set.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate.Builder#setMapActionStrip(androidx.car.app.model.ActionStrip)` |   |

### getNavigationInfo

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

```
public @Nullable NavigationTemplate.NavigationInfo getNavigationInfo()
```

Returns the navigation information displayed on the template or `null` if there is no navigation information on top of the map.

### getPanModeDelegate

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

```
@RequiresCarApi(value = 2)
public @Nullable PanModeDelegate getPanModeDelegate()
```

Returns the `https://developer.android.com/reference/androidx/car/app/navigation/model/PanModeDelegate` that should be called when the user interacts with pan mode on this template, or `null` if a `https://developer.android.com/reference/androidx/car/app/navigation/model/PanModeListener` was not set.

### getPanModeToggle

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

```
@RequiresCarApi(value = 2)
public @Nullable Toggle [getPanModeToggle](https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getPanModeToggle())()
```

> [!CAUTION]
> **This method is deprecated.**   
>
> use `https://developer.android.com/reference/androidx/car/app/navigation/model/NavigationTemplate#getPanModeDelegate()`

Returns whether this template is in the pan mode.

### hashCode

```
public int hashCode()
```

### toString

```
public @NonNull String toString()
```