@MaterialScopeMarker
public 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.

  • DeviceParameters, which contains screen size, font scale, renderer schema version etc.

  • Default usage of system theme, with the option to opt out.

Summary

Public methods
final @NonNull ColorScheme

Color Scheme used within this scope and its components.
final @NonNull DeviceParametersBuilders.DeviceParameters

The device parameters for where the components will be rendered.
final @NonNull Shapes

Shapes theme used within this scope and its components.

Extension functions
final @NonNull LayoutElementBuilders.LayoutElement
ButtonGroupKt.buttonGroup(
    @NonNull MaterialScope receiver,
    @NonNull DimensionBuilders.ContainerDimension width,
    @NonNull DimensionBuilders.ContainerDimension height,
    @Dimension(unit = 0) float spacing,
    @ExtensionFunctionType @NonNull Function1<@NonNull ButtonGroupScope, Unit> content
)

ProtoLayout Material3 component-layout that places its children in a horizontal sequence.
final @NonNull LayoutElementBuilders.LayoutElement

ProtoLayout Material3 clickable component card that offers a single slot to take any content.
final @NonNull LayoutElementBuilders.LayoutElement

ProtoLayout Material3 component edge button that offers a single slot to take an icon or similar round, small content.
final @NonNull LayoutElementBuilders.LayoutElement

ProtoLayout Material3 component edge button that offers a single slot to take a text or similar long and wide content.
final @NonNull LayoutElementBuilders.LayoutElement
IconKt.icon(
    @NonNull MaterialScope receiver,
    @NonNull String protoLayoutResourceId,
    @NonNull DimensionBuilders.ImageDimension size,
    @NonNull ColorBuilders.ColorProp tintColor
)

Returns the icon components with the defined style.
final @NonNull LayoutElementBuilders.LayoutElement
ImageKt.backgroundImage(
    @NonNull MaterialScope receiver,
    @NonNull String protoLayoutResourceId,
    @NonNull DimensionBuilders.ImageDimension width,
    @NonNull DimensionBuilders.ImageDimension height,
    @NonNull ColorBuilders.ColorProp overlayColor,
    @NonNull DimensionBuilders.ContainerDimension overlayWidth,
    @NonNull DimensionBuilders.ContainerDimension overlayHeight,
    @NonNull ModifiersBuilders.Corner shape,
    int contentScaleMode
)

Returns the image background with the defined style.
final @NonNull 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.
final @NonNull LayoutElementBuilders.LayoutElement
TextKt.text(
    @NonNull MaterialScope receiver,
    @NonNull TypeBuilders.StringProp text,
    @NonNull TypeBuilders.StringLayoutConstraint stringLayoutConstraint,
    int typography,
    @NonNull ColorBuilders.ColorProp color,
    boolean italic,
    boolean underline,
    boolean scalable,
    int maxLines,
    int multilineAlignment,
    int overflow,
    @NonNull ModifiersBuilders.Modifiers modifiers
)

ProtoLayout component that represents text object holding any information.

Public methods

getColorScheme

Added in 1.3.0-alpha05
public final @NonNull ColorScheme getColorScheme()

Color Scheme used within this scope and its components.

getDeviceConfiguration

Added in 1.3.0-alpha05
public final @NonNull DeviceParametersBuilders.DeviceParameters getDeviceConfiguration()

The device parameters for where the components will be rendered.

getShapes

Added in 1.3.0-alpha05
public final @NonNull Shapes getShapes()

Shapes theme used within this scope and its components.

Extension functions

ButtonGroupKt.buttonGroup

public final @NonNull LayoutElementBuilders.LayoutElement ButtonGroupKt.buttonGroup(
    @NonNull MaterialScope receiver,
    @NonNull DimensionBuilders.ContainerDimension width,
    @NonNull DimensionBuilders.ContainerDimension height,
    @Dimension(unit = 0) float spacing,
    @ExtensionFunctionType @NonNull Function1<@NonNull ButtonGroupScope, Unit> content
)

ProtoLayout Material3 component-layout that places its children in a horizontal sequence.

These behave as a group which fill the available space to maximize on screen real estate. The color and size of the child elements should be changed in order to create hierarchy and priority.

The width and height of the Button/Card should be flexible (set to androidx.wear.protolayout.DimensionBuilders.expand or androidx.wear.protolayout.DimensionBuilders.weight) and their proportion should be either equal or weight based. However the buttonGroup displays correctly too if the sizes of elements provided are set to a fixed width/height, although it can lead to more empty space on large screen sizes.

A buttonGroup with more than one row can be created by using multiple buttonGroup and Spacers inside a androidx.wear.protolayout.LayoutElementBuilders.Column:

Column.Builder()
  .setWidth(expand())
  .setHeight(expand())
  .addContent(buttonGroup {...})
  .addContent(DEFAULT_SPACER_BETWEEN_BUTTON_GROUPS)
  .addContent(buttonGroup {...})
  .build()
}

