> Documentation index: https://developer.android.com/reference/llms.txt

# GlanceAdaptiveWidgetManager

Artifact: [androidx.glance.adaptive:adaptive-core](https://developer.android.com/jetpack/androidx/releases/glance-adaptive.md.txt) [View Source](https://cs.android.com/search?q=file:androidx/glance/adaptive/core/GlanceAdaptiveWidgetManager.kt+class:androidx.glance.adaptive.core.GlanceAdaptiveWidgetManager) Added in [1.0.0-alpha05](https://developer.android.com/jetpack/androidx/releases/glance-adaptive.md.txt#1.0.0-alpha05)


```
class GlanceAdaptiveWidgetManager
```

<br />

*** ** * ** ***

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>` | `getActiveInstances(widgetName: String)` 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](https://developer.android.com/jetpack/androidx/releases/glance-adaptive.md.txt#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](https://developer.android.com/jetpack/androidx/releases/glance-adaptive.md.txt#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

Artifact: [androidx.glance.adaptive:adaptive-appwidget](https://developer.android.com/jetpack/androidx/releases/glance-adaptive.md.txt) [View Source](https://cs.android.com/search?q=file:androidx/glance/adaptive/appwidget/GlanceAdaptiveAppWidgetManager.kt+function: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`). |

| See also |
|---|---|
| `requestPinAppWidget` |   |

### GlanceAdaptiveWidgetManager.setConfigurationResult

Artifact: [androidx.glance.adaptive:adaptive-appwidget](https://developer.android.com/jetpack/androidx/releases/glance-adaptive.md.txt) [View Source](https://cs.android.com/search?q=file:androidx/glance/adaptive/appwidget/GlanceAdaptiveAppWidgetManager.kt+function: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`:

```kotlin
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. |

| See also |
|---|---|
| `onUpdate` |   |
| `getActiveInstances` |   |
| `pushUpdate` |   |

### GlanceAdaptiveWidgetManager.setPreview

Artifact: [androidx.glance.adaptive:adaptive-appwidget](https://developer.android.com/jetpack/androidx/releases/glance-adaptive.md.txt) [View Source](https://cs.android.com/search?q=file:androidx/glance/adaptive/appwidget/GlanceAdaptiveAppWidgetManager.kt+function: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. |

| See also |
|---|---|
| `setWidgetPreview` |   |
| `pushUpdate` |   |