GlanceAppWidget

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

Properties

open val sizeMode: SizeMode

Defines the handling of sizes.

open val previewSizeMode: PreviewSizeMode

Defines handling of sizes for previews.

open val stateDefinition: GlanceStateDefinition<*>?

Data store for widget data specific to the view.

Functions

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

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.

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.

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.

suspend fun update(context: Context, id: GlanceId)

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

@Throws(Throwable::class)
    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

@RestrictTo(Scope.LIBRARY_GROUP)
    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.