androidx.glance.appwidget.components

Top-level functions summary

Unit
@Composable
CircleIconButton(
    imageProvider: ImageProvider,
    contentDescription: String?,
    onClick: Action,
    modifier: GlanceModifier,
    enabled: Boolean,
    backgroundColor: ColorProvider?,
    contentColor: ColorProvider
)

Intended to fill the role of secondary icon button.

Unit
@Composable
CircleIconButton(
    imageProvider: ImageProvider,
    contentDescription: String?,
    onClick: () -> Unit,
    modifier: GlanceModifier,
    enabled: Boolean,
    backgroundColor: ColorProvider?,
    contentColor: ColorProvider,
    key: String?
)

Intended to fill the role of secondary icon button.

Unit
@Composable
FilledButton(
    text: String,
    onClick: Action,
    modifier: GlanceModifier,
    enabled: Boolean,
    icon: ImageProvider?,
    colors: ButtonColors,
    maxLines: Int
)

A button styled per Material3.

Unit
@Composable
FilledButton(
    text: String,
    onClick: () -> Unit,
    modifier: GlanceModifier,
    enabled: Boolean,
    icon: ImageProvider?,
    colors: ButtonColors,
    maxLines: Int,
    key: String?
)

A button styled per Material3.

Unit
@Composable
OutlineButton(
    text: String,
    contentColor: ColorProvider,
    onClick: Action,
    modifier: GlanceModifier,
    enabled: Boolean,
    icon: ImageProvider?,
    maxLines: Int
)

An outline button styled per Material3.

Unit
@Composable
OutlineButton(
    text: String,
    contentColor: ColorProvider,
    onClick: () -> Unit,
    modifier: GlanceModifier,
    enabled: Boolean,
    icon: ImageProvider?,
    maxLines: Int,
    key: String?
)

An outline button styled per Material3.

Unit
@Composable
Scaffold(
    modifier: GlanceModifier,
    titleBar: (@Composable () -> Unit)?,
    backgroundColor: ColorProvider,
    horizontalPadding: Dp,
    content: @Composable () -> Unit
)

A simple slot api component for displaying widget UI with a TitleBar.

Unit
@Composable
SquareIconButton(
    imageProvider: ImageProvider,
    contentDescription: String?,
    onClick: Action,
    modifier: GlanceModifier,
    enabled: Boolean,
    backgroundColor: ColorProvider,
    contentColor: ColorProvider
)

Intended to fill the role of primary icon button or fab.

Unit
@Composable
SquareIconButton(
    imageProvider: ImageProvider,
    contentDescription: String?,
    onClick: () -> Unit,
    modifier: GlanceModifier,
    enabled: Boolean,
    backgroundColor: ColorProvider,
    contentColor: ColorProvider,
    key: String?
)

Intended to fill the role of primary icon button or fab.

Unit
@Composable
TitleBar(
    startIcon: ImageProvider,
    title: String,
    iconColor: ColorProvider?,
    textColor: ColorProvider,
    modifier: GlanceModifier,
    fontFamily: FontFamily?,
    actions: @Composable RowScope.() -> Unit
)

A Title Bar.

Top-level functions

CircleIconButton

@Composable
fun CircleIconButton(
    imageProvider: ImageProvider,
    contentDescription: String?,
    onClick: Action,
    modifier: GlanceModifier = GlanceModifier,
    enabled: Boolean = true,
    backgroundColor: ColorProvider? = GlanceTheme.colors.background,
    contentColor: ColorProvider = GlanceTheme.colors.onSurface
): Unit

Intended to fill the role of secondary icon button. Background color may be null to have the button display as an icon with a 48x48dp hit area.

Parameters
imageProvider: ImageProvider

the icon to be drawn in the button

contentDescription: String?

Text used by accessibility services to describe what this image represents. This text should be localized, such as by using androidx.compose.ui.res.stringResource or similar

onClick: Action

The action to be performed when this button is clicked.

modifier: GlanceModifier = GlanceModifier

The modifier to be applied to this button.

enabled: Boolean = true

If false, the button will not be clickable.

backgroundColor: ColorProvider? = GlanceTheme.colors.background

The color to tint the button's background. May be null to make background transparent.

contentColor: ColorProvider = GlanceTheme.colors.onSurface

The color to tint the button's icon.

CircleIconButton

@Composable
fun CircleIconButton(
    imageProvider: ImageProvider,
    contentDescription: String?,
    onClick: () -> Unit,
    modifier: GlanceModifier = GlanceModifier,
    enabled: Boolean = true,
    backgroundColor: ColorProvider? = GlanceTheme.colors.background,
    contentColor: ColorProvider = GlanceTheme.colors.onSurface,
    key: String? = null
): Unit

Intended to fill the role of secondary icon button. Background color may be null to have the button display as an icon with a 48x48dp hit area.

Parameters
imageProvider: ImageProvider

the icon to be drawn in the button

