---
title: "setWidgetPreviews"
description: "Generate and publish the widget previews for a [GlanceAppWidgetReceiver] for the given set of
[widgetCategories]. Previews are generated from the layout provided by
[GlanceAppWidget.providePreview] on the widget connected to the given [GlanceAppWidgetReceiver]
class. This receiver must be registered as an app widget provider in the application manifest.

Previews should be published during the initial setup phase or launch of your app. To avoid
running this unnecessarily, you can see what previews are currently published for your provider
by checking [AppWidgetProviderInfo.generatedPreviewCategories].

The preview composition is run for each value in the [widgetCategories] array. If your widget has
the same layout across categories, you can combine all of the categories in a single value, e.g.
`WIDGET_CATEGORY_HOME_SCREEN or WIDGET_CATEGORY_KEYGUARD or WIDGET_CATEGORY_SEARCHBOX`, which
will call [composeForPreview] once and set the previews for all of the categories.

Note that this API is only available on [Build.VERSION_CODES.VANILLA_ICE_CREAM] and above, so you
will likely want to set [AppWidgetProviderInfo.previewLayout] and
[AppWidgetProviderInfo.previewImage] as well to have the most coverage across versions.

See also [AppWidgetProviderInfo.generatedPreviewCategories], [AppWidgetManager.setWidgetPreview],
[AppWidgetManager.getWidgetPreview], and [AppWidgetManager.removeWidgetPreview]."
type: "function"
---

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


<a id='references'></a>
<div class='sourceset sourceset-android'>Android</div>


```kotlin
@RequiresApi(Build.VERSION_CODES.VANILLA_ICE_CREAM)
@CheckResult
public suspend inline fun <reified T : GlanceAppWidgetReceiver> GlanceAppWidgetManager
    .setWidgetPreviews(
    widgetCategories: IntSet =
        intSetOf(
            WIDGET_CATEGORY_HOME_SCREEN or WIDGET_CATEGORY_KEYGUARD or WIDGET_CATEGORY_SEARCHBOX
        )
): @GlanceAppWidgetManager.SetWidgetPreviewsResult Int
```


Generate and publish the widget previews for a `GlanceAppWidgetReceiver` for the given set of
`widgetCategories`. Previews are generated from the layout provided by
`GlanceAppWidget.providePreview` on the widget connected to the given `GlanceAppWidgetReceiver`
class. This receiver must be registered as an app widget provider in the application manifest.

Previews should be published during the initial setup phase or launch of your app. To avoid
running this unnecessarily, you can see what previews are currently published for your provider
by checking `AppWidgetProviderInfo.generatedPreviewCategories`.

The preview composition is run for each value in the `widgetCategories` array. If your widget has
the same layout across categories, you can combine all of the categories in a single value, e.g.
`WIDGET_CATEGORY_HOME_SCREEN or WIDGET_CATEGORY_KEYGUARD or WIDGET_CATEGORY_SEARCHBOX`, which
will call `composeForPreview` once and set the previews for all of the categories.

Note that this API is only available on `Build.VERSION_CODES.VANILLA_ICE_CREAM` and above, so you
will likely want to set `AppWidgetProviderInfo.previewLayout` and
`AppWidgetProviderInfo.previewImage` as well to have the most coverage across versions.

See also `AppWidgetProviderInfo.generatedPreviewCategories`, `AppWidgetManager.setWidgetPreview`,
`AppWidgetManager.getWidgetPreview`, and `AppWidgetManager.removeWidgetPreview`.

#### Parameters

| | |
| --- | --- |
| widgetCategories | the widget categories for which to set previews. Each element of this set must be a combination of `WIDGET_CATEGORY_HOME_SCREEN`, `WIDGET_CATEGORY_KEYGUARD`, or `WIDGET_CATEGORY_SEARCHBOX`. |


#### Returns

| | |
| --- | --- |
|  | `GlanceAppWidgetManager.SET_WIDGET_PREVIEWS_RESULT_SUCCESS` if the preview was successfully updated. Returns `GlanceAppWidgetManager.SET_WIDGET_PREVIEWS_RESULT_RATE_LIMITED` when the caller has hit a system-defined rate limit on setting previews for a particular provider. In this case, you may opt to schedule a task in the future to try again, if necessary. |




## Code Examples
### setWidgetPreviews
```kotlin
suspend fun setWidgetPreviews(context: Context) {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
        return
    }
    fun Class<GlanceAppWidgetReceiver>.hasPreviewForCategory(widgetCategory: Int): Boolean {
        val component = ComponentName(context, this)
        val providerInfo =
            (context.getSystemService(Context.APPWIDGET_SERVICE) as AppWidgetManager)
                .installedProviders
                .first { providerInfo -> providerInfo.provider == component }
        return providerInfo.generatedPreviewCategories.and(widgetCategory) != 0
    }
    val receiverClasses = listOf<Class<GlanceAppWidgetReceiver>>()
    val glanceAppWidgetManager = GlanceAppWidgetManager(context)
    withContext(Dispatchers.Default) {
        try {
            for (receiver in receiverClasses) {
                if (receiver.hasPreviewForCategory(WIDGET_CATEGORY_HOME_SCREEN)) {
                    Log.i("Widget", "Skipped updating previews for $receiver")
                    continue
                }
                if (
                    glanceAppWidgetManager.setWidgetPreviews(receiver.kotlin) ==
                        SET_WIDGET_PREVIEWS_RESULT_RATE_LIMITED
                ) {
                    Log.e("Widget", "Failed to set previews for $receiver, rate limited")
                }
            }
        } catch (e: Exception) {
            Log.e("Widget", "Error thrown when calling setWidgetPreview", e)
        }
    }
}
```