GlanceAppWidgetManager

class GlanceAppWidgetManager


Manager for Glance App Widgets.

This is used to query the app widgets currently installed on the system, and some of their properties.

Summary

Public constructors

Public functions

Int

Retrieve the platform AppWidget ID from the provided GlanceId

suspend List<DpSize>

Retrieve the sizes for a given App Widget, if provided by the host.

GlanceId
getGlanceIdBy(appWidgetId: Int)

Retrieve the GlanceId of the provided AppWidget ID.

GlanceId?
getGlanceIdBy(configurationIntent: Intent)

Retrieve the GlanceId from the configuration activity intent or null if not valid

suspend List<GlanceId>
<T : GlanceAppWidget> getGlanceIds(provider: Class<T>)

Returns the GlanceId of the App Widgets installed for a particular provider.

suspend Boolean
<T : GlanceAppWidgetReceiver> requestPinGlanceAppWidget(
    receiver: Class<T>,
    preview: GlanceAppWidget?,
    previewState: Any?,
    successCallback: PendingIntent?
)

Request to pin the GlanceAppWidget of the given receiver on the current launcher (if supported).

suspend Boolean
<T : GlanceAppWidgetReceiver> requestPinGlanceAppWidget(
    receiver: Class<T>,
    preview: GlanceAppWidget?,
    previewSize: DpSize?,
    previewState: Any?,
    successCallback: PendingIntent?
)

Request to pin the GlanceAppWidget of the given receiver on the current launcher (if supported).

suspend Boolean
@RequiresApi(value = 35)
setWidgetPreviews(
    receiver: KClass<GlanceAppWidgetReceiver>,
    widgetCategories: IntSet
)

Generate and publish the widget previews for receiver for the given set of widgetCategories.

Extension functions

suspend inline Boolean
@RequiresApi(value = 35)
<T : GlanceAppWidgetReceiver> GlanceAppWidgetManager.setWidgetPreviews(
    widgetCategories: IntSet
)

Generate and publish the widget previews for a GlanceAppWidgetReceiver for the given set of widgetCategories.

Public constructors

GlanceAppWidgetManager

Added in 1.0.0
GlanceAppWidgetManager(context: Context)

Public functions

getAppWidgetId

Added in 1.0.0
fun getAppWidgetId(glanceId: GlanceId): Int

Retrieve the platform AppWidget ID from the provided GlanceId

Important: Do NOT use appwidget ID as identifier, instead create your own and store them in the GlanceStateDefinition. This method should only be used for compatibility or IPC communication reasons in conjunction with getGlanceIdBy

getAppWidgetSizes

suspend fun getAppWidgetSizes(glanceId: GlanceId): List<DpSize>

Retrieve the sizes for a given App Widget, if provided by the host.

The list of sizes will be extracted from the App Widget options bundle, using the content of AppWidgetManager.OPTION_APPWIDGET_SIZES if provided. If not, and if AppWidgetManager.OPTION_APPWIDGET_MIN_HEIGHT and similar are provided, the landscape and portrait sizes will be estimated from those and returned. Otherwise, the list will contain DpSize.Zero only.

getGlanceIdBy

Added in 1.0.0
fun getGlanceIdBy(appWidgetId: Int): GlanceId

Retrieve the GlanceId of the provided AppWidget ID.

Throws
kotlin.IllegalArgumentException

if the provided id is not associated with an existing GlanceId

getGlanceIdBy

Added in 1.0.0
fun getGlanceIdBy(configurationIntent: Intent): GlanceId?

Retrieve the GlanceId from the configuration activity intent or null if not valid

getGlanceIds

suspend fun <T : GlanceAppWidget> getGlanceIds(provider: Class<T>): List<GlanceId>

Returns the GlanceId of the App Widgets installed for a particular provider.

requestPinGlanceAppWidget

suspend fun <T : GlanceAppWidgetReceiver> requestPinGlanceAppWidget(
    receiver: Class<T>,
    preview: GlanceAppWidget? = null,
    previewState: Any? = null,
    successCallback: PendingIntent? = null
): Boolean

Request to pin the GlanceAppWidget of the given receiver on the current launcher (if supported).

Note: the request is only supported for SDK 26 and beyond, for lower versions this method will be no-op and return false.

Parameters
receiver: Class<T>

