MessageTemplate.Builder


public final class MessageTemplate.Builder


A builder of MessageTemplate.

Summary

Public constructors

Returns a Builder instance.

Returns a Builder instance.

Public methods

@NonNull MessageTemplate.Builder

Adds an Action to display along with the message.

@NonNull MessageTemplate

Constructs the MessageTemplate defined by this builder.

@NonNull MessageTemplate.Builder
@RequiresCarApi(value = 2)
setActionStrip(@NonNull ActionStrip actionStrip)

This method is deprecated.

Use for each action

@NonNull MessageTemplate.Builder

Sets a Throwable for debugging purposes.

@NonNull MessageTemplate.Builder

Sets a debug message for debugging purposes.

@NonNull MessageTemplate.Builder
@RequiresCarApi(value = 7)
setHeader(@NonNull Header header)

Sets the Header for this template.

@NonNull MessageTemplate.Builder

This method is deprecated.

Use setStartHeaderAction

@NonNull MessageTemplate.Builder

Sets the icon to be displayed along with the message.

@NonNull MessageTemplate.Builder
@RequiresCarApi(value = 2)
setLoading(boolean isLoading)

Sets whether the template is in a loading state.

@NonNull MessageTemplate.Builder

This method is deprecated.

Use setTitle

Public constructors

Builder

Added in 1.0.0
public Builder(@NonNull CarText message)

Returns a Builder instance.

Parameters
@NonNull CarText message

the text message to display in the template

Throws
java.lang.NullPointerException

if the message is null

Builder

Added in 1.0.0
public Builder(@NonNull CharSequence message)

Returns a Builder instance.

Parameters
@NonNull CharSequence message

the text message to display in the template

Throws
java.lang.NullPointerException

if the message is null

Public methods

addAction

Added in 1.0.0
public @NonNull MessageTemplate.Builder addAction(@NonNull Action action)

Adds an Action to display along with the message.

Requirements This template allows up to 2 Actions in its body. Each action's title color can be customized with ForegroundCarColorSpan instances. Any other span is not supported.
Throws
java.lang.NullPointerException

if action is null

java.lang.IllegalArgumentException

if action does not meet the requirements

build

Added in 1.0.0
public @NonNull MessageTemplate build()

Constructs the MessageTemplate defined by this builder.

Requirements A non-empty message must be set on the template.

If none of the header Action, the header title or the action strip have been set on the template, the header is hidden.

Throws
java.lang.IllegalStateException

if the message is empty, or if the template is in loading state and an icon is specified.

setActionStrip

Added in 1.1.0
Deprecated in 1.7.0-beta02
@RequiresCarApi(value = 2)
public @NonNull MessageTemplate.Builder setActionStrip(@NonNull ActionStrip actionStrip)

Sets the ActionStrip for this template or null to not display an .

Unless set with this method, the template will not have an action strip.

Requirements This template allows up to 2 Actions in its ActionStrip. Of the 2 allowed Actions, one of them can contain a title as set via setTitle. Otherwise, only Actions with icons are allowed.
Throws
java.lang.IllegalArgumentException

if actionStrip does not meet the requirements

java.lang.NullPointerException

if actionStrip is null

setDebugMessage

Added in 1.0.0
public @NonNull MessageTemplate.Builder setDebugMessage(@NonNull Throwable cause)

Sets a Throwable for debugging purposes.

The cause will be displayed along with the message set in setDebugMessage.

The host may choose to not display this debugging information if it doesn't deem it appropriate, for example, when running on a production environment rather than in a simulator such as the Desktop Head Unit.

Throws
java.lang.NullPointerException

if icon is null

setDebugMessage

Added in 1.0.0
public @NonNull MessageTemplate.Builder setDebugMessage(@NonNull String debugMessage)

Sets a debug message for debugging purposes.

The debug message will be displayed along with the cause set in setDebugMessage.

The host may choose to not display this debugging information if it doesn't deem it appropriate, for example, when running on a production environment rather than in a simulator such as the Desktop Head Unit.

Throws
java.lang.NullPointerException

if icon is null

setHeader

Added in 1.7.0-beta02
@RequiresCarApi(value = 7)
public @NonNull MessageTemplate.Builder setHeader(@NonNull Header header)

Sets the Header for this template.

The end header actions will show up differently inside vs outside of a map template. See addEndHeaderAction for more details.

Throws
java.lang.NullPointerException

if header is null

setHeaderAction

Added in 1.0.0
Deprecated in 1.7.0-beta02
public @NonNull MessageTemplate.Builder setHeaderAction(@NonNull Action headerAction)

Sets the Action that will be displayed in the header of the template.

Unless set with this method, the template will not have a header action.

Requirements This template only supports either one of APP_ICON and BACK as a header Action.
Throws
java.lang.IllegalArgumentException

if headerAction does not meet the template's requirements

java.lang.NullPointerException

if headerAction is null

setIcon

Added in 1.0.0
public @NonNull MessageTemplate.Builder setIcon(@NonNull CarIcon icon)

Sets the icon to be displayed along with the message.

Unless set with this method, an icon will not be displayed.

Icon Sizing Guidance To minimize scaling artifacts across a wide range of car screens, apps should provide icons targeting a 128 x 128 dp bounding box. If the icon 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 icon is null

setLoading

Added in 1.1.0
@RequiresCarApi(value = 2)
public @NonNull MessageTemplate.Builder setLoading(boolean isLoading)

Sets whether the template is in a loading state.

If set to true, the UI shows a loading indicator where the icon would be otherwise. The caller is expected to call invalidate and send the new template content to the host once the data is ready.

setTitle

Added in 1.0.0
Deprecated in 1.7.0-beta02
public @NonNull MessageTemplate.Builder setTitle(@NonNull CharSequence title)

Sets the title of the template.

Unless set with this method, the template will not have a title.

Only DistanceSpans and DurationSpans are supported in the input string.

Throws
java.lang.NullPointerException

if title is null

java.lang.IllegalArgumentException

if title contains unsupported spans

See also
CarText