androidx.glance

Interfaces

GlanceId

Opaque object used to describe a glance view.

GlanceModifier

An ordered, immutable, collection of modifier element for the Glance library.

GlanceModifier.Element

A single element contained within a GlanceModifier chain.

ImageProvider

Interface representing an Image source which can be used with a Glance Image element.

Classes

ButtonColors

Represents the colors used to style a button, prefer this to using the modifier.

ColorFilter

Effects used to modify the color of an image.

CombinedGlanceModifier

A node in a GlanceModifier chain.

Objects

ButtonDefaults

Contains the default values used by Button.

GlanceModifier.Companion

The companion object Modifier is the empty, default, or starter GlanceModifier that contains no elements.

GlanceTheme

Object that provides access to the current theme.

Annotations

ExperimentalGlanceApi
GlanceComposable

An annotation that can be used to mark a composable function as being expected to be use in a composable function that is also marked or inferred to be marked as a GlanceComposable.

Enums

Visibility

Value of the visibility field for a node in the composition tree.

Top-level functions summary

Unit
@Composable
Button(
    text: String,
    onClick: Action,
    modifier: GlanceModifier,
    enabled: Boolean,
    style: TextStyle?,
    colors: ButtonColors,
    maxLines: Int
)

Adds a button view to the glance view.

Unit
@Composable
Button(
    text: String,
    onClick: () -> Unit,
    modifier: GlanceModifier,
    enabled: Boolean,
    style: TextStyle?,
    colors: ButtonColors,
    maxLines: Int
)

Adds a button view to the glance view.

Unit
@ExperimentalGlanceApi
@Composable
Button(
    text: String,
    onClick: () -> Unit,
    modifier: GlanceModifier,
    enabled: Boolean,
    style: TextStyle?,
    colors: ButtonColors,
    maxLines: Int,
    key: String?
)

Adds a button view to the glance view.

Unit
@Composable
GlanceTheme(
    colors: ColorProviders,
    content: @GlanceComposable @Composable () -> Unit
)

A top level theme for Glance code.

Unit
@Composable
Image(
    provider: ImageProvider,
    contentDescription: String?,
    modifier: GlanceModifier,
    contentScale: ContentScale,
    colorFilter: ColorFilter?
)

A composable which lays out and draws the image specified in provider.

ImageProvider

Image resource from a bitmap.

ImageProvider
@RequiresApi(value = 23)
ImageProvider(icon: Icon)

Image resource from an icon.

ImageProvider

Image resource from an Android Drawable resource.

inline T

Retrieves the current customizable store for view specific state data as defined by GlanceStateDefinition in the surface implementation.

inline T?

Retrieves the current Preferences value of the provided Preferences.Key from the current state when Preferences store is used as GlanceStateDefinition in the surface implementation.

Extension functions summary

GlanceModifier

Apply a background color to the element this modifier is attached to.

GlanceModifier

Apply a background color to the element this modifier is attached to.

GlanceModifier

Apply a background color to the element this modifier is attached to.

GlanceModifier
GlanceModifier.background(
    imageProvider: ImageProvider,
    contentScale: ContentScale,
    colorFilter: ColorFilter?
)

Apply a background image to the element this modifier is attached to.

GlanceModifier

Change the visibility of the current node.

Top-level properties summary

ProvidableCompositionLocal<Context>

Context of application when generating the glance view.

ProvidableCompositionLocal<GlanceId>

Unique Id for the glance view being generated by the current composition.

ProvidableCompositionLocal<DpSize>

Size of the glance view being generated.

ProvidableCompositionLocal<Any?>

Local view state, defined in surface implementation.

Top-level functions

Button

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

Adds a button view to the glance view.

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.

style: TextStyle? = null

The style to be applied to the text in this button.

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.

Button

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

Adds a button view to the glance view.

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.

style: TextStyle? = null

The style to be applied to the text in this button.

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.

Button

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

Adds a button view to the glance view.

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.

style: TextStyle? = null

The style to be applied to the text in this button.

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.

GlanceTheme

@Composable
fun GlanceTheme(
    colors: ColorProviders = LocalColors.current,
    content: @GlanceComposable @Composable () -> Unit
): Unit

A top level theme for Glance code. Unlike a standard compose theme, this only provides color. Like a standard compose theme, it should be at the top level of a compose hierarchy with all themed UI provided as content.

