ButtonKt

Added in 1.3.0-alpha06

public final class ButtonKt

Summary

Public methods
static final @NonNull LayoutElementBuilders.LayoutElement

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

Opinionated ProtoLayout Material3 icon button that offers a single slot to take content representing icon, for example icon.
static final @NonNull LayoutElementBuilders.LayoutElement

Opinionated ProtoLayout Material3 text button that offers a single slot to take content representing short text, for example text.

Public methods

button

public static final @NonNull LayoutElementBuilders.LayoutElement button(
    @NonNull MaterialScope receiver,
    @NonNull ModifiersBuilders.Clickable onClick,
    @NonNull LayoutModifier modifier,
    @ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> content,
    @NonNull DimensionBuilders.ContainerDimension width,
    @NonNull DimensionBuilders.ContainerDimension height,
    @ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> backgroundContent,
    @NonNull ModifiersBuilders.Padding contentPadding
)

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

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 expand or weight for optimal experience across different screen sizes, and use buttonGroup to arrange them.

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

This button can also be used to create image button that only has a background image and no inner content, see androidx.wear.protolayout.material3.samples.imageButtonSample

import androidx.wear.protolayout.DimensionBuilders.expand
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.backgroundColor
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("Big button with image background")
                            .backgroundColor(colorScheme.primary),
                    width = expand(),
                    height = expand(),
                    content = { text("Button!".layoutString) }
                )
            }
        )
    }
 
import androidx.wear.protolayout.DimensionBuilders.expand
import androidx.wear.protolayout.material3.backgroundImage
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.clickable
import androidx.wear.protolayout.modifiers.contentDescription

materialScope(context, deviceConfiguration) {
        primaryLayout(
            mainSlot = {
                button(
                    onClick = clickable,
                    modifier =
                        LayoutModifier.contentDescription("Big button with image background"),
                    width = expand(),
                    height = expand(),
                    backgroundContent = { backgroundImage(protoLayoutResourceId = "id") }
                )
            }
        )
    }
Parameters
@NonNull ModifiersBuilders.Clickable onClick

Associated Clickable for click events. When the button is clicked it will fire the associated action.
@NonNull LayoutModifier modifier

Modifiers to set to this element. It's highly recommended to set a content description using contentDescription. If LayoutModifier.background 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.
@ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> content

The inner content to be put inside of this button.
@NonNull DimensionBuilders.ContainerDimension width

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

The height of this button. It's highly recommended to set this to expand or weight
@ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> backgroundContent

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 backgroundImage with the content. It can be combined with the specified LayoutModifier.background behind it.
@NonNull ModifiersBuilders.Padding contentPadding

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.

iconButton

public static final @NonNull LayoutElementBuilders.LayoutElement iconButton(
    @NonNull MaterialScope receiver,
    @NonNull ModifiersBuilders.Clickable onClick,
    @ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> iconContent,
    @NonNull LayoutModifier modifier,
    @NonNull DimensionBuilders.ContainerDimension width,
    @NonNull DimensionBuilders.ContainerDimension height,
    @NonNull ModifiersBuilders.Corner shape,
    @NonNull ButtonColors colors,
    @ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> backgroundContent,
    @NonNull IconButtonStyle style,
    @NonNull ModifiersBuilders.Padding contentPadding
)

Opinionated ProtoLayout Material3 icon button that offers a single slot to take content representing icon, for example icon.

The button is usually either a circular shape with the same width and height, or highly recommended stadium shape occupying available space with width and height set to expand or weight, usually used in the buttonGroup to arrange them

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.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
@NonNull ModifiersBuilders.Clickable onClick

Associated Clickable for click events. When the button is clicked it will fire the associated action.
@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.
@NonNull LayoutModifier modifier

Modifiers to set to this element. It's highly recommended to set a content description using contentDescription.
@NonNull DimensionBuilders.ContainerDimension width

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

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

Defines the button's shape, in other words the corner radius for this button.
@NonNull ButtonColors colors

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

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 backgroundImage with the content. It can be combined with the specified ButtonColors.container behind it.
@NonNull IconButtonStyle style

The style which provides the attribute values required for constructing this icon button its inner content. It also provides default style for the inner content, that can be overridden by each content slot.
@NonNull ModifiersBuilders.Padding contentPadding

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.

textButton

public static final @NonNull LayoutElementBuilders.LayoutElement textButton(
    @NonNull MaterialScope receiver,
    @NonNull ModifiersBuilders.Clickable onClick,
    @ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelContent,
    @NonNull LayoutModifier modifier,
    @NonNull DimensionBuilders.ContainerDimension width,
    @NonNull DimensionBuilders.ContainerDimension height,
    @NonNull ModifiersBuilders.Corner shape,
    @NonNull ButtonColors colors,
    @ExtensionFunctionType Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> backgroundContent,
    @NonNull TextButtonStyle style,
    @NonNull ModifiersBuilders.Padding contentPadding
)

Opinionated ProtoLayout Material3 text button that offers a single slot to take content representing short text, for example text.

The button is usually either a circular shape with the same width and height, or highly recommended stadium shape occupying available space with width and height set to expand or weight, usually used in the buttonGroup to arrange them.

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.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
@NonNull ModifiersBuilders.Clickable onClick

Associated Clickable for click events. When the button is clicked it will fire the associated action.
@ExtensionFunctionType @NonNull Function1<@NonNull MaterialScope, @NonNull LayoutElementBuilders.LayoutElement> labelContent

The text slot for content displayed in this button. It is recommended to use default styling that is automatically provided by only calling text with the resource ID. This should be small, usually up to 3 characters text.
@NonNull LayoutModifier modifier

Modifiers to set to this element. It's highly recommended to set a content description using contentDescription.
@NonNull DimensionBuilders.ContainerDimension width

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

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

Defines the button's shape, in other words the corner radius for this button.
@NonNull ButtonColors colors

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

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 backgroundImage with the content. It can be combined with the specified ButtonColors.container behind it.
@NonNull TextButtonStyle style

The style which provides the attribute values required for constructing this icon button its inner content. It also provides default style for the inner content, that can be overridden by each content slot.
@NonNull ModifiersBuilders.Padding contentPadding

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.