androidx.wear.protolayout.layout

Top-level functions summary

ResourceBuilders.AndroidImageResourceByResId

Builds image resource that maps to an Android drawable by the given resource ID.
LayoutElementBuilders.Text
basicText(
    text: LayoutString,
    fontStyle: LayoutElementBuilders.FontStyle?,
    modifier: LayoutModifier?,
    maxLines: Int,
    alignment: Int,
    overflow: Int,
    lineHeight: @Dimension(unit = 2) Float
)

Builds a text string.
LayoutElementBuilders.Box
box(
    vararg contents: LayoutElementBuilders.LayoutElement,
    width: DimensionBuilders.ContainerDimension?,
    height: DimensionBuilders.ContainerDimension?,
    modifier: LayoutModifier?,
    horizontalAlignment: Int,
    verticalAlignment: Int
)

Creates a container which stacks all of its children on top of one another.
LayoutElementBuilders.Column
column(
    vararg contents: LayoutElementBuilders.LayoutElement,
    width: DimensionBuilders.ContainerDimension?,
    height: DimensionBuilders.ContainerDimension?,
    modifier: LayoutModifier?,
    horizontalAlignment: Int
)

Creates a column of elements.
LayoutElementBuilders.FontStyle
fontStyle(
    size: @Dimension(unit = 2) Float,
    italic: Boolean,
    underline: Boolean,
    color: LayoutColor?,
    weight: Int,
    letterSpacingEm: Float,
    @RequiresSchemaVersion(major = 1, minor = 300) additionalSizesSp: List<Float>,
    @RequiresSchemaVersion(major = 1, minor = 400) settings: List<LayoutElementBuilders.FontSetting>,
    @RequiresSchemaVersion(major = 1, minor = 400) preferredFontFamilies: List<String>
)

Builds the styling of a font (e.g. font size, and metrics).
ResourceBuilders.ImageResource

Builds a resource object for the image, based on the given resources types.
ResourceBuilders.InlineImageResource
inlineImageResource(
    compressedBytes: ByteArray,
    widthPx: @Dimension(unit = 1) Int,
    heightPx: @Dimension(unit = 1) Int
)

Builds image resource that contains the compressed image data extracted from the raw image data.
ResourceBuilders.InlineImageResource
inlineImageResource(
    pixelBuffer: ByteArray,
    format: Int,
    widthPx: @Dimension(unit = 1) Int,
    heightPx: @Dimension(unit = 1) Int
)

Builds image resource that contains the pixel buffer in the specified format of the given byte array data.
ResourceBuilders.AndroidLottieResourceByResId
lottieResource(
    @RawRes rawResourceId: Int,
    progress: DynamicBuilders.DynamicFloat,
    properties: List<ResourceBuilders.LottieProperty>
)

Builds Lottie resource that is read from a raw Android resource ID and can be played via progress.
ResourceBuilders.AndroidLottieResourceByResId
lottieResource(
    @RawRes rawResourceId: Int,
    startTrigger: TriggerBuilders.Trigger?,
    properties: List<ResourceBuilders.LottieProperty>
)

Builds Lottie resource that is read from a raw Android resource ID and can be played via starting trigger.
LayoutElementBuilders.Row
row(
    vararg contents: LayoutElementBuilders.LayoutElement,
    width: DimensionBuilders.ContainerDimension?,
    height: DimensionBuilders.ContainerDimension?,
    modifier: LayoutModifier?,
    verticalAlignment: Int
)

Creates a row of elements.
LayoutElementBuilders.Spacer
spacer(
    width: DimensionBuilders.SpacerDimension?,
    height: DimensionBuilders.SpacerDimension?,
    modifier: LayoutModifier?,
    @RequiresSchemaVersion(major = 1, minor = 200) horizontalLayoutConstraint: DimensionBuilders.HorizontalLayoutConstraint?,
    @RequiresSchemaVersion(major = 1, minor = 200) verticalLayoutConstraint: DimensionBuilders.VerticalLayoutConstraint?
)

