GlanceAdaptiveWidgetManager

class GlanceAdaptiveWidgetManager


Entry point for managing Glance Adaptive widgets.

Only operations supported by every surface are members of this class. Surface-specific operations, such as setting dynamic widget picker previews on phones, are provided as extension functions by the corresponding surface artifact (for example adaptive-appwidget).

Summary

Public functions

suspend List<WidgetInstanceInfo>

Returns the active widget instances matching widgetName currently placed on host surfaces of this device.

suspend Unit
pushUpdate(widgetName: String, currentData: GlanceAdaptiveTemplate)

Pushes the current data updates to all placed instances matching widgetName.

suspend Unit
pushUpdate(
    widgetName: String,
    widgetIds: Set<String>,
    currentData: GlanceAdaptiveTemplate
)

Pushes the current data updates to the specified widget instances.

Extension functions

suspend Boolean
GlanceAdaptiveWidgetManager.requestPin(
    widgetName: String,
    widgetId: String?,
    initialData: GlanceAdaptiveTemplate?,
    options: Bundle
)

Requests to pin the widget matching widgetName on the host (if supported).

Unit
GlanceAdaptiveWidgetManager.setConfigurationResult(
    activity: Activity,
    widgetId: String?,
    options: Bundle
)

Completes the configuration of a widget instance from within its configuration Activity.

suspend Unit
GlanceAdaptiveWidgetManager.setPreview(
    widgetName: String,
    previewData: GlanceAdaptiveTemplate
)

Sets dynamic preview data rendered in host widget pickers for the specified widgetName.

Public functions

getActiveInstances

suspend fun getActiveInstances(widgetName: String): List<WidgetInstanceInfo>

Returns the active widget instances matching widgetName currently placed on host surfaces of this device.

Instances are keyed by their widget instance String identifier. A single identifier can be placed more than once, so each returned WidgetInstanceInfo reports how many placements it has on each host surface through WidgetInstanceInfo.placementsPerSurface.

Placements that have not yet been assigned a widget instance String identifier are omitted, as they cannot be targeted by pushUpdate. They are still updated by pushUpdate calls that do not target identifiers, and are returned as soon as GlanceAdaptiveWidgetReceiver assigns them one.

Parameters
widgetName: String

Developer widget definition String identifier matching GlanceAdaptiveWidgetReceiver.widgetName.

Returns
List<WidgetInstanceInfo>

Active instances for widgetName, or an empty list if none are placed or have an assigned identifier yet.

Throws
IllegalArgumentException

if widgetName does not identify exactly one widget of the app.

IllegalStateException

if a widget of the app cannot be read to resolve widgetName.

RuntimeException

if the placements or their options cannot be read, rather than returning a partial result.

pushUpdate

Added in 1.0.0-alpha05
suspend fun pushUpdate(widgetName: String, currentData: GlanceAdaptiveTemplate): Unit

Pushes the current data updates to all placed instances matching widgetName.

Parameters
widgetName: String

Developer widget definition String identifier matching GlanceAdaptiveWidgetReceiver.widgetName.

currentData: GlanceAdaptiveTemplate

The declarative template data payload implementing GlanceAdaptiveTemplate.

Throws
IllegalArgumentException

if widgetName does not identify exactly one widget of the app.

IllegalStateException

if a widget of the app cannot be read to resolve widgetName.

GlanceAdaptiveUpdateException

if some placements could not be updated, once every placement has been attempted. It lists the widget instances to retry.

pushUpdate

Added in 1.0.0-alpha05
suspend fun pushUpdate(
    widgetName: String,
    widgetIds: Set<String>,
    currentData: GlanceAdaptiveTemplate
): Unit

Pushes the current data updates to the specified widget instances.

Parameters
widgetName: String

Developer widget definition String identifier matching GlanceAdaptiveWidgetReceiver.widgetName.

widgetIds: Set<String>

Target widget instance String identifiers to update. Passing an explicit empty collection restricts updates strictly to zero instances. Blank identifiers are not allowed.

currentData: GlanceAdaptiveTemplate

The declarative template data payload implementing GlanceAdaptiveTemplate.

Throws
IllegalArgumentException

if widgetIds contains a blank identifier, or if widgetName does not identify exactly one widget of the app.

IllegalStateException

if a widget of the app cannot be read to resolve widgetName.

GlanceAdaptiveUpdateException

if some placements could not be updated, once every placement has been attempted. It lists the widget instances to retry.

Extension functions

GlanceAdaptiveWidgetManager.requestPin

suspend fun GlanceAdaptiveWidgetManager.requestPin(
    widgetName: String,
    widgetId: String? = null,
    initialData: GlanceAdaptiveTemplate? = null,
    options: Bundle = Bundle.EMPTY
): Boolean

Requests to pin the widget matching widgetName on the host (if supported).

It is up to the launcher to accept the request, typically after asking the user to confirm, so true only means that the request was handed to the launcher. There is no success or failure callback: once pinned, the widget is updated through GlanceAdaptiveWidgetReceiver.onUpdate like a widget placed from the picker, and the platform reports nothing if the user dismisses the request. Every failure that can happen before the request is shown throws from this call.

Pinning is only supported by AppWidget hosts, so this operation is provided by this artifact as an extension rather than by GlanceAdaptiveWidgetManager itself.

