Step.Builder

class Step.Builder


A builder of Step.

Summary

Public constructors

Constructs a new builder of Step.

Constructs a new builder of Step with a cue, with support for multiple length variants.

Constructs a new builder of Step with a cue.

Public functions

Step.Builder
addLane(lane: Lane)

Adds the information of a single road lane at the point where the driver should execute this step.

Step

Constructs the Step defined by this builder.

Step.Builder

Sets a text description of this maneuver.

Step.Builder
setLanesImage(lanesImage: CarIcon)

Sets an image representing all the lanes.

Step.Builder
setManeuver(maneuver: Maneuver)

Sets the maneuver to be performed on this step.

Step.Builder

Sets a text description of the road for the step.

Public constructors

Builder

Added in 1.1.0
Builder()

Constructs a new builder of Step.

Builder

Added in 1.0.0
Builder(cue: CarText)

Constructs a new builder of Step with a cue, with support for multiple length variants.

See setCue for details on span support in the input string.

Throws
java.lang.NullPointerException

if cue is null

java.lang.IllegalArgumentException

if cue contains unsupported spans

See also
Builder

Builder

Added in 1.0.0
Builder(cue: CharSequence)

Constructs a new builder of Step with a cue.

A cue can be used as a fallback when Maneuver is not set or is unavailable.

Some cluster displays do not support UTF-8 encoded characters, in which case unsupported characters will not be displayed properly.

See setCue for details on span support in the input string.

Throws
java.lang.NullPointerException

if cue is null

java.lang.IllegalArgumentException

if cue contains unsupported spans

See also
setCue

Public functions

addLane

Added in 1.0.0
fun addLane(lane: Lane): Step.Builder

Adds the information of a single road lane at the point where the driver should execute this step.

Lane information is primarily used when the step is passed to the vehicle cluster or heads up displays. Some vehicles may not use the information at all. The navigation template primarily uses the lanes image provided in setLanesImage.

Lanes are displayed from left to right.

Throws
java.lang.NullPointerException

if lane is null

build

Added in 1.0.0
fun build(): Step

Constructs the Step defined by this builder.

Throws
java.lang.IllegalStateException

if lanesImage was set but no lanes were added

setCue

Added in 1.0.0
fun setCue(cue: CharSequence): Step.Builder

Sets a text description of this maneuver.

A cue can be used as a fallback when Maneuver is not set or is unavailable.

For example "Turn left", "Make a U-Turn", "Sharp Right", or "Take the exit using the left lane"

The cue string can contain androidx.car.app.model.CarIconSpans, androidx.car.app.model.DistanceSpans, and androidx.car.app.model.DurationSpans.

In the following example, the "520" text is replaced with an icon:

SpannableString string = new SpannableString("Turn right on 520 East");
string.setSpan(textWithImage.setSpan(
    CarIconSpan.create(new CarIcon.Builder(
        IconCompat.createWithResource(getCarContext(), R.drawable.ic_520_highway))),
        14, 17, SPAN_INCLUSIVE_EXCLUSIVE));

The host may choose to display the string without the images, so it is important that the string content is readable without the images. This may be the case, for example, if the string is sent to a cluster display that does not support images, or if the host limits the number of images that may be allowed for one line of text.

Image Sizing Guidance The size these images will be displayed at varies depending on where the Step object is used. Refer to the documentation of those APIs for details.

See CarIcon for more details related to providing icon and image resources that work with different car screen pixel densities.

Throws
java.lang.NullPointerException

if cue is null

java.lang.IllegalArgumentException

if cue contains unsupported spans

See also
CarText

setLanesImage

Added in 1.0.0
fun setLanesImage(lanesImage: CarIcon): Step.Builder

Sets an image representing all the lanes.

This image takes priority over Lanes that may have been added with addLane. If an image is added for the lanes with this method then corresponding lane data using addLane must also have been added in case it is shown on a display with limited resources such as the car cluster or heads-up display (HUD).

This image should ideally have a transparent background.

Image Sizing Guidance To minimize scaling artifacts across a wide range of car screens, apps should provide images targeting a 500 x 74 dp bounding box. If the image exceeds this maximum size in either one of the dimensions, it will be scaled down to be centered inside the bounding box while preserving its aspect ratio.

See CarIcon for more details related to providing icon and image resources that work with different car screen pixel densities.

Throws
java.lang.NullPointerException

if lanesImage is null

setManeuver

Added in 1.0.0
fun setManeuver(maneuver: Maneuver): Step.Builder

Sets the maneuver to be performed on this step.

Throws
java.lang.NullPointerException

if maneuver is null

setRoad

Added in 1.0.0
fun setRoad(road: CharSequence): Step.Builder

Sets a text description of the road for the step.

This value is primarily used for vehicle cluster and heads-up displays and may not appear in the navigation template.

For example, a Step for a left turn might provide "State Street" for the road.

Only DistanceSpans and DurationSpans are supported in the input string.

Throws
java.lang.NullPointerException

if road is null

java.lang.IllegalArgumentException

if road contains unsupported spans

See also
CarText