Creates a simple spacer, typically used to provide padding between adjacent elements.

Extension functions summary

LayoutElementBuilders.Image
ProtoLayoutScope.basicImage(
    resource: ResourceBuilders.ImageResource,
    width: DimensionBuilders.ImageDimension,
    height: DimensionBuilders.ImageDimension,
    protoLayoutResourceId: String?,
    modifier: LayoutModifier?,
    contentScaleMode: Int,
    tintColor: LayoutColor?
)

Builds an image from the given resources.

Top-level functions

androidImageResource

fun androidImageResource(resourceId: @DrawableRes Int): ResourceBuilders.AndroidImageResourceByResId

Builds image resource that maps to an Android drawable by the given resource ID.

Parameters
resourceId: @DrawableRes Int

The drawable resource ID to map this image

basicText

fun basicText(
    text: LayoutString,
    fontStyle: LayoutElementBuilders.FontStyle? = null,
    modifier: LayoutModifier? = null,
    maxLines: Int = 0,
    alignment: Int = TEXT_ALIGN_UNDEFINED,
    overflow: Int = TEXT_OVERFLOW_UNDEFINED,
    lineHeight: @Dimension(unit = 2) Float = Float.NaN
): LayoutElementBuilders.Text

Builds a text string.

Parameters
text: LayoutString

The text to render.
fontStyle: LayoutElementBuilders.FontStyle? = null

The style of font to use (size, bold etc). If not specified, defaults to the platform's default body font.
modifier: LayoutModifier? = null

Modifiers to set to this element.
maxLines: Int = 0

The maximum number of lines that can be represented by the Text element. If not defined, the Text element will be treated as a single-line element.
alignment: Int = TEXT_ALIGN_UNDEFINED

Alignment of the text within its bounds. Note that a Text element will size itself to wrap its contents, so this option is meaningless for single-line text (for that, use alignment of the outer container), unless this text overflows. For multi-line text, however, this will set the alignment of lines relative to the Text element bounds. If not defined, defaults to TEXT_ALIGN_CENTER.
overflow: Int = TEXT_OVERFLOW_UNDEFINED

How to handle text which overflows the bound of the Text element. A Text element will grow as large as possible inside its parent container (while still respecting max_lines); if it cannot grow large enough to render all of its text, the text which cannot fit inside its container will be truncated. If not defined, defaults to TEXT_OVERFLOW_TRUNCATE.
lineHeight: @Dimension(unit = 2) Float = Float.NaN

The explicit height between lines of text. This is equivalent to the vertical distance between subsequent baselines. If not specified, defaults the font's recommended interline spacing.

box

fun box(
    vararg contents: LayoutElementBuilders.LayoutElement,
    width: DimensionBuilders.ContainerDimension? = null,
    height: DimensionBuilders.ContainerDimension? = null,
    modifier: LayoutModifier? = null,
    horizontalAlignment: Int = HORIZONTAL_ALIGN_UNDEFINED,
    verticalAlignment: Int = VERTICAL_ALIGN_UNDEFINED
): LayoutElementBuilders.Box

Creates a container which stacks all of its children on top of one another. This also allows to add a background color, or to have a border around them with some padding.

Parameters
vararg contents: LayoutElementBuilders.LayoutElement

The list of child elements to place inside this container.
width: DimensionBuilders.ContainerDimension? = null

The width of the box. Defaults to wrap.
height: DimensionBuilders.ContainerDimension? = null

The height of the box. Defaults to wrap.
modifier: LayoutModifier? = null

Modifiers to set to this element
horizontalAlignment: Int = HORIZONTAL_ALIGN_UNDEFINED

The horizontal alignment of the element inside this box. Defaults to center aligned.
verticalAlignment: Int = VERTICAL_ALIGN_UNDEFINED

The vertical alignment of the element inside this box. Defaults to center aligned.

column