On devices running Android 7.1 and earlier (pre-API 26), pinning is not supported by the platform and this returns false. It also returns false if the launcher does not support pinning, if the receiver declaring widgetName is disabled, or if the launcher refuses the request.

widgetId and options are stored in the options of the pinned widget once the launcher reports its appWidgetId, which the platform does only once. If that report is lost, or storing them keeps failing, the widget keeps the widgetId generated by GlanceAdaptiveWidgetReceiver and does not receive options, so render a sensible default for an unknown widgetId.

widgetId may already be used by placed widgets: every widget sharing a widgetId receives the updates targeted at it.

Parameters
widgetName: String

Developer widget definition String identifier matching GlanceAdaptiveWidgetReceiver.widgetName.

widgetId: String? = null

Optional developer-assigned widget instance String identifier for the pinned widget. If omitted, a unique identifier is generated. It must not be blank.

initialData: GlanceAdaptiveTemplate? = null

Optional declarative template data payload implementing GlanceAdaptiveTemplate to render as the preview shown while the launcher asks the user to confirm. If omitted, the launcher shows the preview declared by the widget instead.

options: Bundle = Bundle.EMPTY

Optional initial configuration options to store in the options of the pinned widget.

Returns
Boolean

true if the request was handed to the launcher, false otherwise.

Throws
IllegalArgumentException

if widgetId is blank, if widgetName cannot be resolved (see GlanceAdaptiveWidgetReceiver.widgetName), or if its provider does not declare the home screen widget category.

IllegalStateException

if this manager was not created for AppWidget hosts, if the app has no foreground activity or foreground service, or if widgetName cannot be resolved (see GlanceAdaptiveWidgetReceiver.widgetName).

GlanceAdaptiveWidgetManager.setConfigurationResult

fun GlanceAdaptiveWidgetManager.setConfigurationResult(
    activity: Activity,
    widgetId: String? = null,
    options: Bundle = Bundle.EMPTY
): Unit

Completes the configuration of a widget instance from within its configuration Activity.

Stores widgetId and options in the options of the widget being configured, then sets the Activity.RESULT_OK result expected by the AppWidget host. Call this before Activity.finish. This automatically triggers GlanceAdaptiveWidgetReceiver.onUpdate, where the configured widgetId and options are available via GlanceAdaptiveWidgetManager.getActiveInstances. Unlike standard android.appwidget.AppWidgetProvider configuration activities, callers do not need to push an initial widget update before finishing the Activity.

Failures to read or store the options of the widget are propagated, and the result is not set if this throws. Exceptions reach the caller, never the host: if the Activity then finishes without Activity.RESULT_OK, the host removes a newly placed widget, or keeps the previous configuration of a reconfigured one.

Example usage in a configuration Activity:

GlanceAdaptiveWidgetManager(this).setConfigurationResult(
activity = this,
widgetId = "bucharest_weather",
options = bundleOf("location_id" to "bucharest"),
)

finish()
Parameters
activity: Activity

Configuration Activity started with android.appwidget.AppWidgetManager.ACTION_APPWIDGET_CONFIGURE.

widgetId: String? = null

Optional developer-assigned widget instance String identifier for the configured widget. If omitted, the one already stored for the widget is kept, or a unique identifier is generated if there is none. It must not be blank.

options: Bundle = Bundle.EMPTY

Optional configuration options to store in the options of the configured widget.

Throws
IllegalArgumentException

if activity's intent does not carry a valid android.appwidget.AppWidgetManager.EXTRA_APPWIDGET_ID, or if widgetId is blank.

IllegalStateException

if this manager was not created for AppWidget hosts.

GlanceAdaptiveWidgetManager.setPreview

suspend fun GlanceAdaptiveWidgetManager.setPreview(
    widgetName: String,
    previewData: GlanceAdaptiveTemplate
): Unit

Sets dynamic preview data rendered in host widget pickers for the specified widgetName.

On devices running Android 14 and earlier (pre-API 35), dynamic widget previews are not supported by the platform and this operation completes as a safe no-op, once widgetName has been resolved.

Each call counts against the platform's preview update rate limit, so call this only when the preview content changes, for example after a data change rather than on every app start.

Picker categories with the same layout, such as home screen and search box, are set with one platform call. Categories with different layouts, such as home screen and keyguard, are set independently: once every category has been attempted, the first failure is thrown with the others attached as suppressed exceptions. If the platform rejects a preview, typically because of its rate limit, the remaining categories are not attempted, as they would be rejected too. A failure never clears a preview: the picker keeps the last accepted one, or the static preview declared by the widget.

Parameters
widgetName: String

Developer widget definition String identifier matching GlanceAdaptiveWidgetReceiver.widgetName.

previewData: GlanceAdaptiveTemplate

Declarative template data payload implementing GlanceAdaptiveTemplate to render as a preview.

Throws
IllegalArgumentException

if widgetName cannot be resolved, see GlanceAdaptiveWidgetReceiver.widgetName.

IllegalStateException

if this manager was not created for AppWidget hosts, if widgetName cannot be resolved (see GlanceAdaptiveWidgetReceiver.widgetName), or if the platform rejects a preview, typically because of its rate limit. Do not retry immediately: call this again only when the preview content changes.