androidx.wear.protolayout.material3
Classes
ButtonGroupScope |
Scope for the children of a |
ColorScheme |
A |
EdgeButtonColors |
Represents the container and content colors used in |
EdgeButtonStyle |
Provides style values for edge button component. |
MaterialScope |
Receiver scope which is used by all ProtoLayout Material3 components and layout to support opinionated defaults and to provide the global information for styling Material3 components. |
Shapes |
Material surfaces can be displayed in different shapes. |
Objects
ButtonGroupDefaults |
Contains the default values used by |
CardDefaults |
|
EdgeButtonDefaults |
|
Typography |
Class holding typography definitions as defined by the Wear Material3 typography specification. |
Annotations
Top-level functions summary
ColorScheme |
dynamicColorScheme(context: Context, defaultColorScheme: ColorScheme)Creates a dynamic color scheme. |
Boolean |
isDynamicColorSchemeEnabled(context: Context)Returns whether the dynamic colors scheme (colors following the system theme) is enabled. |
LayoutElementBuilders.LayoutElement |
materialScope(Creates a top-level receiver scope |
Extension functions summary
Top-level functions
dynamicColorScheme
fun dynamicColorScheme(
context: Context,
defaultColorScheme: ColorScheme = ColorScheme()
): ColorScheme
Creates a dynamic color scheme.
Use this function to create a color scheme based on the current watchface. If the user changes the watchface colors, this color scheme will change accordingly. This function checks whether the dynamic color scheme can be used and returns defaultColorScheme otherwise.
| Parameters | |
|---|---|
context: Context |
The context required to get system resource data. |
defaultColorScheme: ColorScheme = ColorScheme() |
The fallback |
isDynamicColorSchemeEnabled
fun isDynamicColorSchemeEnabled(context: Context): Boolean
Returns whether the dynamic colors scheme (colors following the system theme) is enabled.
If enabled, and elements or MaterialScope are opted in to using dynamic theme, colors will change whenever system theme changes.
materialScope
fun materialScope(
context: Context,
deviceConfiguration: DeviceParametersBuilders.DeviceParameters,
allowDynamicTheme: Boolean = true,
defaultColorScheme: ColorScheme = ColorScheme(),
layout: MaterialScope.() -> LayoutElementBuilders.LayoutElement
): LayoutElementBuilders.LayoutElement
Creates a top-level receiver scope MaterialScope that calls the given layout to support for opinionated defaults and building Material3 components and layout, with default dynamic theme.
| Parameters | |
|---|---|
context: Context |
The Android Context for the Tile service |
deviceConfiguration: DeviceParametersBuilders.DeviceParameters |
The device parameters for where the components will be rendered |
allowDynamicTheme: Boolean = true |
If dynamic colors theme should be used on components, meaning that colors will follow the system theme if enabled on the device. If not set, defaults to using the system theme |
defaultColorScheme: ColorScheme = ColorScheme() |
Color Scheme with static colors. The color theme to be used, when |
layout: MaterialScope.() -> LayoutElementBuilders.LayoutElement |
Scoped slot for the content of layout to be displayed |
Extension functions
backgroundImage
fun MaterialScope.backgroundImage(
protoLayoutResourceId: String,
width: DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.width,
height: DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.height,
overlayColor: ColorBuilders.ColorProp = defaultBackgroundImageStyle.overlayColor,
overlayWidth: DimensionBuilders.ContainerDimension = defaultBackgroundImageStyle.overlayWidth,
overlayHeight: DimensionBuilders.ContainerDimension = defaultBackgroundImageStyle.overlayHeight,
shape: ModifiersBuilders.Corner = defaultBackgroundImageStyle.shape,
contentScaleMode: Int = defaultBackgroundImageStyle.contentScaleMode
): LayoutElementBuilders.LayoutElement
Returns the image background with the defined style.
Material components provide proper defaults for the background image. In order to take advantage of those defaults, this should be used with the resource ID only: backgroundImage("id").
| Parameters | |
|---|---|
protoLayoutResourceId: String |
The protolayout resource id of the icon. Node that, this is not an Android resource id. |
width: DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.width |
The width of an image. Usually, this matches the width of the parent component this is used in. |
height: DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.height |
The height of an image. Usually, this matches the height of the parent component this is used in. |
overlayColor: ColorBuilders.ColorProp = defaultBackgroundImageStyle.overlayColor |
The color used to provide the overlay over the image for better readability. It's recommended to use |
overlayWidth: DimensionBuilders.ContainerDimension = defaultBackgroundImageStyle.overlayWidth |
The width of the overlay on top of the image background |
overlayHeight: DimensionBuilders.ContainerDimension = defaultBackgroundImageStyle.overlayHeight |
The height of the overlay on top of the image background |
shape: ModifiersBuilders.Corner = defaultBackgroundImageStyle.shape |
The shape of the corners for the image |
contentScaleMode: Int = defaultBackgroundImageStyle.contentScaleMode |
The content scale mode for the image to define how image will adapt to the given size |
buttonGroup
fun MaterialScope.buttonGroup(
width: DimensionBuilders.ContainerDimension = expand(),
height: DimensionBuilders.ContainerDimension = expand(),
spacing: @Dimension(unit = 0) Float = DEFAULT_SPACER_SIZE_DP,
content: ButtonGroupScope.() -> Unit
): LayoutElementBuilders.LayoutElement
ProtoLayout Material3 component-layout that places its children in a horizontal sequence.
These behave as a group which fill the available space to maximize on screen real estate. The color and size of the child elements should be changed in order to create hierarchy and priority.
The width and height of the Button/Card should be flexible (set to androidx.wear.protolayout.DimensionBuilders.expand or androidx.wear.protolayout.DimensionBuilders.weight) and their proportion should be either equal or weight based. However the buttonGroup displays correctly too if the sizes of elements provided are set to a fixed width/height, although it can lead to more empty space on large screen sizes.
A buttonGroup with more than one row can be created by using multiple buttonGroup and Spacers inside a androidx.wear.protolayout.LayoutElementBuilders.Column:
Column.Builder()
.setWidth(expand())
.setHeight(expand())
.addContent(buttonGroup {...})
.addContent(DEFAULT_SPACER_BETWEEN_BUTTON_GROUPS)
.addContent(buttonGroup {...})
.build()
}
Note that, having more than 2 rows in a Column could lead to too small height of elements that aren't in line with minimum tap target.
| Parameters | |
|---|---|
width: DimensionBuilders.ContainerDimension = expand() |
The width of this button group |
height: DimensionBuilders.ContainerDimension = expand() |
The height of this button group |
spacing: @Dimension(unit = 0) Float = DEFAULT_SPACER_SIZE_DP |
The amount of spacing between buttons |
content: ButtonGroupScope.() -> Unit |
The content for each child. The UX guidance is to use no more than 3 elements within a this button group. |
card
fun MaterialScope.card(
onClick: ModifiersBuilders.Clickable,
contentDescription: TypeBuilders.StringProp,
width: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = shapes.large,
backgroundColor: ColorBuilders.ColorProp? = null,
background: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
contentPadding: ModifiersBuilders.Padding = Padding.Builder().setAll(DEFAULT_CONTENT_PADDING.toDp()).build(),
content: MaterialScope.() -> LayoutElementBuilders.LayoutElement
): LayoutElementBuilders.LayoutElement
ProtoLayout Material3 clickable component card that offers a single slot to take any content.
It can be used as the container for more opinionated Card components that take specific content such as icons, images, primary label, secondary label, etc.
The Card is Rectangle shaped with some rounded corners by default. It is highly recommended to set its width and height to fill the available space, by expand or weight for optimal experience across different screen sizes.
It can be used for displaying any clickable container with additional data, text or graphics.
import androidx.wear.protolayout.DimensionBuilders.expand import androidx.wear.protolayout.material3.backgroundImage import androidx.wear.protolayout.material3.card import androidx.wear.protolayout.material3.materialScope import androidx.wear.protolayout.material3.primaryLayout import androidx.wear.protolayout.material3.prop import androidx.wear.protolayout.material3.text materialScope(context, deviceConfiguration) { primaryLayout( mainSlot = { card( onClick = clickable, contentDescription = "Card with image background".prop(), width = expand(), height = expand(), background = { backgroundImage(protoLayoutResourceId = "id") } ) { text("Content of the Card!".prop()) } } ) }
| Parameters | |
|---|---|
onClick: ModifiersBuilders.Clickable |
Associated |
contentDescription: TypeBuilders.StringProp |
The content description to be read by Talkback. |
width: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension() |
The width of this card. It's highly recommended to set this to |
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension() |
The height of this card. It's highly recommended to set this to |
shape: ModifiersBuilders.Corner = shapes.large |
Defines the card's shape, in other words the corner radius for this card. |
backgroundColor: ColorBuilders.ColorProp? = null |
The color to be used as a background of this card. If the background image is also specified, it will be laid out on top of this color. |
background: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null |
The background object to be used behind the content in the card. It is recommended the default styling that is automatically provided by only calling |
contentPadding: ModifiersBuilders.Padding = Padding.Builder().setAll(DEFAULT_CONTENT_PADDING.toDp()).build() |
The inner padding used to prevent inner content from being too close to the card's edge. It's highly recommended to keep the default. |
content: MaterialScope.() -> LayoutElementBuilders.LayoutElement |
The inner content to be put inside of this card. |
icon
fun MaterialScope.icon(
protoLayoutResourceId: String,
size: DimensionBuilders.ImageDimension = defaultIconStyle.size,
tintColor: ColorBuilders.ColorProp = defaultIconStyle.tintColor
): LayoutElementBuilders.LayoutElement
Returns the icon components with the defined style.
Material components provide proper defaults for this icon. In order to take advantage of those, this should be used with the resource ID only: icon("id").
| Parameters | |
|---|---|
protoLayoutResourceId: String |
The protolayout resource id of the icon. Node that, this is not an Android resource id. |
size: DimensionBuilders.ImageDimension = defaultIconStyle.size |
The side of an icon that will be used for width and height. |
tintColor: ColorBuilders.ColorProp = defaultIconStyle.tintColor |
The color used to tint the icon. |
iconEdgeButton
fun MaterialScope.iconEdgeButton(
onClick: ModifiersBuilders.Clickable,
contentDescription: TypeBuilders.StringProp,
colors: EdgeButtonColors = filled(),
iconContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement
): LayoutElementBuilders.LayoutElement
ProtoLayout Material3 component edge button that offers a single slot to take an icon or similar round, small content.
The edge button is intended to be used at the bottom of a round screen. It has a special shape with its bottom almost follows the screen's curvature. It has fixed height, and takes 1 line of text or a single icon. This button represents the most important action on the screen, and it must occupy the whole horizontal space in its position as well as being anchored to the screen bottom.
This component is not intended to be used with an image background.
import androidx.wear.protolayout.material3.icon import androidx.wear.protolayout.material3.iconEdgeButton import androidx.wear.protolayout.material3.materialScope import androidx.wear.protolayout.material3.prop import androidx.wear.protolayout.material3.text materialScope(context, deviceConfiguration) { iconEdgeButton(onClick = clickable, contentDescription = "Description of a button".prop()) { icon(protoLayoutResourceId = "id") } }
| Parameters | |
|---|---|
onClick: ModifiersBuilders.Clickable |
Associated |
contentDescription: TypeBuilders.StringProp |
The content description to be read by Talkback. |
colors: EdgeButtonColors = filled() |
The colors used for this button. If not set, |
iconContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement |
The icon slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling |
primaryLayout
fun MaterialScope.primaryLayout(
mainSlot: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
titleSlot: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
bottomSlot: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
labelForBottomSlot: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
onClick: ModifiersBuilders.Clickable? = null
): LayoutElementBuilders.LayoutElement
ProtoLayout Material3 full screen layout that represents a suggested Material3 layout style that is responsive and takes care of the elements placement, together with the recommended margin and padding applied.
This layout is meant to occupy the whole screen, so nothing else should be added on top of it.
On the top, there is an icon that will be automatically placed by the system, followed by the optional title slot. The icon slot needs to be reserved for the whole ProtoLayout Layout and no other content should be added at the top of the screen as it will be overlapped with the system placed icon.
At the bottom, there is an optional fixed slot for either {@link EdgeButton} as a main action or small non tappable content.
The middle of the layout is main content, that will fill the available space. For the best results across different screen sizes, it's recommended that this content's dimension are also DimensionBuilders.expand or DimensionBuilders.weight. Additional content in the main one can be added after a 225dp breakpoint.
import androidx.wear.protolayout.LayoutElementBuilders import androidx.wear.protolayout.LayoutElementBuilders.LayoutElement import androidx.wear.protolayout.ModifiersBuilders import androidx.wear.protolayout.material3.buttonGroup import androidx.wear.protolayout.material3.icon import androidx.wear.protolayout.material3.iconEdgeButton import androidx.wear.protolayout.material3.materialScope import androidx.wear.protolayout.material3.primaryLayout import androidx.wear.protolayout.material3.prop import androidx.wear.protolayout.material3.text materialScope(context, deviceConfiguration) { primaryLayout( titleSlot = { text("App title".prop()) }, mainSlot = { buttonGroup { // To be populated with proper components buttonGroupItem { LayoutElementBuilders.Box.Builder() .setModifiers( ModifiersBuilders.Modifiers.Builder() .setBackground( ModifiersBuilders.Background.Builder() .setCorner(shapes.full) .build() ) .build() ) .build() } } }, bottomSlot = { iconEdgeButton(clickable, "Description".prop()) { icon("id") } } ) }
| Parameters | |
|---|---|
mainSlot: MaterialScope.() -> LayoutElementBuilders.LayoutElement |
The main, central content for this layout. It's recommended for this content to fill the available width and height for the best result across different screen size. This layout places proper padding to prevent content from being cropped by the screen. Note that depending on the corner shapes and different elements on the screen, there might be a need to change padding on some of the elements in this slot. The content passed here can also have an additional content value added to it, after |
titleSlot: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null |
The app title in the top slot, just below the icon. This should be one line of |
bottomSlot: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null |
The content for bottom slot in this layout, that will be anchored to the bottom edge of the screen. This should be either a small non tappable content such as Text with optional label for it or tappable main action with |
labelForBottomSlot: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null |
The label displayed just above the |
onClick: ModifiersBuilders.Clickable? = null |
The clickable action for whole layout. If any area (outside of other added tappable components) is clicked, it will fire the associated action. |
text
fun MaterialScope.text(
text: TypeBuilders.StringProp,
stringLayoutConstraint: TypeBuilders.StringLayoutConstraint = StringLayoutConstraint.Builder(text.value).build(),
typography: Int = defaultTextElementStyle.typography,
color: ColorBuilders.ColorProp = defaultTextElementStyle.color,
italic: Boolean = defaultTextElementStyle.italic,
underline: Boolean = defaultTextElementStyle.underline,
scalable: Boolean = defaultTextElementStyle.scalable,
maxLines: Int = defaultTextElementStyle.maxLines,
multilineAlignment: Int = defaultTextElementStyle.multilineAlignment,
overflow: Int = defaultTextElementStyle.overflow,
modifiers: ModifiersBuilders.Modifiers = Modifiers.Builder().build()
): LayoutElementBuilders.LayoutElement
ProtoLayout component that represents text object holding any information.
There are pre-defined typography styles that can be obtained from Materials token system in Typography.
import androidx.wear.protolayout.material3.Typography import androidx.wear.protolayout.material3.materialScope import androidx.wear.protolayout.material3.prop import androidx.wear.protolayout.material3.text materialScope(context, deviceConfiguration) { text(text = "Hello Material3".prop(), typography = Typography.DISPLAY_LARGE) }
import androidx.wear.protolayout.TypeBuilders.StringLayoutConstraint import androidx.wear.protolayout.TypeBuilders.StringProp import androidx.wear.protolayout.expression.DynamicBuilders.DynamicString import androidx.wear.protolayout.material3.Typography import androidx.wear.protolayout.material3.materialScope import androidx.wear.protolayout.material3.text materialScope(context, deviceConfiguration) { text( text = StringProp.Builder("Static") .setDynamicValue(DynamicString.constant("Dynamic")) .build(), stringLayoutConstraint = StringLayoutConstraint.Builder("Constraint").build(), typography = Typography.DISPLAY_LARGE, color = colorScheme.tertiary, underline = true, maxLines = 5 ) }
| Parameters | |
|---|---|
text: TypeBuilders.StringProp |
The text content for this component. |
stringLayoutConstraint: TypeBuilders.StringLayoutConstraint = StringLayoutConstraint.Builder(text.value).build() |
The layout constraints used to correctly measure Text view size and align text when |
typography: Int = defaultTextElementStyle.typography |
The typography from |
color: ColorBuilders.ColorProp = defaultTextElementStyle.color |
The color to be applied to this text. It is recommended to use predefined default styles created by each component or |
italic: Boolean = defaultTextElementStyle.italic |
Whether text should be displayed as italic. |
underline: Boolean = defaultTextElementStyle.underline |
Whether text should be displayed as underlined. |
scalable: Boolean = defaultTextElementStyle.scalable |
Whether text should scale with the user font size. |
maxLines: Int = defaultTextElementStyle.maxLines |
The maximum number of lines that text can occupy. |
multilineAlignment: Int = defaultTextElementStyle.multilineAlignment |
The horizontal alignment of the multiple lines of text. |
overflow: Int = defaultTextElementStyle.overflow |
The overflow strategy when text doesn't have enough space to be shown. |
modifiers: ModifiersBuilders.Modifiers = Modifiers.Builder().build() |
The additional |
textEdgeButton
fun MaterialScope.textEdgeButton(
onClick: ModifiersBuilders.Clickable,
contentDescription: TypeBuilders.StringProp,
colors: EdgeButtonColors = filled(),
labelContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement
): LayoutElementBuilders.LayoutElement
ProtoLayout Material3 component edge button that offers a single slot to take a text or similar long and wide content.
The edge button is intended to be used at the bottom of a round screen. It has a special shape with its bottom almost follows the screen's curvature. It has fixed height, and takes 1 line of text or a single icon. This button represents the most important action on the screen, and it must occupy the whole horizontal space in its position as well as being anchored to the screen bottom.
This component is not intended to be used with an image background.
import androidx.wear.protolayout.material3.materialScope import androidx.wear.protolayout.material3.prop import androidx.wear.protolayout.material3.text import androidx.wear.protolayout.material3.textEdgeButton materialScope(context, deviceConfiguration) { textEdgeButton(onClick = clickable, contentDescription = "Description of a button".prop()) { text("Hello".prop()) } }
| Parameters | |
|---|---|
onClick: ModifiersBuilders.Clickable |
Associated |
contentDescription: TypeBuilders.StringProp |
The content description to be read by Talkback. |
colors: EdgeButtonColors = filled() |
The colors used for this button. If not set, |
labelContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement |
The label slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling |
withOpacity
fun ColorBuilders.ColorProp.withOpacity(
ratio: @FloatRange(from = 0.0, to = 1.0) Float
): ColorBuilders.ColorProp
Changes the opacity/transparency of the given color.
Note that this only looks at the static value of the ColorProp, any dynamic value will be ignored.