Note that, having more than 2 rows in a Column could lead to too small height of elements that aren't in line with minimum tap target.

Parameters
@NonNull DimensionBuilders.ContainerDimension width

The width of this button group
@NonNull DimensionBuilders.ContainerDimension height

The height of this button group
@Dimension(unit = 0) float spacing

The amount of spacing between buttons
@ExtensionFunctionType @NonNull Function1<@NonNull ButtonGroupScope, Unit> content

The content for each child. The UX guidance is to use no more than 3 elements within a this button group.

CardKt.card

public final @NonNull LayoutElementBuilders.LayoutElement CardKt.card(
    @NonNull MaterialScope receiver,
    @NonNull ModifiersBuilders.Clickable onClick,
    @NonNull TypeBuilders.StringProp contentDescription,
    @NonNull DimensionBuilders.ContainerDimension width,
    @NonNull DimensionBuilders.ContainerDimension height,
    @NonNull ModifiersBuilders.Corner shape,
    ColorBuilders.ColorProp backgroundColor,
    @ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> background,
    @NonNull ModifiersBuilders.Padding contentPadding,
    @ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> content
)

ProtoLayout Material3 clickable component card that offers a single slot to take any content.

It can be used as the container for more opinionated Card components that take specific content such as icons, images, primary label, secondary label, etc.

The Card is Rectangle shaped with some rounded corners by default. It is highly recommended to set its width and height to fill the available space, by expand or weight for optimal experience across different screen sizes.

It can be used for displaying any clickable container with additional data, text or graphics.

import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.backgroundImage
import androidx.wear.protolayout.material3.card
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.prop
import androidx.wear.protolayout.material3.text

materialScope(context, deviceConfiguration) {
        primaryLayout(
            mainSlot = {
                card(
                    onClick = clickable,
                    contentDescription = "Card with image background".prop(),
                    width = expand(),
                    height = expand(),
                    background = { backgroundImage(protoLayoutResourceId = "id") }
                ) {
                    text("Content of the Card!".prop())
                }
            }
        )
    }
Parameters
@NonNull ModifiersBuilders.Clickable onClick

Associated Clickable for click events. When the card is clicked it will fire the associated action.
@NonNull TypeBuilders.StringProp contentDescription

The content description to be read by Talkback.
@NonNull DimensionBuilders.ContainerDimension width

The width of this card. It's highly recommended to set this to expand or weight
@NonNull DimensionBuilders.ContainerDimension height

The height of this card. It's highly recommended to set this to expand or weight
@NonNull ModifiersBuilders.Corner shape

Defines the card's shape, in other words the corner radius for this card.
ColorBuilders.ColorProp backgroundColor

The color to be used as a background of this card. If the background image is also specified, it will be laid out on top of this color.
@ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> background

The background object to be used behind the content in the card. It is recommended the default styling that is automatically provided by only calling backgroundImage with the content. It can be combined with the specified backgroundColor behind it.
@NonNull ModifiersBuilders.Padding contentPadding

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.
@ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> content

The inner content to be put inside of this card.

EdgeButtonKt.iconEdgeButton

public final @NonNull LayoutElementBuilders.LayoutElement EdgeButtonKt.iconEdgeButton(
    @NonNull MaterialScope receiver,
    @NonNull ModifiersBuilders.Clickable onClick,
    @NonNull TypeBuilders.StringProp contentDescription,
    @NonNull EdgeButtonColors colors,
    @ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> iconContent
)

ProtoLayout Material3 component edge button that offers a single slot to take an icon or similar round, small content.

The edge button is intended to be used at the bottom of a round screen. It has a special shape with its bottom almost follows the screen's curvature. It has fixed height, and takes 1 line of text or a single icon. This button represents the most important action on the screen, and it must occupy the whole horizontal space in its position as well as being anchored to the screen bottom.

This component is not intended to be used with an image background.

import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconEdgeButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.prop
import androidx.wear.protolayout.material3.text

materialScope(context, deviceConfiguration) {
        iconEdgeButton(onClick = clickable, contentDescription = "Description of a button".prop()) {
            icon(protoLayoutResourceId = "id")
        }
    }
Parameters
@NonNull ModifiersBuilders.Clickable onClick

Associated Clickable for click events. When the button is clicked it will fire the associated action.
@NonNull TypeBuilders.StringProp contentDescription

The content description to be read by Talkback.
@NonNull EdgeButtonColors colors

The colors used for this button. If not set, EdgeButtonDefaults.filled will be used as high emphasis button. Other recommended colors are EdgeButtonDefaults.filledTonal and EdgeButtonDefaults.filledVariant. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast.
@ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> iconContent

The icon slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling icon with the resource ID.

EdgeButtonKt.textEdgeButton

