GlanceAdaptiveWidgetReceiver

abstract class GlanceAdaptiveWidgetReceiver : AppWidgetProvider

kotlin.Any
   ↳ android.content.BroadcastReceiver
     ↳ android.appwidget.AppWidgetProvider
       ↳ androidx.glance.adaptive.appwidget.GlanceAdaptiveWidgetReceiver

AppWidgetProvider using Glance Adaptive to process widget lifecycle events and updates.

Subclass this receiver to associate a widget declared in AndroidManifest.xml with a widgetName. Rather than providing a custom GlanceAppWidget composable layout, applications push androidx.glance.adaptive.core.ui.templates.GlanceAdaptiveTemplate data via androidx.glance.adaptive.core.GlanceAdaptiveWidgetManager.pushUpdate, and the library adapts and renders the layout for each target surface.

This should typically be used as:

class MyGlanceAdaptiveWidgetReceiver : GlanceAdaptiveWidgetReceiver() {
    override val widgetName: String = "my_widget"
    override suspend fun onUpdate(context: Context) {
        GlanceAdaptiveWidgetManager(context).pushUpdate(
            widgetName = widgetName,
            currentData = ...
        )
    }
}

Include the Intent.ACTION_LOCALE_CHANGED action in the receiver declaration in AndroidManifest.xml so that widgets are updated when the device locale changes:

<receiver android:name=".MyGlanceAdaptiveWidgetReceiver" android:exported="true">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
        <action android:name="android.intent.action.LOCALE_CHANGED" />
    </intent-filter>
</receiver>

Note: If you override any methods of this class or AppWidgetProvider, ensure you call their superclass implementation. For the onUpdate flow managed by this receiver, do not call AppWidgetProvider.goAsync manually, as broadcast lifecycle completion is handled by the superclass implementation.

Summary

Constants
const String

Broadcast action to force a debug update of the Glance Adaptive widget via adb: adb shell am broadcast -a androidx.glance.adaptive.appwidget.action.DEBUG_UPDATE -n APP/COMPONENT
const String

Key for storing the widget instance identifier in the AppWidgetManager widget options bundle.

Public constructors

Public functions
open Unit
@CallSuper
onAppWidgetOptionsChanged(
    context: Context,
    appWidgetManager: AppWidgetManager,
    appWidgetId: Int,
    newOptions: Bundle
)
open Unit
@CallSuper
onDeleted(context: Context, appWidgetIds: IntArray)

Called when widget instances are deleted.
open Unit
onReceive(context: Context, intent: Intent)
open Unit
@CallSuper
onRestored(
    context: Context,
    oldWidgetIds: IntArray,
    newWidgetIds: IntArray
)
abstract suspend Unit
onUpdate(context: Context)

Called on a background coroutine when the system requests an update for this widget (such as on initial placement from the widget picker, device boot, locale or size changes, or periodic update alarms).
open Unit
@CallSuper
onUpdate(
    context: Context,
    appWidgetManager: AppWidgetManager,
    appWidgetIds: IntArray
)

Public properties
open CoroutineContext

Override coroutineContext to provide a custom CoroutineContext in which background update tasks are executed.
abstract String

Unique developer-defined identifier used to associate this receiver with a specific widget definition (e.g., "my_widget").

Inherited functions
From android.appwidget.AppWidgetProvider
Unit
onDisabled(context: Context)
Unit
onEnabled(context: Context)
From android.content.BroadcastReceiver
Unit
Unit
Bundle
BroadcastReceiver.PendingResult
IBinder
peekService(myContext: Context, service: Intent)
Unit
setOrderedHint(isOrdered: Boolean)
Unit
setResult(code: Int, data: String, extras: Bundle)
Unit

Inherited properties
From android.content.BroadcastReceiver
Boolean
Boolean
Boolean
Boolean
Int
String
open String?
open Int

Constants

ACTION_DEBUG_UPDATE

const val ACTION_DEBUG_UPDATE: String

Broadcast action to force a debug update of the Glance Adaptive widget via adb: adb shell am broadcast -a androidx.glance.adaptive.appwidget.action.DEBUG_UPDATE -n APP/COMPONENT

To target specific widget IDs, pass AppWidgetManager.EXTRA_APPWIDGET_IDS: adb shell am broadcast -a androidx.glance.adaptive.appwidget.action.DEBUG_UPDATE -n APP/COMPONENT --eia appWidgetIds 1,2

EXTRA_WIDGET_ID

const val EXTRA_WIDGET_ID: String

Key for storing the widget instance identifier in the AppWidgetManager widget options bundle.

Public constructors

GlanceAdaptiveWidgetReceiver

Added in 1.0.0-alpha04
GlanceAdaptiveWidgetReceiver()

Public functions

onAppWidgetOptionsChanged

@CallSuper
open fun onAppWidgetOptionsChanged(
    context: Context,
    appWidgetManager: AppWidgetManager,
    appWidgetId: Int,
    newOptions: Bundle
): Unit

onDeleted

@CallSuper
open fun onDeleted(context: Context, appWidgetIds: IntArray): Unit

Called when widget instances are deleted. Removes cached widget options associated with the deleted appWidgetIds from the internal cache.

If this method is overridden, super.onDeleted must be called to ensure internal cache cleanup.

onReceive

open fun onReceive(context: Context, intent: Intent): Unit

onRestored

@CallSuper
open fun onRestored(
    context: Context,
    oldWidgetIds: IntArray,
    newWidgetIds: IntArray
): Unit

onUpdate

Added in 1.0.0-alpha04
abstract suspend fun onUpdate(context: Context): Unit

Called on a background coroutine when the system requests an update for this widget (such as on initial placement from the widget picker, device boot, locale or size changes, or periodic update alarms).

Implement this method to fetch your widget data and call androidx.glance.adaptive.core.GlanceAdaptiveWidgetManager.pushUpdate.

Parameters
context: Context

The application Context.

onUpdate

@CallSuper
open fun onUpdate(
    context: Context,
    appWidgetManager: AppWidgetManager,
    appWidgetIds: IntArray
): Unit

Public properties

coroutineContext

Added in 1.0.0-alpha04
open val coroutineContext: CoroutineContext

Override coroutineContext to provide a custom CoroutineContext in which background update tasks are executed.

This context is used when launching the asynchronous broadcast block. It should include a dispatcher suitable for background work (e.g., Dispatchers.Default or Dispatchers.IO).

widgetName

Added in 1.0.0-alpha04
abstract val widgetName: String

Unique developer-defined identifier used to associate this receiver with a specific widget definition (e.g., "my_widget").

This identifier should correspond to the widget template definition or layout configuration registered with the adaptive widget framework.