@Composable
fun Image(
    provider: ImageProvider,
    contentDescription: String?,
    modifier: GlanceModifier = GlanceModifier,
    contentScale: ContentScale = ContentScale.Fit,
    colorFilter: ColorFilter? = null
): Unit

A composable which lays out and draws the image specified in provider. This will attempt to lay out the image using the intrinsic width and height of the provided image, but this can be overridden by using a modifier to set the width or height of this element.

Parameters
provider: ImageProvider

The image provider to use to draw the image

contentDescription: String?

text used by accessibility services to describe what this image represents. This should always be provided unless this image is used for decorative purposes, and does not represent a meaningful action that a user can take. This text should be localized.

modifier: GlanceModifier = GlanceModifier

Modifier used to adjust the layout algorithm or draw decoration content.

contentScale: ContentScale = ContentScale.Fit

How to lay the image out with respect to its bounds, if the bounds are smaller than the image.

colorFilter: ColorFilter? = null

The effects to use to modify the color of an image.

ImageProvider

fun ImageProvider(bitmap: Bitmap): ImageProvider

Image resource from a bitmap.

Parameters
bitmap: Bitmap

The bitmap to be displayed.

ImageProvider

@RequiresApi(value = 23)
fun ImageProvider(icon: Icon): ImageProvider

Image resource from an icon.

Parameters
icon: Icon

The icon to be displayed.

ImageProvider

fun ImageProvider(resId: @DrawableRes Int): ImageProvider

Image resource from an Android Drawable resource.

Parameters
resId: @DrawableRes Int

The resource ID of the Drawable resource to be used.

currentState

@Composable
inline fun <T : Any?> currentState(): T

Retrieves the current customizable store for view specific state data as defined by GlanceStateDefinition in the surface implementation.

Returns
T

the current store of the provided type T

currentState

@Composable
inline fun <T : Any?> currentState(key: Preferences.Key<T>): T?

Retrieves the current Preferences value of the provided Preferences.Key from the current state when Preferences store is used as GlanceStateDefinition in the surface implementation.

Parameters
key: Preferences.Key<T>

the Preferences.Key to retrieve its value

Returns
T?

the stored value or null if not available.

Extension functions

background

fun GlanceModifier.background(color: Color): GlanceModifier

Apply a background color to the element this modifier is attached to. This will cause the element to paint the specified Color as its background, which will fill the bounds of the element.

Parameters
color: Color

The color to set as the background.

background

fun GlanceModifier.background(color: @ColorRes Int): GlanceModifier

Apply a background color to the element this modifier is attached to. This will cause the element to paint the specified color resource as its background, which will fill the bounds of the element.

Parameters
color: @ColorRes Int

The color resource to set as the background.

background

fun GlanceModifier.background(colorProvider: ColorProvider): GlanceModifier

Apply a background color to the element this modifier is attached to. This will cause the element to paint the specified ColorProvider as its background, which will fill the bounds of the element.

Parameters
colorProvider: ColorProvider

The color to set as the background

background

fun GlanceModifier.background(
    imageProvider: ImageProvider,
    contentScale: ContentScale = ContentScale.FillBounds,
    colorFilter: ColorFilter? = null
): GlanceModifier

Apply a background image to the element this modifier is attached to.

Parameters
imageProvider: ImageProvider

The content to set as the background

contentScale: ContentScale = ContentScale.FillBounds

scaling to apply to the imageProvider.

colorFilter: ColorFilter? = null

Optional color filter to apply to imageProvider, such as tint.

visibility

fun GlanceModifier.visibility(visibility: Visibility): GlanceModifier

Change the visibility of the current node.

Parameters
visibility: Visibility

New visibility of the node.

Top-level properties

LocalContext

val LocalContextProvidableCompositionLocal<Context>

Context of application when generating the glance view.

LocalGlanceId

val LocalGlanceIdProvidableCompositionLocal<GlanceId>

Unique Id for the glance view being generated by the current composition.

LocalSize

val LocalSizeProvidableCompositionLocal<DpSize>

Size of the glance view being generated.

The glance view will have at least that much space to be displayed. The exact meaning may changed depending on the surface and how it is configured.

LocalState

val LocalStateProvidableCompositionLocal<Any?>

Local view state, defined in surface implementation. A customizable store for view specific state data.