fun column(
    vararg contents: LayoutElementBuilders.LayoutElement,
    width: DimensionBuilders.ContainerDimension? = null,
    height: DimensionBuilders.ContainerDimension? = null,
    modifier: LayoutModifier? = null,
    horizontalAlignment: Int = HORIZONTAL_ALIGN_UNDEFINED
): LayoutElementBuilders.Column

Creates a column of elements. Each child element will be laid out vertically, one after another (i.e. stacking down). This element will size itself to the smallest size required to hold all of its children (e.g. if it contains three elements sized 10x10, 20x20 and 30x30, the resulting column will be 30x60).

If specified, horizontal_alignment can be used to control the gravity inside the container, affecting the horizontal placement of children whose width are smaller than the resulting column width.

Parameters
vararg contents: LayoutElementBuilders.LayoutElement

The list of child elements to place inside this container.
width: DimensionBuilders.ContainerDimension? = null

The width of the box. Defaults to wrap.
height: DimensionBuilders.ContainerDimension? = null

The height of the box. Defaults to wrap.
modifier: LayoutModifier? = null

Modifiers to set to this element
horizontalAlignment: Int = HORIZONTAL_ALIGN_UNDEFINED

The horizontal alignment of the element inside this box. Defaults to center aligned.

fontStyle

fun fontStyle(
    size: @Dimension(unit = 2) Float = 0.0f,
    italic: Boolean = false,
    underline: Boolean = false,
    color: LayoutColor? = null,
    weight: Int = FONT_WEIGHT_UNDEFINED,
    letterSpacingEm: Float = Float.NaN,
    @RequiresSchemaVersion(major = 1, minor = 300) additionalSizesSp: List<Float> = emptyList(),
    @RequiresSchemaVersion(major = 1, minor = 400) settings: List<LayoutElementBuilders.FontSetting> = emptyList(),
    @RequiresSchemaVersion(major = 1, minor = 400) preferredFontFamilies: List<String> = emptyList()
): LayoutElementBuilders.FontStyle

Builds the styling of a font (e.g. font size, and metrics).

Parameters
size: @Dimension(unit = 2) Float = 0.0f

The size of the font, in scaled pixels (sp). If not specified, defaults to the size of the system's "body" font.
italic: Boolean = false

Whether the text should be rendered in a italic typeface.
underline: Boolean = false

Whether the text should be rendered with an underline.
color: LayoutColor? = null

The text color. If not defined, defaults to white.
weight: Int = FONT_WEIGHT_UNDEFINED

The weight of the font. If the provided value is not supported on a platform, the nearest supported value will be used. If not defined, or when set to an invalid value, defaults to "normal".
letterSpacingEm: Float = Float.NaN

The text letter-spacing. Positive numbers increase the space between letters while negative numbers tighten the space. If not specified, defaults to 0.
@RequiresSchemaVersion(major = 1, minor = 300) additionalSizesSp: List<Float> = emptyList()

when this FontStyle is applied to a Text element with static text, the text size will be automatically picked from the provided sizes to try to perfectly fit within its parent bounds. In other words, the largest size from the specified preset sizes that can fit the most text within the parent bounds will be used.
@RequiresSchemaVersion(major = 1, minor = 400) settings: List<LayoutElementBuilders.FontSetting> = emptyList()

The collection of font settings to be applied. If more than one Setting with the same axis tag is specified, the first one will be used. Supported settings depend on the font used by the system and the renderer version. However, if using FontSetting.weight axis with a value higher than 500, consider adding a fallback weight parameter as FONT_WEIGHT_MEDIUM or FONT_WEIGHT_BOLD to avoid text looking too thin on fonts that don't support weight axis.
@RequiresSchemaVersion(major = 1, minor = 400) preferredFontFamilies: List<String> = emptyList()

is the ordered list of font families to pick from for this FontStyle. If the given font family is not available on a device, the fallback values will be attempted to use, in order in which they are given. Note that support for font family customization is dependent on the target platform.

imageResource

fun imageResource(
    androidImage: ResourceBuilders.AndroidImageResourceByResId? = null,
    inlineImage: ResourceBuilders.InlineImageResource? = null,
    lottie: ResourceBuilders.AndroidLottieResourceByResId? = null
): ResourceBuilders.ImageResource

