---
title: "GlanceAppWidget"
description: "Object handling the composition and the communication with [AppWidgetManager].

The UI is defined by calling [provideContent] from within [provideGlance]. When the widget is
requested, the composition is run and translated into a [RemoteViews] which is then sent to the
[AppWidgetManager]."
type: "class"
---

<div class='type'>Class</div>


<a id='references'></a>

<div class='sourceset sourceset-android'>Android</div>


```kotlin
public abstract class GlanceAppWidget(
    @LayoutRes internal open val errorUiLayout: Int = R.layout.glance_error_layout
)
```


Object handling the composition and the communication with `AppWidgetManager`.

The UI is defined by calling `provideContent` from within `provideGlance`. When the widget is
requested, the composition is run and translated into a `RemoteViews` which is then sent to the
`AppWidgetManager`.

#### Parameters

| | |
| --- | --- |
| errorUiLayout | Used by `onCompositionError`. When `onCompositionError` is called, it will, unless overridden, update the appwidget to display error UI using this layout resource ID, unless `errorUiLayout` is 0, in which case the error will be rethrown. If `onCompositionError` is overridden, `errorUiLayout` will not be read.. |



## Functions

```kotlin
@RestrictTo(Scope.LIBRARY_GROUP)
    public open fun getSessionManager(context: Context): SessionManager
```

```kotlin
public abstract suspend fun provideGlance(context: Context, id: GlanceId)
```


Override this function to provide the Glance Composable.

This is a good place to load any data needed to render the Composable. Use `provideContent`
to provide the Composable once the data is ready.

`provideGlance` is run in the background as a `androidx.work.CoroutineWorker` in response to
calls to `update` and `updateAll`, as well as requests from the Launcher. Before
`provideContent` is called, `provideGlance` is subject to the typical
`androidx.work.WorkManager` time limit (currently ten minutes). After `provideContent` is
called, the composition continues to run and recompose for about 45 seconds. When UI
interactions or update requests are received, additional time is added to process these
requests.

Note: `update` and `updateAll` do not restart `provideGlance` if it is already running. As a
result, you should load initial data before calling `provideContent`, and then observe your
sources of data within the composition (e.g. `androidx.compose.runtime.collectAsState`). This
ensures that your widget will continue to update while the composition is active. When you
update your data source from elsewhere in the app, make sure to call `update` in case a
Worker for this widget is not currently running.


```kotlin
public open suspend fun providePreview(context: Context, widgetCategory: Int)
```


Override this function to provide a Glance Composable that will be used when running this
widget in preview mode. Use `provideContent` to provide the composable once the data is
ready.

In order to generate and publish the previews for a provider, use `setWidgetPreviews`. You
can use `composeForPreview` to generate a `RemoteViews` from this Composable without
publishing it.

The given `widgetCategory` value will be one of
`AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN`,
`AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD`, or
`AppWidgetProviderInfo.WIDGET_CATEGORY_SEARCHBOX`, or some combination of all three. This
indicates what kind of widget host this preview can be used for. `widgetCategory` corresponds
to the categories passed to `setWidgetPreviews`.


```kotlin
public open suspend fun onDelete(context: Context, glanceId: GlanceId)
```


Method called by the framework when an App Widget has been removed from its host.

When the method returns, the state associated with the `glanceId` will be deleted.


```kotlin
public suspend fun update(context: Context, id: GlanceId)
```


Run the composition in `provideGlance` and send the result to `AppWidgetManager`.


```kotlin
@Throws(Throwable::class)
    public open fun onCompositionError(
        context: Context,
        glanceId: GlanceId,
        appWidgetId: Int,
        throwable: Throwable,
    )
```


A callback invoked when the `AppWidgetSession` encounters an exception. At this point, the
session will be closed down. The default implementation of this method creates a
`RemoteViews` from `errorUiLayout` and sets this as the widget's content.

This method should be overridden if you want to log the error, create a custom error layout,
or attempt to recover from or ignore the error by updating the widget's view state and then
restarting composition.

#### Parameters

| | |
| --- | --- |
| context | Context. |
| glanceId | The `GlanceId` of the widget experiencing the error. |
| appWidgetId | The appWidgetId of the widget experiencing the error. This is provided as a convenience in addition to `GlanceId`. |
| throwable | The exception that was caught by `AppWidgetSession` |



```kotlin
@RestrictTo(Scope.LIBRARY_GROUP)
    public open fun getComponents(context: Context): GlanceComponents?
```


Override this function to specify the components that will be used for actions and
RemoteViewsService. All of the components must run in the same process.

If null, then the default components will be used.