contentDescription: String?

Text used by accessibility services to describe what this image represents. This text should be localized, such as by using androidx.compose.ui.res.stringResource or similar

onClick: () -> Unit

The action to be performed when this button is clicked.

modifier: GlanceModifier = GlanceModifier

The modifier to be applied to this button.

enabled: Boolean = true

If false, the button will not be clickable.

backgroundColor: ColorProvider? = GlanceTheme.colors.background

The color to tint the button's background. May be null to make background transparent.

contentColor: ColorProvider = GlanceTheme.colors.onSurface

The color to tint the button's icon.

key: String? = null

A stable and unique key that identifies the action for this button. This ensures that the correct action is triggered, especially in cases of items that change order. If not provided we use the key that is automatically generated by the Compose runtime, which is unique for every exact code location in the composition tree.

FilledButton

@Composable
fun FilledButton(
    text: String,
    onClick: Action,
    modifier: GlanceModifier = GlanceModifier,
    enabled: Boolean = true,
    icon: ImageProvider? = null,
    colors: ButtonColors = ButtonDefaults.buttonColors(),
    maxLines: Int = Int.MAX_VALUE
): Unit

A button styled per Material3. It has a filled background. It is more opinionated than Button and suitable for uses where M3 is preferred.

Parameters
text: String

The text that this button will show.

onClick: Action

The action to be performed when this button is clicked.

modifier: GlanceModifier = GlanceModifier

The modifier to be applied to this button.

enabled: Boolean = true

If false, the button will not be clickable.

icon: ImageProvider? = null

An optional leading icon placed before the text.

colors: ButtonColors = ButtonDefaults.buttonColors()

The colors to use for the background and content of the button.

maxLines: Int = Int.MAX_VALUE

An optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated.

FilledButton

@Composable
fun FilledButton(
    text: String,
    onClick: () -> Unit,
    modifier: GlanceModifier = GlanceModifier,
    enabled: Boolean = true,
    icon: ImageProvider? = null,
    colors: ButtonColors = ButtonDefaults.buttonColors(),
    maxLines: Int = Int.MAX_VALUE,
    key: String? = null
): Unit

A button styled per Material3. It has a filled background. It is more opinionated than Button and suitable for uses where M3 is preferred.

Parameters
text: String

The text that this button will show.

onClick: () -> Unit

The action to be performed when this button is clicked.

modifier: GlanceModifier = GlanceModifier

The modifier to be applied to this button.

enabled: Boolean = true

If false, the button will not be clickable.

icon: ImageProvider? = null

An optional leading icon placed before the text.

colors: ButtonColors = ButtonDefaults.buttonColors()

The colors to use for the background and content of the button.

maxLines: Int = Int.MAX_VALUE

An optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated.

key: String? = null

A stable and unique key that identifies the action for this button. This ensures that the correct action is triggered, especially in cases of items that change order. If not provided we use the key that is automatically generated by the Compose runtime, which is unique for every exact code location in the composition tree.

OutlineButton

@Composable
fun OutlineButton(
    text: String,
    contentColor: ColorProvider,
    onClick: Action,
    modifier: GlanceModifier = GlanceModifier,
    enabled: Boolean = true,
    icon: ImageProvider? = null,
    maxLines: Int = Int.MAX_VALUE
): Unit

An outline button styled per Material3. It has a transparent background. It is more opinionated than Button and suitable for uses where M3 is preferred.

Parameters
text: String

The text that this button will show.

contentColor: ColorProvider

The color used for the text, optional icon tint, and outline.

onClick: Action

The action to be performed when this button is clicked.

modifier: GlanceModifier = GlanceModifier

The modifier to be applied to this button.

enabled: Boolean = true

If false, the button will not be clickable.

icon: ImageProvider? = null

An optional leading icon placed before the text.

maxLines: Int = Int.MAX_VALUE

An optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated.

OutlineButton

@Composable
fun OutlineButton(
    text: String,
    contentColor: ColorProvider,
    onClick: () -> Unit,
    modifier: GlanceModifier = GlanceModifier,
    enabled: Boolean = true,
    icon: ImageProvider? = null,
    maxLines: Int = Int.MAX_VALUE,
    key: String? = null
): Unit

An outline button styled per Material3. It has a transparent background. It is more opinionated than Button and suitable for uses where M3 is preferred.

Parameters
text: String

The text that this button will show.

contentColor: ColorProvider

The color used for the text, optional icon tint, and outline.

onClick: () -> Unit

The action to be performed when this button is clicked.

modifier: GlanceModifier = GlanceModifier

The modifier to be applied to this button.

enabled: Boolean = true

If false, the button will not be clickable.

icon: ImageProvider? = null

An optional leading icon placed before the text.

maxLines: Int = Int.MAX_VALUE

An optional maximum number of lines for the text to span, wrapping if necessary. If the text exceeds the given number of lines, it will be truncated.