Builds a resource object for the image, based on the given resources types. This can hold multiple underlying resource types, which the underlying renderer will pick according to what it is supported in its version and what it thinks is appropriate.

It is recommended to use this inside the APIs for the automatic resource registration, such as basicImage.

Parameters
androidImage: ResourceBuilders.AndroidImageResourceByResId? = null

The image resource that maps to an Android drawable by resource ID
inlineImage: ResourceBuilders.InlineImageResource? = null

The image resource that contains the image data inline
lottie: ResourceBuilders.AndroidLottieResourceByResId? = null

The Lottie resource that is read from a raw Android resource ID

inlineImageResource

fun inlineImageResource(
    compressedBytes: ByteArray,
    widthPx: @Dimension(unit = 1) Int,
    heightPx: @Dimension(unit = 1) Int
): ResourceBuilders.InlineImageResource

Builds image resource that contains the compressed image data extracted from the raw image data.

This data shouldn't be in any format. If the image data bytes are formatted use inlineImageResource with (ByteArray, Int, Int, Int).

Parameters
compressedBytes: ByteArray

The byte array representing the image
widthPx: @Dimension(unit = 1) Int

The native width of the image, in pixels.
heightPx: @Dimension(unit = 1) Int

The native height of the image, in pixels.

inlineImageResource

fun inlineImageResource(
    pixelBuffer: ByteArray,
    format: Int,
    widthPx: @Dimension(unit = 1) Int,
    heightPx: @Dimension(unit = 1) Int
): ResourceBuilders.InlineImageResource

Builds image resource that contains the pixel buffer in the specified format of the given byte array data.

Parameters
pixelBuffer: ByteArray

The byte array representing the image
format: Int

The format of the byte array data representing the image. This should be specific format of IMAGE_FORMAT_RGB_565 or IMAGE_FORMAT_ARGB_8888. If compressed image data is used, then inlineImageResource with (ByteArray, Int, Int) should be used, without specified format.
widthPx: @Dimension(unit = 1) Int

The native width of the image, in pixels.
heightPx: @Dimension(unit = 1) Int

The native height of the image, in pixels.

lottieResource

fun lottieResource(
    @RawRes rawResourceId: Int,
    progress: DynamicBuilders.DynamicFloat,
    properties: List<ResourceBuilders.LottieProperty> = emptyList()
): ResourceBuilders.AndroidLottieResourceByResId

Builds Lottie resource that is read from a raw Android resource ID and can be played via progress.

Parameters
@RawRes rawResourceId: Int

The raw resource ID to map this Lottie
progress: DynamicBuilders.DynamicFloat

The DynamicFloat, normally transformed from certain states with the data binding pipeline to control the progress of the animation. Its value is required to fall in the range of 0.0, 1.0. Any values outside this range would be clamped.
properties: List<ResourceBuilders.LottieProperty> = emptyList()

The list of properties to customize Lottie further
Throws
kotlin.IllegalArgumentException

if the number of properties is larger than AndroidLottieResourceByResId.getMaxPropertiesCount()

lottieResource

fun lottieResource(
    @RawRes rawResourceId: Int,
    startTrigger: TriggerBuilders.Trigger? = null,
    properties: List<ResourceBuilders.LottieProperty> = emptyList()
): ResourceBuilders.AndroidLottieResourceByResId

Builds Lottie resource that is read from a raw Android resource ID and can be played via starting trigger.

Parameters
@RawRes rawResourceId: Int

The raw resource ID to map this Lottie
startTrigger: TriggerBuilders.Trigger? = null

The trigger to start the animation. If not set, animation will be played on layout load
properties: List<ResourceBuilders.LottieProperty> = emptyList()

The list of properties to customize Lottie further
Throws
kotlin.IllegalArgumentException

if the number of properties is larger than AndroidLottieResourceByResId.getMaxPropertiesCount()

row