public final @NonNull LayoutElementBuilders.LayoutElement EdgeButtonKt.textEdgeButton(
    @NonNull MaterialScope receiver,
    @NonNull ModifiersBuilders.Clickable onClick,
    @NonNull TypeBuilders.StringProp contentDescription,
    @NonNull EdgeButtonColors colors,
    @ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelContent
)

ProtoLayout Material3 component edge button that offers a single slot to take a text or similar long and wide content.

The edge button is intended to be used at the bottom of a round screen. It has a special shape with its bottom almost follows the screen's curvature. It has fixed height, and takes 1 line of text or a single icon. This button represents the most important action on the screen, and it must occupy the whole horizontal space in its position as well as being anchored to the screen bottom.

This component is not intended to be used with an image background.

import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.prop
import androidx.wear.protolayout.material3.text
import androidx.wear.protolayout.material3.textEdgeButton

materialScope(context, deviceConfiguration) {
        textEdgeButton(onClick = clickable, contentDescription = "Description of a button".prop()) {
            text("Hello".prop())
        }
    }
Parameters
@NonNull ModifiersBuilders.Clickable onClick

Associated Clickable for click events. When the button is clicked it will fire the associated action.
@NonNull TypeBuilders.StringProp contentDescription

The content description to be read by Talkback.
@NonNull EdgeButtonColors colors

The colors used for this button. If not set, EdgeButtonDefaults.filled will be used as high emphasis button. Other recommended colors are EdgeButtonDefaults.filledTonal and EdgeButtonDefaults.filledVariant. If using custom colors, it is important to choose a color pair from same role to ensure accessibility with sufficient color contrast.
@ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelContent

The label slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling text with the content.

IconKt.icon

public final @NonNull LayoutElementBuilders.LayoutElement IconKt.icon(
    @NonNull MaterialScope receiver,
    @NonNull String protoLayoutResourceId,
    @NonNull DimensionBuilders.ImageDimension size,
    @NonNull ColorBuilders.ColorProp tintColor
)

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
@NonNull String protoLayoutResourceId

The protolayout resource id of the icon. Node that, this is not an Android resource id.
@NonNull DimensionBuilders.ImageDimension size

The side of an icon that will be used for width and height.
@NonNull ColorBuilders.ColorProp tintColor

The color used to tint the icon.

ImageKt.backgroundImage

public final @NonNull LayoutElementBuilders.LayoutElement ImageKt.backgroundImage(
    @NonNull MaterialScope receiver,
    @NonNull String protoLayoutResourceId,
    @NonNull DimensionBuilders.ImageDimension width,
    @NonNull DimensionBuilders.ImageDimension height,
    @NonNull ColorBuilders.ColorProp overlayColor,
    @NonNull DimensionBuilders.ContainerDimension overlayWidth,
    @NonNull DimensionBuilders.ContainerDimension overlayHeight,
    @NonNull ModifiersBuilders.Corner shape,
    int contentScaleMode
)

Returns the image background with the defined style.

Material components provide proper defaults for the background image. In order to take advantage of those defaults, this should be used with the resource ID only: backgroundImage("id").

Parameters
@NonNull String protoLayoutResourceId

The protolayout resource id of the icon. Node that, this is not an Android resource id.
@NonNull DimensionBuilders.ImageDimension width

The width of an image. Usually, this matches the width of the parent component this is used in.
@NonNull DimensionBuilders.ImageDimension height

The height of an image. Usually, this matches the height of the parent component this is used in.
@NonNull ColorBuilders.ColorProp overlayColor

The color used to provide the overlay over the image for better readability. It's recommended to use ColorScheme.background color with 60% opacity.
@NonNull DimensionBuilders.ContainerDimension overlayWidth

The width of the overlay on top of the image background
@NonNull DimensionBuilders.ContainerDimension overlayHeight

The height of the overlay on top of the image background
@NonNull ModifiersBuilders.Corner shape

The shape of the corners for the image
int contentScaleMode

The content scale mode for the image to define how image will adapt to the given size

PrimaryLayoutKt.primaryLayout

public final @NonNull LayoutElementBuilders.LayoutElement PrimaryLayoutKt.primaryLayout(
    @NonNull MaterialScope receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> mainSlot,
    @ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> titleSlot,
    @ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> bottomSlot,
    @ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelForBottomSlot,
    ModifiersBuilders.Clickable onClick
)

ProtoLayout Material3 full screen layout that represents a suggested Material3 layout style that is responsive and takes care of the elements placement, together with the recommended margin and padding applied.

This layout is meant to occupy the whole screen, so nothing else should be added on top of it.

On the top, there is an icon that will be automatically placed by the system, followed by the optional title slot. The icon slot needs to be reserved for the whole ProtoLayout Layout and no other content should be added at the top of the screen as it will be overlapped with the system placed icon.

