# MaterialScope
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/MaterialScope.kt+class:androidx.wear.protolayout.material3.MaterialScope) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0)
*** ** * ** ***
```
@MaterialScopeMarker
open class 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.
The MaterialScope includes:
- theme, which is used to retrieve the color, typography or shape values.
- `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DeviceParametersBuilders.DeviceParameters`, which contains screen size, font scale, renderer schema version etc.
- Default usage of system theme, with the option to opt out.
## Summary
| ### Public properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#colorScheme()` Color Scheme used within this scope and its components. |
| `https://developer.android.com/reference/android/content/Context.html` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#context()` |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DeviceParametersBuilders.DeviceParameters` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#deviceConfiguration()` |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#hasProtoLayoutScope()` Checks whether `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` exists in this `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#protoLayoutScope()` The `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` for the Tile service, that is responsible for handling internal details of ProtoLayout layouts and Tiles and can be used to create image resources with automatic resources registration. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#shapes()` Shapes theme used within this scope and its components. |
| ### Extension functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)( width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, spacing: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, content: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonGroupScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` ProtoLayout Material3 component-layout that places its children in a horizontal sequence. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, labelContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, avatarContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, secondaryLabelContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors, style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/AvatarButtonStyle, horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding )` Opinionated ProtoLayout Material3 pill shape avatar button that offers up to three slots to take content representing vertically stacked label and secondary label, and an image (avatar) next to it. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, labelContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, secondaryLabelContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, iconContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors, backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonStyle, horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding )` Opinionated ProtoLayout Material3 pill shape button that offers up to three slots to take content representing vertically stacked label and secondary label, and an icon next to it. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, labelContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, iconContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors, horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding )` Opinionated ProtoLayout Material3 compact button that offers up to two slots to take horizontally stacked content representing an icon and text next to it. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, iconContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors, style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/IconButtonStyle, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding )` Opinionated ProtoLayout Material3 icon button that offers a single slot to take content representing icon, for example `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)`. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).imageButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, backgroundContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension )` ProtoLayout Material3 clickable image button that doesn't offer additional slots, only image (for example `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` as a background). |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, labelContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors, style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/TextButtonStyle, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding )` Opinionated ProtoLayout Material3 text button that offers a single slot to take content representing short text, for example `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).appCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.AppCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, avatar: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, label: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, time: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors, backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/AppCardStyle, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding )` Opinionated ProtoLayout Material3 app card that offers up to 5 slots, usually text based. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).card(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Padding,kotlin.Function1)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding, content: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement )` ProtoLayout Material3 clickable component card that offers a single slot to take any content. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).graphicDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,androidx.wear.protolayout.material3.GraphicDataCardStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, graphic: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors, style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/GraphicDataCardStyle, horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding )` Opinionated ProtoLayout Material3 graphic data card that offers a slot for graphic data such as progress indicator and up to 2 vertically stacked slots, usually for textual description. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, secondaryIcon: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors, backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle, titleContentPlacement: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/TitleContentPlacementInDataCard, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding )` Opinionated ProtoLayout Material3 data card that offers up to 3 vertically stacked slots, usually text or numeral based, with icon. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).textDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, secondaryText: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors, backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding )` Opinionated ProtoLayout Material3 data card that offers up to 3 vertically stacked slots, usually text or numeral based. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).titleCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.TitleCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding,kotlin.Int)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, time: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension, shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors, backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/TitleCardStyle, contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding, horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` Opinionated ProtoLayout Material3 title card that offers 1 to 3 slots, usually text based. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.Box` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)( staticProgress: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, dynamicProgress: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicFloat?, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, startAngleDegrees: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, endAngleDegrees: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, strokeWidth: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, gapSize: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ProgressIndicatorColors, size: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension )` ProtoLayout Material3 design circular progress indicator. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.Box` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)( segmentCount: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, staticProgress: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, dynamicProgress: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicFloat?, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, startAngleDegrees: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, endAngleDegrees: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, strokeWidth: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, gapSize: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ProgressIndicatorColors, size: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension )` ProtoLayout Material3 design segmented circular progress indicator. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).iconEdgeButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors, iconContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement )` ProtoLayout Material3 component edge button that offers a single slot to take an icon or similar round, small content. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).textEdgeButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1)( onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors, labelContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement )` ProtoLayout Material3 component edge button that offers a single slot to take a text or similar long and wide content. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.[icon](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).icon(kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor))( protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, tintColor: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor )` **This function is deprecated.** Use icon(ImageResource, String, ImageDimension, ImageDimension, LayoutColor) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)( resource: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ResourceBuilders.ImageResource, protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, tintColor: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor )` Returns the icon components with the defined style which will be automatically registered as a resource. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.[avatarImage](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).avatarImage(kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int))( protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, contentScaleMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` **This function is deprecated.** Use avatarImage(ImageResource, String, ImageDimension, ImageDimension, LayoutModifier, Int) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).avatarImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int)( resource: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ResourceBuilders.ImageResource, protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, contentScaleMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` Returns the avatar image with the defined style which will be automatically registered as a resource. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.[backgroundImage](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int))( protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, overlayColor: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor?, contentScaleMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` **This function is deprecated.** Use backgroundImage(ImageResource, String, LayoutModifier, ImageDimension, ImageDimension, LayoutColor?, Int) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)( resource: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ResourceBuilders.ImageResource, protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension, overlayColor: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor?, contentScaleMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` Returns the image background with the defined style which will be automatically registered as a resource. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)( mainSlot: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement, titleSlot: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, bottomSlot: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, labelForBottomSlot: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)?, onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable?, margins: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PrimaryLayoutMargins )` 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. |
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)( text: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutString, modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier, typography: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, color: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor, italic: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, underline: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, scalable: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, maxLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, alignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, overflow: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, @https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/RequiresSchemaVersion(major = 1, minor = 400) settings: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html, incrementsForTypographySize: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html )` ProtoLayout component that represents text object holding any information. |
## Public properties
### colorScheme
Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0)
```
val colorScheme: ColorScheme
```
Color Scheme used within this scope and its components.
### context
Added in [1.4.2](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.4.2)
```
val context: Context
```
### deviceConfiguration
Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0)
```
val deviceConfiguration: DeviceParametersBuilders.DeviceParameters
```
### hasProtoLayoutScope
Added in [1.4.2](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.4.2)
```
val hasProtoLayoutScope: Boolean
```
Checks whether `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` exists in this `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
It is guaranteed that exists when the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` is created with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#materialScopeWithResources(android.content.Context,androidx.wear.protolayout.ProtoLayoutScope,androidx.wear.protolayout.DeviceParametersBuilders.DeviceParameters,kotlin.Boolean,androidx.wear.protolayout.material3.ColorScheme,kotlin.Function1)`.
### protoLayoutScope
Added in [1.4.2](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.4.2)
```
val protoLayoutScope: ProtoLayoutScope
```
The `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` for the Tile service, that is responsible for handling internal details of ProtoLayout layouts and Tiles and can be used to create image resources with automatic resources registration.
This field can safely be used when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` is created with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#materialScopeWithResources(android.content.Context,androidx.wear.protolayout.ProtoLayoutScope,androidx.wear.protolayout.DeviceParametersBuilders.DeviceParameters,kotlin.Boolean,androidx.wear.protolayout.material3.ColorScheme,kotlin.Function1)`.
| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | When the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` within this `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` is null, which can happen if `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#materialScope(android.content.Context,androidx.wear.protolayout.DeviceParametersBuilders.DeviceParameters,kotlin.Boolean,androidx.wear.protolayout.material3.ColorScheme,kotlin.Function1)` is used to create it. It is guaranteed that this method will return value and not throw when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` is created with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#materialScopeWithResources(android.content.Context,androidx.wear.protolayout.ProtoLayoutScope,androidx.wear.protolayout.DeviceParametersBuilders.DeviceParameters,kotlin.Boolean,androidx.wear.protolayout.material3.ColorScheme,kotlin.Function1)`. In other cases, presence of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` can be checked with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#hasProtoLayoutScope()`. |
### shapes
Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0)
```
val shapes: Shapes
```
Shapes theme used within this scope and its components.
## Extension functions
### MaterialScope.buttonGroup
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/ButtonGroup.kt+function: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 `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)`) and their proportion should be either equal or weight based. However the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)` 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 `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)` with more than one row can be created by using multiple `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.Spacer`s inside a `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.Column`:
```kotlin
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.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.DimensionBuilders.weight
import androidx.wear.protolayout.material3.CardDefaults.filledTonalCardColors
import androidx.wear.protolayout.material3.CardDefaults.filledVariantCardColors
import androidx.wear.protolayout.material3.DataCardStyle.Companion.extraLargeDataCardStyle
import androidx.wear.protolayout.material3.DataCardStyle.Companion.largeCompactDataCardStyle
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconDataCard
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textDataCard
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
buttonGroup {
buttonGroupItem {
textDataCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Data Card with text"),
width = weight(1f),
height = expand(),
colors = filledTonalCardColors(),
style = extraLargeDataCardStyle(),
title = { this.text("1km".layoutString) },
content = { this.text("Run".layoutString) },
secondaryText = { this.text("Nice!".layoutString) },
)
}
buttonGroupItem {
iconDataCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Data Card with icon"),
width = weight(1f),
height = expand(),
colors = filledTonalCardColors(),
style = extraLargeDataCardStyle(),
title = { this.text("2km".layoutString) },
secondaryIcon = { icon("id") },
content = { this.text("Run".layoutString) },
)
}
buttonGroupItem {
textDataCard(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Compact Data Card without icon or secondary label"
),
width = weight(3f),
height = expand(),
colors = filledVariantCardColors(),
style = largeCompactDataCardStyle(),
title = { this.text("10:30".layoutString) },
content = { this.text("PM".layoutString) },
)
}
}
}
)
}
```
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textButton
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
buttonGroup {
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
iconContent = { icon("id1") },
)
}
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
iconContent = { icon("id2") },
)
}
buttonGroupItem {
textButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
labelContent = { text("Dec".layoutString) },
)
}
}
}
)
}
```
| Parameters |
|---|---|
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = expand()` | The width of this button group |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = expand()` | The height of this button group |
| `spacing: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = DEFAULT_SPACER_SIZE_DP` | The amount of spacing between buttons |
| `content: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonGroupScope.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The content for each child. The UX guidance is to use no more than 3 elements within a this button group. |
### MaterialScope.avatarButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:avatarButton)
```
fun MaterialScope.avatarButton(
onClick: ModifiersBuilders.Clickable,
labelContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
avatarContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
secondaryLabelContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = shapes.full,
colors: ButtonColors = filledButtonColors(),
style: AvatarButtonStyle = defaultAvatarButtonStyle(),
horizontalAlignment: Int = HORIZONTAL_ALIGN_START,
contentPadding: ModifiersBuilders.Padding = style.innerVerticalPadding
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 pill shape avatar button that offers up to three slots to take content representing vertically stacked label and secondary label, and an image (avatar) next to it.
Difference from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is that this one takes an image instead of an icon and spaces the content proportionally, so that edge of the button nicely hugs the avatar image.
The button's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.material3.avatarButton
import androidx.wear.protolayout.material3.avatarImage
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
avatarButton(
onClick = clickable(),
modifier = LayoutModifier.contentDescription("Pill button"),
avatarContent = { avatarImage("id") },
labelContent = { text("Primary label".layoutString) },
secondaryLabelContent = { text("Secondary label".layoutString) },
)
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `labelContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
| `avatarContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | The avatar slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int)` with the resource ID. Width and height of this element should be set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()`. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `secondaryLabelContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = shapes.full` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors = filledButtonColors()` | The colors used for this button. If not set, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/AvatarButtonStyle = defaultAvatarButtonStyle()` | The style which provides the attribute values required for constructing this pill shape button and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = HORIZONTAL_ALIGN_START` | The horizontal placement of the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)`. This should be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()` to place the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.AvatarButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` on the start side of the button, or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_END()` to place in on the end side. `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_CENTER()` will be ignored and replaced with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()`. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = style.innerVerticalPadding` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. Only vertical values would be used, as horizontally elements are spaced out proportionally to the buttons width. |
### MaterialScope.button
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:button)
```
fun MaterialScope.button(
onClick: ModifiersBuilders.Clickable,
labelContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
secondaryLabelContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
iconContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
width: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = shapes.full,
colors: ButtonColors = filledButtonColors(),
backgroundContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
style: ButtonStyle = defaultButtonStyle(),
horizontalAlignment: Int = if (iconContent == null && secondaryLabelContent == null) {
HORIZONTAL_ALIGN_CENTER
} else {
HORIZONTAL_ALIGN_START
},
contentPadding: ModifiersBuilders.Padding = style.innerPadding
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 pill shape button that offers up to three slots to take content representing vertically stacked label and secondary label, and an icon next to it.
The button's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
button(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Pill shape button"),
width = expand(),
height = expand(),
labelContent = { text("First label".layoutString) },
secondaryLabelContent = { text("Second label".layoutString) },
iconContent = { icon("id") },
)
}
)
}
```
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.LayoutElementBuilders.Box
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
// Button with custom content inside
button(
onClick = clickable,
modifier =
LayoutModifier.contentDescription("Big button with image background")
.background(colorScheme.primary),
width = expand(),
height = expand(),
labelContent = {
// This can be further built.
Box.Builder().build()
},
)
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `labelContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `secondaryLabelContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. |
| `iconContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The icon slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)` with the resource ID. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = shapes.full` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors = filledButtonColors()` | The colors used for this button. If not set, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The background object to be used behind the content in the button. It is recommended to use the default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` with the content. It can be combined with the specified `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors#containerColor()` behind it. |
| `style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonStyle = defaultButtonStyle()` | The style which provides the attribute values required for constructing this pill shape button and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = if (iconContent == null && secondaryLabelContent == null) { HORIZONTAL_ALIGN_CENTER } else { HORIZONTAL_ALIGN_START }` | The horizontal placement of the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` content. If `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is present, this should be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()`. Defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_CENTER()` if only `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).button(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1,androidx.wear.protolayout.material3.ButtonStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is present, otherwise it default to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()`. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = style.innerPadding` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. |
### MaterialScope.compactButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:compactButton)
```
fun MaterialScope.compactButton(
onClick: ModifiersBuilders.Clickable,
modifier: LayoutModifier = LayoutModifier,
labelContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
iconContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
width: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = shapes.full,
colors: ButtonColors = filledButtonColors(),
horizontalAlignment: Int = if (iconContent != null && labelContent != null) {
HORIZONTAL_ALIGN_START
} else {
HORIZONTAL_ALIGN_CENTER
},
contentPadding: ModifiersBuilders.Padding = Padding.Builder()
.setStart(COMPACT_BUTTON_DEFAULT_CONTENT_PADDING_DP.toDp())
.setEnd(COMPACT_BUTTON_DEFAULT_CONTENT_PADDING_DP.toDp())
.build()
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 compact button that offers up to two slots to take horizontally stacked content representing an icon and text next to it.
The button's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.compactButton
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
compactButton(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Compact button"),
width = expand(),
labelContent = { text("Action".layoutString) },
iconContent = { icon("id") },
)
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `labelContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` with only the text data parameter. |
| `iconContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The icon slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)` with the resource ID. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = shapes.full` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors = filledButtonColors()` | The colors used for this button. If not set, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose colors from the same role to ensure accessibility with sufficient color contrast. |
| `horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = if (iconContent != null && labelContent != null) { HORIZONTAL_ALIGN_START } else { HORIZONTAL_ALIGN_CENTER }` | The horizontal placement of the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` content. If both are present, this should be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_END()` (in which case `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` would be on the start or end side, respectively). Defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_CENTER()` if only `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).compactButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is present, otherwise it default to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()`. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = Padding.Builder() .setStart(COMPACT_BUTTON_DEFAULT_CONTENT_PADDING_DP.toDp()) .setEnd(COMPACT_BUTTON_DEFAULT_CONTENT_PADDING_DP.toDp()) .build()` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. |
### MaterialScope.iconButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:iconButton)
```
fun MaterialScope.iconButton(
onClick: ModifiersBuilders.Clickable,
iconContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
width: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = shapes.full,
colors: ButtonColors = filledButtonColors(),
style: IconButtonStyle = defaultIconButtonStyle(),
contentPadding: ModifiersBuilders.Padding = style.innerPadding
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 icon button that offers a single slot to take content representing icon, for example `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)`.
The button is usually either a circular shape with the same `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)`, or highly recommended stadium shape occupying available space with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)`, usually arranged with the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)`.
The button's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textButton
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
buttonGroup {
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
iconContent = { icon("id1") },
)
}
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
iconContent = { icon("id2") },
)
}
buttonGroupItem {
textButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
labelContent = { text("Dec".layoutString) },
)
}
}
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `iconContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/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 `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)` with the resource ID. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = shapes.full` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.IconButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors = filledButtonColors()` | The colors used for this button. If not set, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/IconButtonStyle = defaultIconButtonStyle()` | The style which provides the attribute values required for constructing this icon button and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = style.innerPadding` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. |
### MaterialScope.imageButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:imageButton)
```
fun MaterialScope.imageButton(
onClick: ModifiersBuilders.Clickable,
backgroundContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
width: DimensionBuilders.ContainerDimension = IMAGE_BUTTON_DEFAULT_SIZE_DP.toDp(),
height: DimensionBuilders.ContainerDimension = IMAGE_BUTTON_DEFAULT_SIZE_DP.toDp()
): LayoutElementBuilders.LayoutElement
```
ProtoLayout Material3 clickable image button that doesn't offer additional slots, only image (for example `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` as a background).
The button is usually stadium or circle shaped with fully rounded corners by default. It is highly recommended to set its width and height to fill the available space, by `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` for optimal experience across different screen sizes, and use `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)` to arrange them.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.backgroundImage
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.imageButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
imageButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription("Big button with image background"),
width = expand(),
height = expand(),
backgroundContent = { backgroundImage(protoLayoutResourceId = "id") },
)
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `backgroundContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | The background object to be used behind the content in the button. It is recommended to use the default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` with the content and optional overlay. It can be combined with the specified `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).background(androidx.wear.protolayout.types.LayoutColor)` behind it. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. If `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).background(androidx.wear.protolayout.types.LayoutColor)` modifier is used and the the background image is also specified, the image will be laid out on top of this color. In case of the fully opaque background image, then the background color will not be shown. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = IMAGE_BUTTON_DEFAULT_SIZE_DP.toDp()` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = IMAGE_BUTTON_DEFAULT_SIZE_DP.toDp()` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
### MaterialScope.textButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Button.kt+function:textButton)
```
fun MaterialScope.textButton(
onClick: ModifiersBuilders.Clickable,
labelContent: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
width: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = shapes.full,
colors: ButtonColors = filledButtonColors(),
style: TextButtonStyle = defaultTextButtonStyle(),
contentPadding: ModifiersBuilders.Padding = style.innerPadding
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 text button that offers a single slot to take content representing short text, for example `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`.
The button is usually either a circular shape with the same `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)`, or highly recommended stadium shape occupying available space with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)`, usually arranged with the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)`.
The button's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textButton
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
buttonGroup {
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
iconContent = { icon("id1") },
)
}
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
iconContent = { icon("id2") },
)
}
buttonGroupItem {
textButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
labelContent = { text("Dec".layoutString) },
)
}
}
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `labelContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. This should be small text, usually up to 3 characters text. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The width of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The height of this button. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = shapes.full` | Defines the button's shape, in other words the corner radius for this button. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.ButtonColors,androidx.wear.protolayout.material3.TextButtonStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors = filledButtonColors()` | The colors used for this button. If not set, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/TextButtonStyle = defaultTextButtonStyle()` | The style which provides the attribute values required for constructing this text button and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = style.innerPadding` | The inner padding used to prevent inner content from being too close to the button's edge. It's highly recommended to keep the default. |
### MaterialScope.appCard
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Card.kt+function:appCard)
```
fun MaterialScope.appCard(
onClick: ModifiersBuilders.Clickable,
title: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
content: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
avatar: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
label: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
time: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = if (deviceConfiguration.screenWidthDp.isBreakpoint()) {
shapes.extraLarge
} else {
shapes.large
},
colors: CardColors = filledCardColors(),
backgroundContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
style: AppCardStyle = defaultAppCardStyle(),
contentPadding: ModifiersBuilders.Padding = style.innerPadding
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 app card that offers up to 5 slots, usually text based.
Those are vertically stacked title and content, and additional side slot for a time.
The first row of the card has three slots:
1. a small optional image, such as `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int)`
2. label, which is expected to be a short `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`
3. time, end aligned.
The second row shows a title, this is expected to be a single row of start aligned `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`.
The rest of the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).appCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.AppCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` contains the content which should be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`.
The card's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).appCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.AppCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.AppCardStyle
import androidx.wear.protolayout.material3.CardDefaults.filledTonalCardColors
import androidx.wear.protolayout.material3.appCard
import androidx.wear.protolayout.material3.card
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
appCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("App Card"),
height = expand(),
colors = filledTonalCardColors(),
style = AppCardStyle.largeAppCardStyle(),
title = { text("This is title of the app card".layoutString) },
time = { text("NOW".layoutString) },
label = { text("Label".layoutString) },
content = { text("Content of the Card!".layoutString) },
)
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the card is clicked it will fire the associated action. |
| `title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | A slot for displaying the title of the card, expected to be one line of text. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#titleColor()` color by default. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The optional body content of the card. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#contentColor()` color by default. |
| `avatar: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | An optional slot in header for displaying small image, such as `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).avatarImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int)`. |
| `label: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | An optional slot in header for displaying short, label text. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#labelColor()` color by default. |
| `time: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | An optional slot for displaying the time relevant to the contents of the card, expected to be a short piece of text. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#timeColor()` color by default. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The height of this card. It's highly recommended to leave this with default value as `wrap` if there's only 1 card on the screen. If there are two cards, it is highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` and use the smaller styles. |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = if (deviceConfiguration.screenWidthDp.isBreakpoint()) { shapes.extraLarge } else { shapes.large }` | Defines the card's shape, in other words the corner radius for this card. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).appCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.AppCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors = filledCardColors()` | The colors to be used for a background and inner content of this card. If the background image is also specified, the image will be laid out on top of the background color. In case of the fully opaque background image, then the background color will not be shown. Specified colors can be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledCardColors()` for high emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantCardColors()` for high/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalCardColors()` for low/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).imageBackgroundCardColors()` for card with image as a background or custom built `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors`. |
| `backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The background object to be used behind the content in the card. It is recommended to use the default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` with the content. It can be combined with the specified `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).appCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.AppCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)`'s background color behind it. |
| `style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/AppCardStyle = defaultAppCardStyle()` | The style which provides the attribute values required for constructing this title card and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = style.innerPadding` | 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. |
### MaterialScope.card
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Card.kt+function:card)
```
fun MaterialScope.card(
onClick: ModifiersBuilders.Clickable,
modifier: LayoutModifier = LayoutModifier,
width: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
backgroundContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
contentPadding: ModifiersBuilders.Padding = padding(DEFAULT_CONTENT_PADDING),
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 `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` for optimal experience across different screen sizes.
It can be used for displaying any clickable container with additional data, text or graphics.
It is highly recommended to set its height to fill the available space, with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` for optimal experience across different screen sizes.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
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.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
card(
onClick = clickable,
modifier =
LayoutModifier.contentDescription("Card with image background")
.clickable(id = "card"),
width = expand(),
height = expand(),
backgroundContent = { backgroundImage(protoLayoutResourceId = "id") },
) {
text("Content of the Card!".layoutString)
}
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the card is clicked it will fire the associated action. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. If `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).background(androidx.wear.protolayout.types.LayoutColor)` modifier is used and the the background image is also specified, the image will be laid out on top of this color. In case of the fully opaque background image, then the background color will not be shown. If `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).clip(kotlin.Float)` modifier is used to change the shape of the card to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if changing to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The width of this card. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The height of this card. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` |
| `backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The background object to be used behind the content in the card. It is recommended to use the default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` with the content. It can be combined with the specified `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).background(androidx.wear.protolayout.types.LayoutColor)` behind it. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = padding(DEFAULT_CONTENT_PADDING)` | 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: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | The inner content to be put inside of this card. |
### MaterialScope.graphicDataCard
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Card.kt+function:graphicDataCard)
```
fun MaterialScope.graphicDataCard(
onClick: ModifiersBuilders.Clickable,
graphic: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
title: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
content: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = shapes.full,
colors: CardColors = filledCardColors(),
style: GraphicDataCardStyle = defaultGraphicDataCardStyle(),
horizontalAlignment: Int = HORIZONTAL_ALIGN_START,
contentPadding: ModifiersBuilders.Padding = style.innerPadding
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 graphic data card that offers a slot for graphic data such as progress indicator and up to 2 vertically stacked slots, usually for textual description.
It is highly recommended to set its height to fill the available space, with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` for optimal experience across different screen sizes.
The card's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).graphicDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,androidx.wear.protolayout.material3.GraphicDataCardStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.CardDefaults.filledVariantCardColors
import androidx.wear.protolayout.material3.CircularProgressIndicatorDefaults.filledTonalProgressIndicatorColors
import androidx.wear.protolayout.material3.GraphicDataCardStyle.Companion.largeGraphicDataCardStyle
import androidx.wear.protolayout.material3.graphicDataCard
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.segmentedCircularProgressIndicator
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
graphicDataCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Data Card with graphic"),
height = expand(),
colors = filledVariantCardColors(),
style = largeGraphicDataCardStyle(),
title = { text("1,234".layoutString) },
content = { icon("steps") },
graphic = {
segmentedCircularProgressIndicator(
segmentCount = 5,
staticProgress = 0.5F,
colors = filledTonalProgressIndicatorColors(),
)
},
)
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the card is clicked it will fire the associated action. |
| `graphic: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | A slot for displaying graphic data, such as `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)`. A progress indicator will have its default color matching to the card when the card has one of the predefined colors in CardDefaults. A helper `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/GraphicDataCardDefaults#(androidx.wear.protolayout.material3.MaterialScope).constructGraphic(kotlin.Function1,kotlin.Function1,kotlin.Float)` is also provided to construct a graphic content with a progress indicator and an icon, where the icon will be placed in the center with proportional size and color matching to the progress indicator. |
| `title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | A slot for displaying the title of the card, expected to be one line of text. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#titleColor()` color by default. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The optional body content of the card. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#contentColor()` color by default. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The width of this card. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` for the most optimal experience across different screen sizes. |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = shapes.full` | Defines the card's shape, in other words the corner radius for this card. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).graphicDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,androidx.wear.protolayout.material3.GraphicDataCardStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors = filledCardColors()` | The colors to be used for a background and inner content of this card. Specified colors can be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledCardColors()` for high emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantCardColors()` for high/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalCardColors()` for low/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).imageBackgroundCardColors()` for card with image as a background or custom built `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors`. |
| `style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/GraphicDataCardStyle = defaultGraphicDataCardStyle()` | The style which provides the attribute values required for constructing this data card and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. It is highly recommended to use one of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/GraphicDataCardStyle#defaultGraphicDataCardStyle()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/GraphicDataCardStyle#largeGraphicDataCardStyle()`. |
| `horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = HORIZONTAL_ALIGN_START` | The horizontal placement of the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).graphicDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,androidx.wear.protolayout.material3.GraphicDataCardStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` content. This can be either `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_START()` (when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).graphicDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,androidx.wear.protolayout.material3.GraphicDataCardStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` is on the start side), or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders#HORIZONTAL_ALIGN_END()` (when it is on the end side). |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = style.innerPadding` | 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. |
### MaterialScope.iconDataCard
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Card.kt+function:iconDataCard)
```
fun MaterialScope.iconDataCard(
onClick: ModifiersBuilders.Clickable,
title: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
content: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
secondaryIcon: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
width: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = shapes.large,
colors: CardColors = filledCardColors(),
backgroundContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
style: DataCardStyle = if (secondaryIcon == null) {
defaultCompactDataCardStyle()
} else {
defaultDataCardStyle()
},
titleContentPlacement: TitleContentPlacementInDataCard = TitleContentPlacementInDataCard.Bottom,
contentPadding: ModifiersBuilders.Padding = style.innerPadding
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 data card that offers up to 3 vertically stacked slots, usually text or numeral based, with icon.
Slots can have multiple placements, depending on their presence and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)`:
- If `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` are set, it will be placed first when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/TitleContentPlacementInDataCard#Bottom()`, or last if `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/TitleContentPlacementInDataCard#Top()`.
- If `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` is not set, this `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` is considered as `compact` data card, with title and content only.
This card works well in `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)` with cards `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()`.
The card's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.DimensionBuilders.weight
import androidx.wear.protolayout.material3.CardDefaults.filledTonalCardColors
import androidx.wear.protolayout.material3.CardDefaults.filledVariantCardColors
import androidx.wear.protolayout.material3.DataCardStyle.Companion.extraLargeDataCardStyle
import androidx.wear.protolayout.material3.DataCardStyle.Companion.largeCompactDataCardStyle
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconDataCard
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textDataCard
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
buttonGroup {
buttonGroupItem {
textDataCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Data Card with text"),
width = weight(1f),
height = expand(),
colors = filledTonalCardColors(),
style = extraLargeDataCardStyle(),
title = { this.text("1km".layoutString) },
content = { this.text("Run".layoutString) },
secondaryText = { this.text("Nice!".layoutString) },
)
}
buttonGroupItem {
iconDataCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Data Card with icon"),
width = weight(1f),
height = expand(),
colors = filledTonalCardColors(),
style = extraLargeDataCardStyle(),
title = { this.text("2km".layoutString) },
secondaryIcon = { icon("id") },
content = { this.text("Run".layoutString) },
)
}
buttonGroupItem {
textDataCard(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Compact Data Card without icon or secondary label"
),
width = weight(3f),
height = expand(),
colors = filledVariantCardColors(),
style = largeCompactDataCardStyle(),
title = { this.text("10:30".layoutString) },
content = { this.text("PM".layoutString) },
)
}
}
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the card is clicked it will fire the associated action. |
| `title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | A slot for displaying the title of the card, expected to be one line of text. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#titleColor()` color by default. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The optional body content of the card. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#contentColor()` color by default. |
| `secondaryIcon: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | An optional slot for displaying small icon, such as `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)`. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#secondaryIconColor()` tint color by default. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The width of this card. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` for the most optimal experience across different screen sizes. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The height of this card. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` for the most optimal experience across different screen sizes. |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = shapes.large` | Defines the card's shape, in other words the corner radius for this card. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors = filledCardColors()` | The colors to be used for a background and inner content of this card. If the background image is also specified, the image will be laid out on top of the background color. In case of the fully opaque background image, then the background color will not be shown. Specified colors can be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledCardColors()` for high emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantCardColors()` for high/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalCardColors()` for low/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).imageBackgroundCardColors()` for card with image as a background or custom built `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors`. |
| `backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The background object to be used behind the content in the card. It is recommended to use the default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` with the content. It can be combined with the specified `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)`'s background color behind it. |
| `style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle = if (secondaryIcon == null) { defaultCompactDataCardStyle() } else { defaultDataCardStyle() }` | The style which provides the attribute values required for constructing this data card and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. It is highly recommended to use one of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#smallDataCardStyle()`, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#defaultDataCardStyle()`, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#largeDataCardStyle()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#extraLargeDataCardStyle()` styles when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)`is present. If it's not present, it's highly recommended to use `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#smallCompactDataCardStyle()`, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#defaultCompactDataCardStyle()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#largeCompactDataCardStyle()`. |
| `titleContentPlacement: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/TitleContentPlacementInDataCard = TitleContentPlacementInDataCard.Bottom` | The placement of the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)` slots, relative to the given `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.material3.TitleContentPlacementInDataCard,androidx.wear.protolayout.ModifiersBuilders.Padding)`. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = style.innerPadding` | 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. |
### MaterialScope.textDataCard
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Card.kt+function:textDataCard)
```
fun MaterialScope.textDataCard(
onClick: ModifiersBuilders.Clickable,
title: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
content: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
secondaryText: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
width: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = shapes.large,
colors: CardColors = filledCardColors(),
backgroundContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
style: DataCardStyle = if (secondaryText == null) {
defaultCompactDataCardStyle()
} else {
defaultDataCardStyle()
},
contentPadding: ModifiersBuilders.Padding = style.innerPadding
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 data card that offers up to 3 vertically stacked slots, usually text or numeral based.
This card works well in `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)` with cards `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()`.
The card's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.DimensionBuilders.weight
import androidx.wear.protolayout.material3.CardDefaults.filledTonalCardColors
import androidx.wear.protolayout.material3.CardDefaults.filledVariantCardColors
import androidx.wear.protolayout.material3.DataCardStyle.Companion.extraLargeDataCardStyle
import androidx.wear.protolayout.material3.DataCardStyle.Companion.largeCompactDataCardStyle
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconDataCard
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textDataCard
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
buttonGroup {
buttonGroupItem {
textDataCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Data Card with text"),
width = weight(1f),
height = expand(),
colors = filledTonalCardColors(),
style = extraLargeDataCardStyle(),
title = { this.text("1km".layoutString) },
content = { this.text("Run".layoutString) },
secondaryText = { this.text("Nice!".layoutString) },
)
}
buttonGroupItem {
iconDataCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Data Card with icon"),
width = weight(1f),
height = expand(),
colors = filledTonalCardColors(),
style = extraLargeDataCardStyle(),
title = { this.text("2km".layoutString) },
secondaryIcon = { icon("id") },
content = { this.text("Run".layoutString) },
)
}
buttonGroupItem {
textDataCard(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Compact Data Card without icon or secondary label"
),
width = weight(3f),
height = expand(),
colors = filledVariantCardColors(),
style = largeCompactDataCardStyle(),
title = { this.text("10:30".layoutString) },
content = { this.text("PM".layoutString) },
)
}
}
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the card is clicked it will fire the associated action. |
| `title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | A slot for displaying the title of the card, expected to be one line of text. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#titleColor()` color by default. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The optional body content of the card. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#contentColor()` color by default. |
| `secondaryText: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | An optional slot for displaying short, secondary text. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#secondaryTextColor()` color by default. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The width of this card. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)` for the most optimal experience across different screen sizes. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The height of this card. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` for the most optimal experience across different screen sizes. |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = shapes.large` | Defines the card's shape, in other words the corner radius for this card. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors = filledCardColors()` | The colors to be used for a background and inner content of this card. If the background image is also specified, the image will be laid out on top of the background color. In case of the fully opaque background image, then the background color will not be shown. Specified colors can be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledCardColors()` for high emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantCardColors()` for high/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalCardColors()` for low/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).imageBackgroundCardColors()` for card with image as a background or custom built `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors`. |
| `backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The background object to be used behind the content in the card. It is recommended to use the default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` with the content. It can be combined with the specified `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)`'s background color behind it. |
| `style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle = if (secondaryText == null) { defaultCompactDataCardStyle() } else { defaultDataCardStyle() }` | The style which provides the attribute values required for constructing this data card and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. It is highly recommended to use one of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#smallDataCardStyle()`, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#defaultDataCardStyle()`, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#largeDataCardStyle()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#extraLargeDataCardStyle()` styles when either `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.DataCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` are present. If they are not present, it's highly recommended to use `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#smallCompactDataCardStyle()`, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#defaultCompactDataCardStyle()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/DataCardStyle#largeCompactDataCardStyle()`. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = style.innerPadding` | 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. |
### MaterialScope.titleCard
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Card.kt+function:titleCard)
```
fun MaterialScope.titleCard(
onClick: ModifiersBuilders.Clickable,
title: MaterialScope.() -> LayoutElementBuilders.LayoutElement,
modifier: LayoutModifier = LayoutModifier,
content: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
time: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
height: DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension(),
shape: ModifiersBuilders.Corner = if (deviceConfiguration.screenWidthDp.isBreakpoint()) {
shapes.extraLarge
} else {
shapes.large
},
colors: CardColors = filledCardColors(),
backgroundContent: (MaterialScope.() -> LayoutElementBuilders.LayoutElement)? = null,
style: TitleCardStyle = defaultTitleCardStyle(),
contentPadding: ModifiersBuilders.Padding = style.innerPadding,
horizontalAlignment: Int = if (time == null) HORIZONTAL_ALIGN_CENTER else HORIZONTAL_ALIGN_START
): LayoutElementBuilders.LayoutElement
```
Opinionated ProtoLayout Material3 title card that offers 1 to 3 slots, usually text based.
Those are vertically stacked title and content, and additional side slot for a time.
It is highly recommended to set its height to fill the available space, with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` for optimal experience across different screen sizes.
The card's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).titleCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.TitleCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding,kotlin.Int)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.CardDefaults.filledVariantCardColors
import androidx.wear.protolayout.material3.TitleCardStyle.Companion.largeTitleCardStyle
import androidx.wear.protolayout.material3.card
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.titleCard
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
titleCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Title Card"),
height = expand(),
colors = filledVariantCardColors(),
style = largeTitleCardStyle(),
title = { text("This is title of the title card".layoutString) },
time = { text("NOW".layoutString) },
content = { text("Content of the Card!".layoutString) },
)
}
)
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the card is clicked it will fire the associated action. |
| `title: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement` | A slot for displaying the title of the card, expected to be one or two lines of text. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#titleColor()` color by default. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `content: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The optional body content of the card. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#contentColor()` color by default. |
| `time: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | An optional slot for displaying the time relevant to the contents of the card, expected to be a short piece of text. Uses `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors#timeColor()` color by default. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = wrapWithMinTapTargetDimension()` | The height of this card. It's highly recommended to set this to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)`. |
| `shape: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Corner = if (deviceConfiguration.screenWidthDp.isBreakpoint()) { shapes.extraLarge } else { shapes.large }` | Defines the card's shape, in other words the corner radius for this card. If changing these to radius smaller than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#medium()`, it is important to adjusts the margins of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` used to accommodate for more space, for example by using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).maxPrimaryLayoutMargins()`. Or, if the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).titleCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.TitleCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding,kotlin.Int)` is set to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Shapes#full()`, using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PredefinedPrimaryLayoutMargins#(androidx.wear.protolayout.material3.MaterialScope).minPrimaryLayoutMargins()` can be considered. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors = filledCardColors()` | The colors to be used for a background and inner content of this card. If the background image is also specified, the image will be laid out on top of the background color. In case of the fully opaque background image, then the background color will not be shown. Specified colors can be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledCardColors()` for high emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantCardColors()` for high/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalCardColors()` for low/medium emphasis card, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardDefaults#(androidx.wear.protolayout.material3.MaterialScope).imageBackgroundCardColors()` for card with image as a background or custom built `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CardColors`. |
| `backgroundContent: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The background object to be used behind the content in the card. It is recommended to use the default styling that is automatically provided by only calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` with the content. It can be combined with the specified `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).titleCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.TitleCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding,kotlin.Int)`'s background color behind it. |
| `style: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/TitleCardStyle = defaultTitleCardStyle()` | The style which provides the attribute values required for constructing this title card and its inner content. It also provides default style for the inner content, that can be overridden by each content slot. |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Padding = style.innerPadding` | 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. |
| `horizontalAlignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = if (time == null) HORIZONTAL_ALIGN_CENTER else HORIZONTAL_ALIGN_START` | The horizontal alignment of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).titleCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.TitleCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding,kotlin.Int)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).titleCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.TitleCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding,kotlin.Int)`. Default to centered when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).titleCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.TitleCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding,kotlin.Int)` is not present. When time is present, defaults to start aligned, which is highly recommended. |
### MaterialScope.circularProgressIndicator
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/CircularProgressIndicator.kt+function:circularProgressIndicator)
```
fun MaterialScope.circularProgressIndicator(
staticProgress: Float = 0.0f,
dynamicProgress: DynamicBuilders.DynamicFloat? = null,
modifier: LayoutModifier = LayoutModifier,
startAngleDegrees: Float = 0.0f,
endAngleDegrees: Float = startAngleDegrees + 360F,
strokeWidth: @Dimension(unit = 0) Float = LARGE_STROKE_WIDTH,
gapSize: @Dimension(unit = 0) Float = calculateRecommendedGapSize(strokeWidth),
colors: ProgressIndicatorColors = defaultProgressIndicatorStyle.color ?: filledProgressIndicatorColors(),
size: DimensionBuilders.ContainerDimension = expand()
): LayoutElementBuilders.Box
```
ProtoLayout Material3 design circular progress indicator.
Note that, the proper implementation of this component requires a ProtoLayout renderer with version equal to or above 1.403. When the renderer is lower than 1.403, this component will automatically fallback to an implementation with reduced features, without support for expandable size, and start/end transition.
This component consumes 3 animation quotas when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is specified with animation by the caller. It is highly recommend to use the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CircularProgressIndicatorDefaults#recommendedAnimationSpec()` to animate the progress.
The progress indicator's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.dp
import androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat
import androidx.wear.protolayout.material3.CircularProgressIndicatorDefaults
import androidx.wear.protolayout.material3.CircularProgressIndicatorDefaults.filledVariantProgressIndicatorColors
import androidx.wear.protolayout.material3.circularProgressIndicator
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.text
materialScope(context, deviceParameters) {
circularProgressIndicator(
dynamicProgress =
DynamicFloat.animate(
0.0F,
1.1F,
CircularProgressIndicatorDefaults.recommendedAnimationSpec,
),
startAngleDegrees = 200F,
endAngleDegrees = 520F,
colors = filledVariantProgressIndicatorColors(),
size = dp(85F),
)
}
```
| Parameters |
|---|---|
| `staticProgress: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = 0.0f` | The static progress of this progress indicator where 0 represent no progress and 1 represents completion. Progress above 1 is also allowed. If `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is also set, this static value will only be used when the dynamic value cannot be evaluated. By default it equals to 0. |
| `dynamicProgress: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicFloat? = null` | The dynamic progress of this progress indicator where 0 represent no progress and 1 represents completion. Progress above 1 is also allowed. If not provided, the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is used. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `startAngleDegrees: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = 0.0f` | The starting position of the progress arc, measured clockwise in degrees from the 12 o'clock position. |
| `endAngleDegrees: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = startAngleDegrees + 360F` | The ending position of the progress arc, measured clockwise in degrees from 12 o'clock position. Its value must be bigger than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)`, otherwise an exception would be thrown. By default it equals to 'startAngleDegrees + 360'. |
| `strokeWidth: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = LARGE_STROKE_WIDTH` | The stroke width for the progress indicator. The recommended values are `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CircularProgressIndicatorDefaults#LARGE_STROKE_WIDTH()` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CircularProgressIndicatorDefaults#SMALL_STROKE_WIDTH()`. |
| `gapSize: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = calculateRecommendedGapSize(strokeWidth)` | The size in dp of the gap between the ends of the progress indicator and the track. The stroke end caps are not included in this distance. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ProgressIndicatorColors = defaultProgressIndicatorStyle.color ?: filledProgressIndicatorColors()` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ProgressIndicatorColors` that will be used to resolve the indicator and track color for this progress indicator. |
| `size: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = expand()` | The bounding box size of this progress indicator, applies to both width and height. The indicator arc and track arc are located on the largest circle that can be inscribed inside. It is highly recommended for the progress indicator in a graphics card to have its size as `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ExpandedDimensionProp`, which is the default, to fill the available space for the best result across different screen sizes. Setting `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` with a `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.WrappedDimensionProp` instance will cause failure and throws an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. |
| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | When `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is set to be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.WrappedDimensionProp` instance or the provided `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is smaller than the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)`. |
### MaterialScope.segmentedCircularProgressIndicator
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/CircularProgressIndicator.kt+function:segmentedCircularProgressIndicator)
```
fun MaterialScope.segmentedCircularProgressIndicator(
segmentCount: @IntRange(from = 1) Int,
staticProgress: Float = 0.0f,
dynamicProgress: DynamicBuilders.DynamicFloat? = null,
modifier: LayoutModifier = LayoutModifier,
startAngleDegrees: Float = 0.0f,
endAngleDegrees: Float = startAngleDegrees + 360F,
strokeWidth: @Dimension(unit = 0) Float = LARGE_STROKE_WIDTH,
gapSize: @Dimension(unit = 0) Float = calculateRecommendedGapSize(strokeWidth),
colors: ProgressIndicatorColors = defaultProgressIndicatorStyle.color ?: filledProgressIndicatorColors(),
size: DimensionBuilders.ContainerDimension = expand()
): LayoutElementBuilders.Box
```
ProtoLayout Material3 design segmented circular progress indicator.
A segmented variant of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).circularProgressIndicator(kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` that is divided into equally sized segments.
Note that, the proper implementation of this component requires a ProtoLayout renderer with version equal to or above 1.403. When the renderer is lower than 1.403, this component will automatically fallback to an implementation with reduced features, without support for multiple segments, expandable size, and start/end transition.
This component consumes 2 animation quotas when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is specified with animation by the caller. It is highly recommend to use the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CircularProgressIndicatorDefaults#recommendedAnimationSpec()` to animate the progress.
The progress indicator's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.DimensionBuilders.dp
import androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat
import androidx.wear.protolayout.material3.CircularProgressIndicatorDefaults
import androidx.wear.protolayout.material3.CircularProgressIndicatorDefaults.filledVariantProgressIndicatorColors
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.segmentedCircularProgressIndicator
import androidx.wear.protolayout.material3.text
materialScope(context, deviceParameters) {
segmentedCircularProgressIndicator(
segmentCount = 5,
dynamicProgress =
DynamicFloat.animate(
0.0F,
1.1F,
CircularProgressIndicatorDefaults.recommendedAnimationSpec,
),
startAngleDegrees = 200F,
endAngleDegrees = 520F,
colors = filledVariantProgressIndicatorColors(),
size = dp(85F),
)
}
```
| Parameters |
|---|---|
| `segmentCount: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Number of equal segments that the progress indicator should be divided into. Has to be a number greater than or equal to 1. |
| `staticProgress: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = 0.0f` | The static progress of this progress indicator where 0 represent no progress and 1 represents completion. Progress above 1 is also allowed. If `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is also set, this static value will only be used when the dynamic value cannot be evaluated. By default it equals to 0. |
| `dynamicProgress: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicFloat? = null` | The dynamic progress of this progress indicator where 0 represent no progress and 1 represents completion. Progress above 1 is also allowed. If not provided, the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is used. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `startAngleDegrees: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = 0.0f` | The starting position of the progress arc, measured clockwise in degrees from the 12 o'clock position. |
| `endAngleDegrees: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = startAngleDegrees + 360F` | The ending position of the progress arc, measured clockwise in degrees from 12 o'clock position. This value must be bigger than `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)`, otherwise an exception would be thrown. By default it equals to 'startAngleDegrees + 360'. |
| `strokeWidth: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = LARGE_STROKE_WIDTH` | The stroke width for the progress indicator. The recommended values are `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CircularProgressIndicatorDefaults#LARGE_STROKE_WIDTH()` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/CircularProgressIndicatorDefaults#SMALL_STROKE_WIDTH()`. |
| `gapSize: @https://developer.android.com/reference/kotlin/androidx/annotation/Dimension(unit = 0) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = calculateRecommendedGapSize(strokeWidth)` | The size in dp of the gap between the ends of the progress indicator and the track. The stroke end caps are not included in this distance. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ProgressIndicatorColors = defaultProgressIndicatorStyle.color ?: filledProgressIndicatorColors()` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ProgressIndicatorColors` that will be used to resolve the indicator and track color for this progress indicator. |
| `size: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ContainerDimension = expand()` | The bounding box size of this progress indicator, applies to both width and height. The indicator arc and track arc are located on the largest circle that can be inscribed inside. It is highly recommended for the progress indicator in `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).graphicDataCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,androidx.wear.protolayout.material3.GraphicDataCardStyle,kotlin.Int,androidx.wear.protolayout.ModifiersBuilders.Padding)` to have its size as `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()`, which is the default, to fill the available space for the best result across different screen sizes. Setting `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` with a `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.WrappedDimensionProp` instance will cause failure and throws an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`. |
| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | When `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is set to be `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.WrappedDimensionProp` instance or the provided `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` is smaller than the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).segmentedCircularProgressIndicator(kotlin.Int,kotlin.Float,androidx.wear.protolayout.expression.DynamicBuilders.DynamicFloat,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Float,kotlin.Float,kotlin.Float,kotlin.Float,androidx.wear.protolayout.material3.ProgressIndicatorColors,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)`. |
### MaterialScope.iconEdgeButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/EdgeButton.kt+function:iconEdgeButton)
```
fun MaterialScope.iconEdgeButton(
onClick: ModifiersBuilders.Clickable,
modifier: LayoutModifier = LayoutModifier,
colors: ButtonColors = filledButtonColors(),
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 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.
The button's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconEdgeButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconEdgeButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
materialScope(context, deviceConfiguration) {
iconEdgeButton(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Description of a button"),
) {
icon(protoLayoutResourceId = "id")
}
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors = filledButtonColors()` | The colors used for this button. If not set, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `iconContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/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 `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).icon(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor)` with the resource ID. |
### MaterialScope.textEdgeButton
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/EdgeButton.kt+function:textEdgeButton)
```
fun MaterialScope.textEdgeButton(
onClick: ModifiersBuilders.Clickable,
modifier: LayoutModifier = LayoutModifier,
colors: ButtonColors = filledButtonColors(),
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. 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.
The button's `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textEdgeButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1)` default to using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope` it's defined in, which defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#dynamicColorScheme(android.content.Context,androidx.wear.protolayout.material3.ColorScheme)`, meaning that the colors follow system theme if available on device. If not, or switched off by user, uses fallback `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme` defined in its `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`.
See [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textEdgeButton
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
textEdgeButton(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Description of a button"),
) {
text("Hello".layoutString)
}
}
```
| Parameters |
|---|---|
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` | Associated `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ModifiersBuilders.Clickable` for click events. When the button is clicked it will fire the associated action. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. It's highly recommended to set a content description using `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/package-summary#(androidx.wear.protolayout.modifiers.LayoutModifier).contentDescription(kotlin.String,androidx.wear.protolayout.expression.DynamicBuilders.DynamicString)`. |
| `colors: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonColors = filledButtonColors()` | The colors used for this button. If not set, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledButtonColors()` will be used as high emphasis button. Other recommended colors are `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledTonalButtonColors()` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ButtonDefaults#(androidx.wear.protolayout.material3.MaterialScope).filledVariantButtonColors()`. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast. |
| `labelContent: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/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 `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` with the content. |
### MaterialScope.icon
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Icon.kt+function:icon)
```
fun MaterialScope.[icon](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).icon(kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor))(
protoLayoutResourceId: String,
width: DimensionBuilders.ImageDimension = defaultIconStyle.width,
height: DimensionBuilders.ImageDimension = defaultIconStyle.height,
tintColor: LayoutColor = defaultIconStyle.tintColor
): LayoutElementBuilders.LayoutElement
```
> [!CAUTION]
> **This function is deprecated.**
> Use icon(ImageResource, String, ImageDimension, ImageDimension, LayoutColor) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you.
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The protolayout resource id of the icon. Note that, this is not an Android resource id. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultIconStyle.width` | The width of the icon. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultIconStyle.height` | The height of the icon. |
| `tintColor: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor = defaultIconStyle.tintColor` | The color used to tint the icon. |
### MaterialScope.icon
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Icon.kt+function:icon)
```
fun MaterialScope.icon(
resource: ResourceBuilders.ImageResource,
protoLayoutResourceId: String? = null,
width: DimensionBuilders.ImageDimension = defaultIconStyle.width,
height: DimensionBuilders.ImageDimension = defaultIconStyle.height,
tintColor: LayoutColor = defaultIconStyle.tintColor
): LayoutElementBuilders.LayoutElement
```
Returns the icon components with the defined style which will be automatically registered as a resource.
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(imageResource)`.
Note that, by using this method, there's no need to register resource for Tiles in `androidx.wear.tiles.TileService.onTileResourcesRequest`.
| Parameters |
|---|---|
| `resource: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ResourceBuilders.ImageResource` | An Image resource, used in the layout in the place of this element. |
| `protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html? = null` | The optional protolayout resource id of the icon. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultIconStyle.width` | The width of the icon. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultIconStyle.height` | The height of the icon. |
| `tintColor: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor = defaultIconStyle.tintColor` | The color used to tint the icon. |
| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if this method is called without `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` set to the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`, i.e. when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#materialScopeWithResources(android.content.Context,androidx.wear.protolayout.ProtoLayoutScope,androidx.wear.protolayout.DeviceParametersBuilders.DeviceParameters,kotlin.Boolean,androidx.wear.protolayout.material3.ColorScheme,kotlin.Function1)` wasn't used |
### MaterialScope.avatarImage
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Image.kt+function:avatarImage)
```
fun MaterialScope.[avatarImage](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).avatarImage(kotlin.String,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int))(
protoLayoutResourceId: String,
width: DimensionBuilders.ImageDimension = defaultAvatarImageStyle.width,
height: DimensionBuilders.ImageDimension = defaultAvatarImageStyle.height,
modifier: LayoutModifier = LayoutModifier,
contentScaleMode: Int = defaultAvatarImageStyle.contentScaleMode
): LayoutElementBuilders.LayoutElement
```
> [!CAUTION]
> **This function is deprecated.**
> Use avatarImage(ImageResource, String, ImageDimension, ImageDimension, LayoutModifier, Int) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you.
Returns the avatar image with the defined style.
Material components such as `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).appCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.AppCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` provide proper defaults for the small avatar image. In order to take advantage of those defaults, this should be used with the resource ID only: `avatarImage("id")`.
| Parameters |
|---|---|
| `protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The protolayout resource id of the image. Node that, this is not an Android resource id. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultAvatarImageStyle.width` | The width of an image. Usually, a small image that fit into the component's slot. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultAvatarImageStyle.height` | The height of an image. Usually, a small image that fit into the component's slot. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. |
| `contentScaleMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = defaultAvatarImageStyle.contentScaleMode` | The content scale mode for the image to define how image will adapt to the given size |
### MaterialScope.avatarImage
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Image.kt+function:avatarImage)
```
fun MaterialScope.avatarImage(
resource: ResourceBuilders.ImageResource,
protoLayoutResourceId: String? = null,
width: DimensionBuilders.ImageDimension = defaultAvatarImageStyle.width,
height: DimensionBuilders.ImageDimension = defaultAvatarImageStyle.height,
modifier: LayoutModifier = LayoutModifier,
contentScaleMode: Int = defaultAvatarImageStyle.contentScaleMode
): LayoutElementBuilders.LayoutElement
```
Returns the avatar image with the defined style which will be automatically registered as a resource.
Material components such as `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).appCard(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.ModifiersBuilders.Corner,androidx.wear.protolayout.material3.CardColors,kotlin.Function1,androidx.wear.protolayout.material3.AppCardStyle,androidx.wear.protolayout.ModifiersBuilders.Padding)` provide proper defaults for the small avatar image. In order to take advantage of those defaults, this should be used with the resource ID only: `avatarImage(imageResource)`.
Note that, by using this method, there's no need to register resource for Tiles in `androidx.wear.tiles.TileService.onTileResourcesRequest`.
| Parameters |
|---|---|
| `resource: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ResourceBuilders.ImageResource` | An Image resource, used in the layout in the place of this element. |
| `protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html? = null` | The optional protolayout resource id of the icon. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultAvatarImageStyle.width` | The width of an image. Usually, a small image that fit into the component's slot. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultAvatarImageStyle.height` | The height of an image. Usually, a small image that fit into the component's slot. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. |
| `contentScaleMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = defaultAvatarImageStyle.contentScaleMode` | The content scale mode for the image to define how image will adapt to the given size |
| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if this method is called without `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` set to the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`, i.e. when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#materialScopeWithResources(android.content.Context,androidx.wear.protolayout.ProtoLayoutScope,androidx.wear.protolayout.DeviceParametersBuilders.DeviceParameters,kotlin.Boolean,androidx.wear.protolayout.material3.ColorScheme,kotlin.Function1)` wasn't used |
### MaterialScope.backgroundImage
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Image.kt+function:backgroundImage)
```
fun MaterialScope.[backgroundImage](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int))(
protoLayoutResourceId: String,
modifier: LayoutModifier = LayoutModifier,
width: DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.width,
height: DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.height,
overlayColor: LayoutColor? = defaultBackgroundImageStyle.overlayColor,
contentScaleMode: Int = defaultBackgroundImageStyle.contentScaleMode
): LayoutElementBuilders.LayoutElement
```
> [!CAUTION]
> **This function is deprecated.**
> Use backgroundImage(ImageResource, String, LayoutModifier, ImageDimension, ImageDimension, LayoutColor?, Int) instead, in combination with \[androidx.wear.tiles.Material3TileService\] that creates scopes for you.
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")`.
This image can have optional overlay on top of it, that is usually a dark color with opacity. This is highly recommended to be added when there's additional content like text on top of image, to improve readability.
If this is used in `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).imageButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` as image button with no other content, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` can be omitted, and the overlay color on top of the image would be ignored.
| Parameters |
|---|---|
| `protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The protolayout resource id of the image. Node that, this is not an Android resource id. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.width` | The width of an image. Usually, this matches the width of the parent component this is used in. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.height` | The height of an image. Usually, this matches the height of the parent component this is used in. |
| `overlayColor: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor? = defaultBackgroundImageStyle.overlayColor` | The color used to provide the overlay over the image for better readability. It's recommended to use `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme#background()` color with 60% opacity. If `null`, overlay would be ignored. |
| `contentScaleMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = defaultBackgroundImageStyle.contentScaleMode` | The content scale mode for the image to define how image will adapt to the given size |
### MaterialScope.backgroundImage
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Image.kt+function:backgroundImage)
```
fun MaterialScope.backgroundImage(
resource: ResourceBuilders.ImageResource,
protoLayoutResourceId: String? = null,
modifier: LayoutModifier = LayoutModifier,
width: DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.width,
height: DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.height,
overlayColor: LayoutColor? = defaultBackgroundImageStyle.overlayColor,
contentScaleMode: Int = defaultBackgroundImageStyle.contentScaleMode
): LayoutElementBuilders.LayoutElement
```
Returns the image background with the defined style which will be automatically registered as a resource.
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(imageResource)`.
Note that, by using this method, there's no need to register resource for Tiles in `androidx.wear.tiles.TileService.onTileResourcesRequest`.
This image can have optional overlay on top of it, that is usually a dark color with opacity. This is highly recommended to be added when there's additional content like text on top of image, to improve readability.
If this is used in `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).imageButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,kotlin.Function1,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension)` as image button with no other content, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).backgroundImage(androidx.wear.protolayout.ResourceBuilders.ImageResource,kotlin.String,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.DimensionBuilders.ImageDimension,androidx.wear.protolayout.types.LayoutColor,kotlin.Int)` can be omitted, and the overlay color on top of the image would be ignored.
| Parameters |
|---|---|
| `resource: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ResourceBuilders.ImageResource` | An Image resource, used in the layout in the place of this element. |
| `protoLayoutResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html? = null` | The optional protolayout resource id of the icon. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. |
| `width: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.width` | The width of an image. Usually, this matches the width of the parent component this is used in. |
| `height: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders.ImageDimension = defaultBackgroundImageStyle.height` | The height of an image. Usually, this matches the height of the parent component this is used in. |
| `overlayColor: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor? = defaultBackgroundImageStyle.overlayColor` | The color used to provide the overlay over the image for better readability. It's recommended to use `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme#background()` color with 60% opacity. If `null`, overlay would be ignored. |
| `contentScaleMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = defaultBackgroundImageStyle.contentScaleMode` | The content scale mode for the image to define how image will adapt to the given size |
| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if this method is called without `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/ProtoLayoutScope` set to the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope`, i.e. when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#materialScopeWithResources(android.content.Context,androidx.wear.protolayout.ProtoLayoutScope,androidx.wear.protolayout.DeviceParametersBuilders.DeviceParameters,kotlin.Boolean,androidx.wear.protolayout.material3.ColorScheme,kotlin.Function1)` wasn't used |
### MaterialScope.primaryLayout
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/PrimaryLayout.kt+function: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,
margins: PrimaryLayoutMargins = DEFAULT_PRIMARY_LAYOUT_MARGIN
): 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. It is highly recommended to use this directly as the first root layout element in the `https://developer.android.com/reference/kotlin/androidx/wear/tiles/Material3TileService`.
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 `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#expand()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/DimensionBuilders#weight(float)`. Additional content in the main one can be added after a `225dp` breakpoint.
See [slots](https://developer.android.com/training/wearables/tiles/get_started?version=3#slots), [common-layouts/tiles](https://developer.android.com/design/ui/wear/guides/foundations/common-layouts/tiles) and [bestpractices](https://developer.android.com/design/ui/wear/guides/surfaces/tiles/bestpractices) for more visuals and design recommendations.
```kotlin
import androidx.wear.protolayout.LayoutElementBuilders
import androidx.wear.protolayout.LayoutElementBuilders.Box
import androidx.wear.protolayout.LayoutElementBuilders.LayoutElement
import androidx.wear.protolayout.ModifiersBuilders
import androidx.wear.protolayout.material3.PrimaryLayoutMargins.Companion.MAX_PRIMARY_LAYOUT_MARGIN
import androidx.wear.protolayout.material3.button
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.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
titleSlot = { text("App title".layoutString) },
mainSlot = {
buttonGroup {
// To be populated with proper components
buttonGroupItem {
LayoutElementBuilders.Box.Builder()
.setModifiers(
ModifiersBuilders.Modifiers.Builder()
.setBackground(
ModifiersBuilders.Background.Builder()
.setCorner(shapes.small)
.build()
)
.build()
)
.build()
}
}
},
// Adjust margins as the corner of the inner content is on the square side.
margins = MAX_PRIMARY_LAYOUT_MARGIN,
bottomSlot = {
iconEdgeButton(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Description"),
) {
icon("id")
}
},
)
}
```
```kotlin
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.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
card(
onClick = clickable,
modifier =
LayoutModifier.contentDescription("Card with image background")
.clickable(id = "card"),
width = expand(),
height = expand(),
backgroundContent = { backgroundImage(protoLayoutResourceId = "id") },
) {
text("Content of the Card!".layoutString)
}
}
)
}
```
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.button
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textButton
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.background
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
buttonGroup {
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
iconContent = { icon("id1") },
)
}
buttonGroupItem {
iconButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
iconContent = { icon("id2") },
)
}
buttonGroupItem {
textButton(
onClick = clickable,
modifier =
LayoutModifier.contentDescription(
"Big button with image background"
),
width = expand(),
height = expand(),
shape = shapes.large,
labelContent = { text("Dec".layoutString) },
)
}
}
}
)
}
```
```kotlin
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.CardDefaults.filledVariantCardColors
import androidx.wear.protolayout.material3.CircularProgressIndicatorDefaults.filledTonalProgressIndicatorColors
import androidx.wear.protolayout.material3.GraphicDataCardStyle.Companion.largeGraphicDataCardStyle
import androidx.wear.protolayout.material3.graphicDataCard
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.segmentedCircularProgressIndicator
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clickable
import androidx.wear.protolayout.modifiers.contentDescription
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
mainSlot = {
graphicDataCard(
onClick = clickable,
modifier = LayoutModifier.contentDescription("Data Card with graphic"),
height = expand(),
colors = filledVariantCardColors(),
style = largeGraphicDataCardStyle(),
title = { text("1,234".layoutString) },
content = { icon("steps") },
graphic = {
segmentedCircularProgressIndicator(
segmentCount = 5,
staticProgress = 0.5F,
colors = filledTonalProgressIndicatorColors(),
)
},
)
}
)
}
```
```kotlin
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clearSemantics
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
titleSlot = {
text("App title".layoutString, modifier = LayoutModifier.clearSemantics())
},
mainSlot = { text("Main content".layoutString) },
bottomSlot = {
text("Bottom slot".layoutString, modifier = LayoutModifier.clearSemantics())
},
labelForBottomSlot = {
text("Bottom label".layoutString, modifier = LayoutModifier.clearSemantics())
},
)
}
```
| Parameters |
|---|---|
| `mainSlot: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/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 `225dp` breakpoint. Some of the examples of content that can be passed in here are: \* `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).buttonGroup(androidx.wear.protolayout.DimensionBuilders.ContainerDimension,androidx.wear.protolayout.DimensionBuilders.ContainerDimension,kotlin.Float,kotlin.Function1)` with buttons or cards \* two \[buttonGroup \* Expanded card |
| `titleSlot: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The app title in the top slot, just below the icon. This should be one line of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Typography#TITLE_SMALL()` typography, describing the main purpose of this layout. Title is an optional slot which can be omitted to make space for other elements. Defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme#onBackground()` color. When this `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` is `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`, it is considered as important for accessibility by default, and is marked as heading role, which can be overridden by adding LayoutModifier.clearSemantics into the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` modifier. |
| `bottomSlot: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/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 `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).textEdgeButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1)` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).iconEdgeButton(androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.modifiers.LayoutModifier,androidx.wear.protolayout.material3.ButtonColors,kotlin.Function1)` which is designed to have its bottom following the screen's curvature. This bottom slot is optional, if unset the main content will expand more towards the edge of the screen. When this `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` is `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`, it is considered as important for accessibility by default, which can be overridden by adding LayoutModifier.clearSemantics into the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` modifiers. |
| `labelForBottomSlot: (https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/MaterialScope.() -> https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.LayoutElement)? = null` | The label displayed just above the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)`. Default will be one line of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` with `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Typography#TITLE_SMALL()` typography, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/ColorScheme#onSurface()` color that should contain additional description of this layout. When the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` is not provided or it an edge button, the given label will be ignored. When this `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` is `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`, it is considered as important for accessibility by default, which can be overridden by adding LayoutModifier.clearSemantics into the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` modifiers. |
| `onClick: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/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. |
| `margins: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PrimaryLayoutMargins = DEFAULT_PRIMARY_LAYOUT_MARGIN` | The customized outer margin that will be applied as following: \* `start` and `end` would be applied as a side margins on `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` \* `bottom` would be applied as a bottom margin when `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)` is not present. It is highly recommended to use provided constants for these margins - `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PrimaryLayoutMargins#DEFAULT_PRIMARY_LAYOUT_MARGIN()`, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PrimaryLayoutMargins#MIN_PRIMARY_LAYOUT_MARGIN()`, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PrimaryLayoutMargins#MID_PRIMARY_LAYOUT_MARGIN()` or `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PrimaryLayoutMargins#MAX_PRIMARY_LAYOUT_MARGIN()`, depending on inner content and its corners shape. If providing custom numbers by `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/PrimaryLayoutMargins#customizedPrimaryLayoutMargin(kotlin.Float,kotlin.Float)`, it is a requirement for those to be percentages of the screen width and height. |
### MaterialScope.text
Artifact: [androidx.wear.protolayout:protolayout-material3](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/material3/Text.kt+function:text)
```
fun MaterialScope.text(
text: LayoutString,
modifier: LayoutModifier = LayoutModifier,
typography: Int = defaultTextElementStyle.typography,
color: LayoutColor = defaultTextElementStyle.color,
italic: Boolean = defaultTextElementStyle.italic,
underline: Boolean = defaultTextElementStyle.underline,
scalable: Boolean = defaultTextElementStyle.scalable ?: TypographyFontSelection.getFontScalability(typography),
maxLines: Int = defaultTextElementStyle.maxLines,
alignment: Int = defaultTextElementStyle.alignment,
overflow: Int = defaultTextElementStyle.overflow,
@RequiresSchemaVersion(major = 1, minor = 400) settings: List = emptyList(),
incrementsForTypographySize: List = emptyList()
): 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 `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Typography`.
This text, when added to the `titleSlot`, `bottomSlot` and `labelForBottomSlot` in `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).primaryLayout(kotlin.Function1,kotlin.Function1,kotlin.Function1,kotlin.Function1,androidx.wear.protolayout.ModifiersBuilders.Clickable,androidx.wear.protolayout.material3.PrimaryLayoutMargins)`, is considered as important for accessibility automatically and gets read out by the screen reader even without content description provided in the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. This behavior can be removed with LayoutModifier.clearSemantics if not desired. In all other places, this text is considered as not important for accessibility by default unless content description is specifically provided in the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`.
```kotlin
import androidx.wear.protolayout.material3.Typography
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
text(text = "Hello Material3".layoutString, typography = Typography.DISPLAY_LARGE)
}
```
```kotlin
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
import androidx.wear.protolayout.types.LayoutString
import androidx.wear.protolayout.types.asLayoutConstraint
materialScope(context, deviceConfiguration) {
this.text(
text =
LayoutString(
"Static",
DynamicString.constant("Dynamic"),
"LongestConstraint".asLayoutConstraint(),
),
typography = Typography.DISPLAY_LARGE,
color = colorScheme.tertiary,
underline = true,
maxLines = 5,
)
}
```
```kotlin
import androidx.wear.protolayout.material3.Typography
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
text(
text = "Hello Material3".layoutString,
typography = Typography.DISPLAY_LARGE,
incrementsForTypographySize = listOf(-4f, -2f, 2f),
)
}
```
```kotlin
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.modifiers.LayoutModifier
import androidx.wear.protolayout.modifiers.clearSemantics
import androidx.wear.protolayout.types.layoutString
materialScope(context, deviceConfiguration) {
primaryLayout(
titleSlot = {
text("App title".layoutString, modifier = LayoutModifier.clearSemantics())
},
mainSlot = { text("Main content".layoutString) },
bottomSlot = {
text("Bottom slot".layoutString, modifier = LayoutModifier.clearSemantics())
},
labelForBottomSlot = {
text("Bottom label".layoutString, modifier = LayoutModifier.clearSemantics())
},
)
}
```
| Parameters |
|---|---|
| `text: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutString` | The text content for this component. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/modifiers/LayoutModifier = LayoutModifier` | Modifiers to set to this element. |
| `typography: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = defaultTextElementStyle.typography` | The typography from `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Typography` to be applied to this text. This will have predefined default value specified by each components that uses this text, to achieve the recommended look. If using some of `Typography.NUMERAL_` styles and the provided text is animating, the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` should include `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.FontSetting#tabularNum()` font feature setting for the best results and to avoid text changing its width based on the number present. Value is one of the following: - `2` - `3` - `4` - `5` - `6` - `7` - `8` - `9` - `10` - `11` - `12` - `13` - `14` - `15` - `16` - `17` - `18` - `19`
|
| `color: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/types/LayoutColor = defaultTextElementStyle.color` | The color to be applied to this text. It is recommended to use predefined default styles created by each component or `getColorProp(token)`. |
| `italic: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = defaultTextElementStyle.italic` | Whether text should be displayed as italic. |
| `underline: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = defaultTextElementStyle.underline` | Whether text should be displayed as underlined. |
| `scalable: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = defaultTextElementStyle.scalable ?: TypographyFontSelection.getFontScalability(typography)` | Whether text should scale with the user font size. |
| `maxLines: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = defaultTextElementStyle.maxLines` | The maximum number of lines that text can occupy. |
| `alignment: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = defaultTextElementStyle.alignment` | The horizontal alignment of the multiple lines of text or one line of text when text overflows. |
| `overflow: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html = defaultTextElementStyle.overflow` | The overflow strategy when text doesn't have enough space to be shown. |
| `@https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/RequiresSchemaVersion(major = 1, minor = 400) settings: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html = 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 and renderer version. Each default typography will apply appropriate default setting axes for it (`https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.FontSetting#weight(int)`, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.FontSetting#width(float)` and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/LayoutElementBuilders.FontSetting#roundness(int)`. |
| `incrementsForTypographySize: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html = emptyList()` | The collection increments for the given `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` size to allow text to grow or shrink for that amount to make text auto size in the space it has. The largest increment that fits the most text will be used. Increments can be positive for text to grow more than the specified `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` or negative, for text to be smaller than the specified `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)`. All other parameters of the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/Typography` stay as defined by the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` parameter. For the best results when using auto size, `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` should be negative, to allow text to shrink while still maintaining space between multiple lines. If using positive increments in `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/material3/package-summary#(androidx.wear.protolayout.material3.MaterialScope).text(androidx.wear.protolayout.types.LayoutString,androidx.wear.protolayout.modifiers.LayoutModifier,kotlin.Int,androidx.wear.protolayout.types.LayoutColor,kotlin.Boolean,kotlin.Boolean,kotlin.Boolean,kotlin.Int,kotlin.Int,kotlin.Int,kotlin.collections.List,kotlin.collections.List)` to make the text bigger, pay attention to the line height as that one won't be increased and if increment is too big, text in multiple lines can start overlapping. Positive increments on a single line text can work correctly. Note that this text element should be used in a constraint parent, not purely the one with `wrap` dimension for the best results. |