key: String? = null

A stable and unique key that identifies the action for this button. This ensures that the correct action is triggered, especially in cases of items that change order. If not provided we use the key that is automatically generated by the Compose runtime, which is unique for every exact code location in the composition tree.

@Composable
fun Scaffold(
    modifier: GlanceModifier = GlanceModifier,
    titleBar: (@Composable () -> Unit)? = null,
    backgroundColor: ColorProvider = GlanceTheme.colors.widgetBackground,
    horizontalPadding: Dp = 12.dp,
    content: @Composable () -> Unit
): Unit

A simple slot api component for displaying widget UI with a TitleBar. Sets the background color to GlanceTheme.colors.surface and applies padding. This is intended to be used as a top level component.

Parameters
modifier: GlanceModifier = GlanceModifier

a modifier

titleBar: (@Composable () -> Unit)? = null

A composable that creates the TitleBar. Optional parameter.

backgroundColor: ColorProvider = GlanceTheme.colors.widgetBackground

the background color for the layout.

horizontalPadding: Dp = 12.dp

Scaffold provides a default padding which should work for most use cases. However, it can be overridden.

content: @Composable () -> Unit

The main content of the widget.

SquareIconButton

@Composable
fun SquareIconButton(
    imageProvider: ImageProvider,
    contentDescription: String?,
    onClick: Action,
    modifier: GlanceModifier = GlanceModifier,
    enabled: Boolean = true,
    backgroundColor: ColorProvider = GlanceTheme.colors.primary,
    contentColor: ColorProvider = GlanceTheme.colors.onPrimary
): Unit

Intended to fill the role of primary icon button or fab.

Parameters
imageProvider: ImageProvider

the icon to be drawn in the button

contentDescription: String?

Text used by accessibility services to describe what this image represents. This text should be localized, such as by using androidx.compose.ui.res.stringResource or similar

onClick: Action

The action to be performed when this button is clicked.

modifier: GlanceModifier = GlanceModifier

The modifier to be applied to this button.

enabled: Boolean = true

If false, the button will not be clickable.

backgroundColor: ColorProvider = GlanceTheme.colors.primary

The color to tint the button's background.

contentColor: ColorProvider = GlanceTheme.colors.onPrimary

The color to tint the button's icon.

SquareIconButton

@Composable
fun SquareIconButton(
    imageProvider: ImageProvider,
    contentDescription: String?,
    onClick: () -> Unit,
    modifier: GlanceModifier = GlanceModifier,
    enabled: Boolean = true,
    backgroundColor: ColorProvider = GlanceTheme.colors.primary,
    contentColor: ColorProvider = GlanceTheme.colors.onPrimary,
    key: String? = null
): Unit

Intended to fill the role of primary icon button or fab.

Parameters
imageProvider: ImageProvider

the icon to be drawn in the button

contentDescription: String?

Text used by accessibility services to describe what this image represents. This text should be localized, such as by using androidx.compose.ui.res.stringResource or similar

onClick: () -> Unit

The action to be performed when this button is clicked.

modifier: GlanceModifier = GlanceModifier

The modifier to be applied to this button.

enabled: Boolean = true

If false, the button will not be clickable.

backgroundColor: ColorProvider = GlanceTheme.colors.primary

The color to tint the button's background.

contentColor: ColorProvider = GlanceTheme.colors.onPrimary

The color to tint the button's icon.

key: String? = null

A stable and unique key that identifies the action for this button. This ensures that the correct action is triggered, especially in cases of items that change order. If not provided we use the key that is automatically generated by the Compose runtime, which is unique for every exact code location in the composition tree.

TitleBar

@Composable
fun TitleBar(
    startIcon: ImageProvider,
    title: String,
    iconColor: ColorProvider? = GlanceTheme.colors.onSurface,
    textColor: ColorProvider = GlanceTheme.colors.onSurface,
    modifier: GlanceModifier = GlanceModifier,
    fontFamily: FontFamily? = null,
    actions: @Composable RowScope.() -> Unit = {}
): Unit

A Title Bar. Contains an Icon, Text, and actions. Intended to be placed at the top of a widget.

Parameters
startIcon: ImageProvider

A tintable icon representing your app or brand.

title: String

Text to be displayed. Generally the name of your widget or app. Title should be shortened or omitted when the widget's width is narrow. The width can be checked using LocalSize.current.width

iconColor: ColorProvider? = GlanceTheme.colors.onSurface

The color which startIcon will be tinted.

textColor: ColorProvider = GlanceTheme.colors.onSurface

The color which title will be tinted.

modifier: GlanceModifier = GlanceModifier

GlanceModifier.

fontFamily: FontFamily? = null

Optional override for title's font family. Leave null to use the default.

actions: @Composable RowScope.() -> Unit = {}

A slot api for buttons. Use CircleIconButton with backgroundColor = null. Buttons will be placed in a Row.