MessageTemplate.Builder

public static final class MessageTemplate.Builder
extends Object

java.lang.Object
   ↳ androidx.car.app.model.MessageTemplate.Builder


A builder of MessageTemplate.

Summary

Public constructors

Builder(CharSequence message)

Returns a MessageTemplate.Builder instance.

Builder(CarText message)

Returns a MessageTemplate.Builder instance.

Public methods

MessageTemplate.Builder addAction(Action action)

Adds an Action to display along with the message.

MessageTemplate build()

Constructs the MessageTemplate defined by this builder.

MessageTemplate.Builder setActionStrip(ActionStrip actionStrip)

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

MessageTemplate.Builder setDebugMessage(String debugMessage)

Sets a debug message for debugging purposes.

MessageTemplate.Builder setDebugMessage(Throwable cause)

Sets a Throwable for debugging purposes.

MessageTemplate.Builder setHeaderAction(Action headerAction)

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

MessageTemplate.Builder setIcon(CarIcon icon)

Sets the icon to be displayed along with the message.

MessageTemplate.Builder setLoading(boolean isLoading)

Sets whether the template is in a loading state.

MessageTemplate.Builder setTitle(CharSequence title)

Sets the title of the template.

Inherited methods

Public constructors

Builder

public Builder (CharSequence message)

Returns a MessageTemplate.Builder instance.

Parameters
message CharSequence: the text message to display in the template

Throws
NullPointerException if the message is null

Builder

public Builder (CarText message)

Returns a MessageTemplate.Builder instance.

Parameters
message CarText: the text message to display in the template

Throws
NullPointerException if the message is null

Public methods

addAction

public MessageTemplate.Builder addAction (Action action)

Adds an Action to display along with the message.

Requirements

This template allows up to 2 Actions in its body. The action's title color can be customized with ForegroundCarColorSpan instances, any other spans will be ignored by the host.

Parameters
action Action

Returns
MessageTemplate.Builder

Throws
NullPointerException if action is null
IllegalArgumentException if action does not meet the requirements

build

public MessageTemplate build ()

Constructs the MessageTemplate defined by this builder.

Requirements

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

Either a header Action or title must be set on the template.

Returns
MessageTemplate

Throws
IllegalStateException if the message is empty, if the template does not have either a title or header Action set, or if the template is in loading state and an icon is specified.

setActionStrip

public MessageTemplate.Builder setActionStrip (ActionStrip actionStrip)

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

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 Action.Builder.setTitle(CarText). Otherwise, only Actions with icons are allowed.

Parameters
actionStrip ActionStrip

Returns
MessageTemplate.Builder

Throws
IllegalArgumentException if actionStrip does not meet the requirements
NullPointerException if actionStrip is null

setDebugMessage

public MessageTemplate.Builder setDebugMessage (String debugMessage)

Sets a debug message for debugging purposes.

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

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.

Parameters
debugMessage String

Returns
MessageTemplate.Builder

Throws
NullPointerException if icon is null

setDebugMessage

public MessageTemplate.Builder setDebugMessage (Throwable cause)

Sets a Throwable for debugging purposes.

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

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.

Parameters
cause Throwable

Returns
MessageTemplate.Builder

Throws
NullPointerException if icon is null

setHeaderAction

public MessageTemplate.Builder setHeaderAction (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 Action.APP_ICON and Action.BACK as a header Action.

Parameters
headerAction Action

Returns
MessageTemplate.Builder

Throws
IllegalArgumentException if headerAction does not meet the template's requirements
NullPointerException if headerAction is null

setIcon

public MessageTemplate.Builder setIcon (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.

Parameters
icon CarIcon

Returns
MessageTemplate.Builder

Throws
NullPointerException if icon is null

setLoading

public 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 Screen.invalidate() and send the new template content to the host once the data is ready.

Parameters
isLoading boolean

Returns
MessageTemplate.Builder

setTitle

public MessageTemplate.Builder setTitle (CharSequence title)

Sets the title of the template.

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

Spans are not supported in the input string and will be ignored.

Parameters
title CharSequence

Returns
MessageTemplate.Builder

Throws
NullPointerException if title is null

See also: