NavigationTemplate

public final class NavigationTemplate
extends Object implements Template

java.lang.Object
   ↳ androidx.car.app.navigation.model.NavigationTemplate

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 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 AppManager.setSurfaceCallback(SurfaceCallback).

See 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 SurfaceCallback methods, such as: In order to receive the callbacks, add an Action.PAN button in a map ActionStrip via the NavigationTemplate.Builder.setMapActionStrip(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 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 SurfaceCallback methods. Respond to the user action to enter or exit the pan mode via NavigationTemplate.Builder.setPanModeListener(PanModeListener).

If the app does not include this button in the map ActionStrip, the app will not receive the user input for panning gestures from 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 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 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 classes

class NavigationTemplate.Builder

A builder of NavigationTemplate. 

interface NavigationTemplate.NavigationInfo

Represents navigation information such as routing instructions or navigation-related messages. 

Public methods

boolean equals(Object other)
ActionStrip getActionStrip()

Returns the ActionStrip for this template or null if not set.

CarColor getBackgroundColor()

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

TravelEstimate getDestinationTravelEstimate()

Returns the TravelEstimate to the final destination or null if there is no travel estimate information.

ActionStrip getMapActionStrip()

Returns the map ActionStrip for this template or null if not set.

NavigationTemplate.NavigationInfo getNavigationInfo()

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

PanModeDelegate getPanModeDelegate()

Returns the PanModeDelegate that should be called when the user interacts with pan mode on this template, or null if a PanModeListener was not set.

Toggle getPanModeToggle()

This method is deprecated. use getPanModeDelegate()

int hashCode()
String toString()

Inherited methods

Public methods

equals

public boolean equals (Object other)

Parameters
other Object

Returns
boolean

getActionStrip

public ActionStrip getActionStrip ()

Returns the ActionStrip for this template or null if not set.

Returns
ActionStrip

getBackgroundColor

public CarColor getBackgroundColor ()

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

Returns
CarColor

getDestinationTravelEstimate

public TravelEstimate getDestinationTravelEstimate ()

Returns the TravelEstimate to the final destination or null if there is no travel estimate information.

Returns
TravelEstimate

getMapActionStrip

public ActionStrip getMapActionStrip ()

Returns the map ActionStrip for this template or null if not set.

Returns
ActionStrip

getNavigationInfo

public NavigationTemplate.NavigationInfo getNavigationInfo ()

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

Returns
NavigationTemplate.NavigationInfo

getPanModeDelegate

public PanModeDelegate getPanModeDelegate ()

Returns the PanModeDelegate that should be called when the user interacts with pan mode on this template, or null if a PanModeListener was not set.

Returns
PanModeDelegate

getPanModeToggle

public Toggle getPanModeToggle ()

This method is deprecated.
use getPanModeDelegate()

Returns whether this template is in the pan mode.

Returns
Toggle

hashCode

public int hashCode ()

Returns
int

toString

public String toString ()

Returns
String