At the bottom, there is an optional fixed slot for either {@link EdgeButton} as a main action or small non tappable content.

The middle of the layout is main content, that will fill the available space. For the best results across different screen sizes, it's recommended that this content's dimension are also DimensionBuilders.expand or DimensionBuilders.weight. Additional content in the main one can be added after a 225dp breakpoint.

import androidx.wear.protolayout.LayoutElementBuilders
import androidx.wear.protolayout.LayoutElementBuilders.LayoutElement
import androidx.wear.protolayout.ModifiersBuilders
import androidx.wear.protolayout.material3.buttonGroup
import androidx.wear.protolayout.material3.icon
import androidx.wear.protolayout.material3.iconEdgeButton
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.primaryLayout
import androidx.wear.protolayout.material3.prop
import androidx.wear.protolayout.material3.text

materialScope(context, deviceConfiguration) {
        primaryLayout(
            titleSlot = { text("App title".prop()) },
            mainSlot = {
                buttonGroup {
                    // To be populated with proper components
                    buttonGroupItem {
                        LayoutElementBuilders.Box.Builder()
                            .setModifiers(
                                ModifiersBuilders.Modifiers.Builder()
                                    .setBackground(
                                        ModifiersBuilders.Background.Builder()
                                            .setCorner(shapes.full)
                                            .build()
                                    )
                                    .build()
                            )
                            .build()
                    }
                }
            },
            bottomSlot = { iconEdgeButton(clickable, "Description".prop()) { icon("id") } }
        )
    }
Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> mainSlot

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: * buttonGroup with buttons or cards * two [buttonGroup * Expanded card
@ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> titleSlot

The app title in the top slot, just below the icon. This should be one line of text with 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 ColorScheme.onBackground color.
@ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> bottomSlot

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 textEdgeButton or iconEdgeButton 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.
@ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelForBottomSlot

The label displayed just above the bottomSlot. Default will be one line of text with Typography.TITLE_SMALL typography, ColorScheme.onSurface color that should contain additional description of this layout. When the bottomSlot is not provided or it an edge button, the given label will be ignored.
ModifiersBuilders.Clickable onClick

The clickable action for whole layout. If any area (outside of other added tappable components) is clicked, it will fire the associated action.

TextKt.text

public final @NonNull LayoutElementBuilders.LayoutElement TextKt.text(
    @NonNull MaterialScope receiver,
    @NonNull TypeBuilders.StringProp text,
    @NonNull TypeBuilders.StringLayoutConstraint stringLayoutConstraint,
    int typography,
    @NonNull ColorBuilders.ColorProp color,
    boolean italic,
    boolean underline,
    boolean scalable,
    int maxLines,
    int multilineAlignment,
    int overflow,
    @NonNull ModifiersBuilders.Modifiers modifiers
)

ProtoLayout component that represents text object holding any information.

There are pre-defined typography styles that can be obtained from Materials token system in Typography.

import androidx.wear.protolayout.material3.Typography
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.prop
import androidx.wear.protolayout.material3.text

materialScope(context, deviceConfiguration) {
        text(text = "Hello Material3".prop(), typography = Typography.DISPLAY_LARGE)
    }
 
import androidx.wear.protolayout.TypeBuilders.StringLayoutConstraint
import androidx.wear.protolayout.TypeBuilders.StringProp
import androidx.wear.protolayout.expression.DynamicBuilders.DynamicString
import androidx.wear.protolayout.material3.Typography
import androidx.wear.protolayout.material3.materialScope
import androidx.wear.protolayout.material3.text

materialScope(context, deviceConfiguration) {
        text(
            text =
                StringProp.Builder("Static")
                    .setDynamicValue(DynamicString.constant("Dynamic"))
                    .build(),
            stringLayoutConstraint = StringLayoutConstraint.Builder("Constraint").build(),
            typography = Typography.DISPLAY_LARGE,
            color = colorScheme.tertiary,
            underline = true,
            maxLines = 5
        )
    }
Parameters
@NonNull TypeBuilders.StringProp text

The text content for this component.
@NonNull TypeBuilders.StringLayoutConstraint stringLayoutConstraint

The layout constraints used to correctly measure Text view size and align text when text has dynamic value.
int typography

The typography from 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.
@NonNull ColorBuilders.ColorProp color

The color to be applied to this text. It is recommended to use predefined default styles created by each component or getColorProp(token).
boolean italic

Whether text should be displayed as italic.
boolean underline

Whether text should be displayed as underlined.
boolean scalable

Whether text should scale with the user font size.
int maxLines

The maximum number of lines that text can occupy.
int multilineAlignment

The horizontal alignment of the multiple lines of text.
int overflow

The overflow strategy when text doesn't have enough space to be shown.
@NonNull ModifiersBuilders.Modifiers modifiers

The additional Modifiers for this text.