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
CarAppExtender for how to show
alerts with notifications. Frequent alert notifications distract the driver and are discouraged.
Pan and ZoomThis template allows an app to provide pan and zoom functionality. To support pan and zoom, respond to the user input in
SurfaceCallbackmethods, such as:
SurfaceCallback.onScale(float, float, float)
Action.PANbutton in a map
When the user presses the
... 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); ...
Action.PANbutton, 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
SurfaceCallbackmethods. Respond to the user action to enter or exit the pan mode via
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 RestrictionsIn 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.
A builder of
Represents navigation information such as routing instructions or navigation-related messages.