the target GlanceAppWidgetReceiver class

preview: GlanceAppWidget? = null

the instance of the GlanceAppWidget to compose the preview that will be shown in the request dialog. When not provided the app widget previewImage (as defined in the meta-data) will be used instead, or the app's icon if not available either.

previewState: Any? = null

the state (as defined by the GlanceAppWidget.stateDefinition to use for the preview

successCallback: PendingIntent? = null

a PendingIntent to be invoked if the app widget pinning is accepted by the user

Returns
Boolean

true if the request was successfully sent to the system, false otherwise

See also
requestPinAppWidget

for more information and limitations

requestPinGlanceAppWidget

suspend fun <T : GlanceAppWidgetReceiver> requestPinGlanceAppWidget(
    receiver: Class<T>,
    preview: GlanceAppWidget? = null,
    previewSize: DpSize? = null,
    previewState: Any? = null,
    successCallback: PendingIntent? = null
): Boolean

Request to pin the GlanceAppWidget of the given receiver on the current launcher (if supported).

Note: the request is only supported for SDK 26 and beyond, for lower versions this method will be no-op and return false.

Parameters
receiver: Class<T>

the target GlanceAppWidgetReceiver class

preview: GlanceAppWidget? = null

the instance of the GlanceAppWidget to compose the preview that will be shown in the request dialog. When not provided the app widget previewImage (as defined in the meta-data) will be used instead, or the app's icon if not available either.

previewSize: DpSize? = null

the size to be used for the preview. If none is provided, the widget's minimum size (as determined by its' AppWidgetProviderInfo) will be used.

previewState: Any? = null

the state (as defined by the GlanceAppWidget.stateDefinition to use for the preview

successCallback: PendingIntent? = null

a PendingIntent to be invoked if the app widget pinning is accepted by the user

Returns
Boolean

true if the request was successfully sent to the system, false otherwise

See also
requestPinAppWidget

for more information and limitations

setWidgetPreviews

@RequiresApi(value = 35)
suspend fun setWidgetPreviews(
    receiver: KClass<GlanceAppWidgetReceiver>,
    widgetCategories: IntSet = intSetOf( WIDGET_CATEGORY_HOME_SCREEN or WIDGET_CATEGORY_KEYGUARD or WIDGET_CATEGORY_SEARCHBOX )
): Boolean

Generate and publish the widget previews for receiver for the given set of widgetCategories. Previews are generated from the layout provided by GlanceAppWidget.providePreview on the widget connected to the given receiver.

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. By default, a single preview is generated for all widget categories, i.e. widgetsCategories = intSetOf(WIDGET_CATEGORY_HOME_SCREEN or WIDGET_CATEGORY_KEYGUARD or WIDGET_CATEGORY_SEARCHBOX). To generate a separate preview for each widget category, pass each category as a separate item in the int set, e.g. intSetOf(WIDGET_CATEGORY_HOME_SCREEN, WIDGET_CATEGORY_KEYGUARD). This is only necessary if you want to generate different layouts for the different 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
receiver: KClass<GlanceAppWidgetReceiver>

the GlanceAppWidgetReceiver which holds the GlanceAppWidget to run. This receiver must be registered as an app widget provider in the application manifest.

widgetCategories: IntSet = intSetOf( WIDGET_CATEGORY_HOME_SCREEN or WIDGET_CATEGORY_KEYGUARD or WIDGET_CATEGORY_SEARCHBOX )

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
Boolean

true if the preview was successfully updated, false if otherwise. AppWidgetManager.setWidgetPreview will return false 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.

Extension functions

setWidgetPreviews

@RequiresApi(value = 35)
suspend inline fun <T : GlanceAppWidgetReceiver> GlanceAppWidgetManager.setWidgetPreviews(
    widgetCategories: IntSet = intSetOf( WIDGET_CATEGORY_HOME_SCREEN or WIDGET_CATEGORY_KEYGUARD or WIDGET_CATEGORY_SEARCHBOX )
): Boolean

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: IntSet = intSetOf( WIDGET_CATEGORY_HOME_SCREEN or WIDGET_CATEGORY_KEYGUARD or WIDGET_CATEGORY_SEARCHBOX )

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
Boolean

true if the preview was successfully updated, false if otherwise. AppWidgetManager.setWidgetPreview will return false 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.