fun row(
    vararg contents: LayoutElementBuilders.LayoutElement,
    width: DimensionBuilders.ContainerDimension? = null,
    height: DimensionBuilders.ContainerDimension? = null,
    modifier: LayoutModifier? = null,
    verticalAlignment: Int = VERTICAL_ALIGN_UNDEFINED
): LayoutElementBuilders.Row

Creates a row of elements. Each child will be laid out horizontally, one after another (i.e. stacking to the right). This element will size itself to the smallest size required to hold all of its children (e.g. if it contains three elements sized 10x10, 20x20 and 30x30, the resulting row will be 60x30).

If specified, verticalAlignment can be used to control the gravity inside the container, affecting the vertical placement of children whose width are smaller than the resulting row height.

Parameters
vararg contents: LayoutElementBuilders.LayoutElement

The list of child elements to place inside this container.
width: DimensionBuilders.ContainerDimension? = null

The width of the box. Defaults to wrap.
height: DimensionBuilders.ContainerDimension? = null

The height of the box. Defaults to wrap.
modifier: LayoutModifier? = null

Modifiers to set to this element
verticalAlignment: Int = VERTICAL_ALIGN_UNDEFINED

The vertical alignment of the element inside this box. Defaults to center aligned.

spacer

fun spacer(
    width: DimensionBuilders.SpacerDimension? = null,
    height: DimensionBuilders.SpacerDimension? = null,
    modifier: LayoutModifier? = null,
    @RequiresSchemaVersion(major = 1, minor = 200) horizontalLayoutConstraint: DimensionBuilders.HorizontalLayoutConstraint? = null,
    @RequiresSchemaVersion(major = 1, minor = 200) verticalLayoutConstraint: DimensionBuilders.VerticalLayoutConstraint? = null
): LayoutElementBuilders.Spacer

Creates a simple spacer, typically used to provide padding between adjacent elements.

Parameters
width: DimensionBuilders.SpacerDimension? = null

The width of the box. Defaults to wrap.
height: DimensionBuilders.SpacerDimension? = null

The height of the box. Defaults to wrap.
modifier: LayoutModifier? = null

Modifiers to set to this element
@RequiresSchemaVersion(major = 1, minor = 200) horizontalLayoutConstraint: DimensionBuilders.HorizontalLayoutConstraint? = null

The bounding constraints for the layout affected by the dynamic value from width. If the SpacerDimension for width does not have a dynamic value, this will be ignored.
@RequiresSchemaVersion(major = 1, minor = 200) verticalLayoutConstraint: DimensionBuilders.VerticalLayoutConstraint? = null

The bounding constraints for the layout affected by the dynamic value from height. If the SpacerDimension for height does not have a dynamic value, this will be ignored.

Extension functions

basicImage

fun ProtoLayoutScope.basicImage(
    resource: ResourceBuilders.ImageResource,
    width: DimensionBuilders.ImageDimension,
    height: DimensionBuilders.ImageDimension,
    protoLayoutResourceId: String? = null,
    modifier: LayoutModifier? = null,
    contentScaleMode: Int = CONTENT_SCALE_MODE_UNDEFINED,
    tintColor: LayoutColor? = null
): LayoutElementBuilders.Image

Builds an image from the given resources.

Parameters
resource: ResourceBuilders.ImageResource

An Image resource, used in the layout in the place of this element
width: DimensionBuilders.ImageDimension

The width of the image
height: DimensionBuilders.ImageDimension

The height of the image
protoLayoutResourceId: String? = null

The optional String ID for the resource. This is optional as it has a default value assigned by the automatic resource registration, but can be used to override it if desired to mark the resource with readable ID.
modifier: LayoutModifier? = null

Modifiers to set to this element
contentScaleMode: Int = CONTENT_SCALE_MODE_UNDEFINED

Defines how the content which does not match the dimensions of its bounds (e.g. an image resource being drawn inside an Image) will be resized to fit its bounds
tintColor: LayoutColor? = null

The tint color to apply to the image