AppWidgetManager

ACTION_APPWIDGET_BIND

static val ACTION_APPWIDGET_BIND: String

Activity action to launch from your AppWidgetHost activity when you want to bind an AppWidget to display and bindAppWidgetIdIfAllowed returns false.

You must supply the following extras:

The system will respond with an onActivityResult call with the following extras in the intent:

When you receive the result from the AppWidget bind activity, if the resultCode is android.app.Activity#RESULT_OK, the AppWidget has been bound. You should then check the AppWidgetProviderInfo for the returned AppWidget, and if it has one, launch its configuration activity. If android.app.Activity#RESULT_CANCELED is returned, you should delete the appWidgetId.

Value: "android.appwidget.action.APPWIDGET_BIND"

ACTION_APPWIDGET_CONFIGURE

static val ACTION_APPWIDGET_CONFIGURE: String

Sent when it is time to configure your AppWidget while it is being added to a host. This action is not sent as a broadcast to the AppWidget provider, but as a startActivity to the activity specified in the meta-data.

The intent will contain the following extras:

If you return android.app.Activity#RESULT_OK using android.app.Activity#setResult, the AppWidget will be added, and you will receive an ACTION_APPWIDGET_UPDATE broadcast for this AppWidget. If you return android.app.Activity#RESULT_CANCELED, the host will cancel the add and not display this AppWidget, and you will receive a ACTION_APPWIDGET_DELETED broadcast.

Value: "android.appwidget.action.APPWIDGET_CONFIGURE"

ACTION_APPWIDGET_DELETED

static val ACTION_APPWIDGET_DELETED: String

Sent when an instance of an AppWidget is deleted from its host.

This is a protected intent that can only be sent by the system.

Value: "android.appwidget.action.APPWIDGET_DELETED"

ACTION_APPWIDGET_DISABLED

static val ACTION_APPWIDGET_DISABLED: String

Sent when the last AppWidget of this provider is removed from the last host.

This is a protected intent that can only be sent by the system.

Value: "android.appwidget.action.APPWIDGET_DISABLED"

ACTION_APPWIDGET_ENABLED

static val ACTION_APPWIDGET_ENABLED: String

Sent when an instance of an AppWidget is added to a host for the first time. This broadcast is sent at boot time if there is a AppWidgetHost installed with an instance for this provider.

This is a protected intent that can only be sent by the system.

Value: "android.appwidget.action.APPWIDGET_ENABLED"

ACTION_APPWIDGET_HOST_RESTORED

static val ACTION_APPWIDGET_HOST_RESTORED: String

Sent to widget hosts after AppWidget state related to the host has been restored from backup. The intent contains information about how to translate AppWidget ids from the restored data to their new equivalents. If an application maintains multiple separate widget host instances, it will receive this broadcast separately for each one.

The intent will contain the following extras:

This is a protected intent that can only be sent by the system.

Value: "android.appwidget.action.APPWIDGET_HOST_RESTORED"

ACTION_APPWIDGET_OPTIONS_CHANGED

static val ACTION_APPWIDGET_OPTIONS_CHANGED: String

Sent when the custom extras for an AppWidget change.

This is a protected intent that can only be sent by the system.

Value: "android.appwidget.action.APPWIDGET_UPDATE_OPTIONS"

ACTION_APPWIDGET_PICK

static val ACTION_APPWIDGET_PICK: String

Activity action to launch from your AppWidgetHost activity when you want to pick an AppWidget to display. The AppWidget picker activity will be launched.

You must supply the following extras:

The system will respond with an onActivityResult call with the following extras in the intent:

When you receive the result from the AppWidget pick activity, if the resultCode is android.app.Activity#RESULT_OK, an AppWidget has been selected. You should then check the AppWidgetProviderInfo for the returned AppWidget, and if it has one, launch its configuration activity. If android.app.Activity#RESULT_CANCELED is returned, you should delete the appWidgetId.

Value: "android.appwidget.action.APPWIDGET_PICK"

ACTION_APPWIDGET_RESTORED

static val ACTION_APPWIDGET_RESTORED: String

Sent to an AppWidgetProvider after AppWidget state related to that provider has been restored from backup. The intent contains information about how to translate AppWidget ids from the restored data to their new equivalents.

The intent will contain the following extras:

This is a protected intent that can only be sent by the system.

Value: "android.appwidget.action.APPWIDGET_RESTORED"

ACTION_APPWIDGET_UPDATE

static val ACTION_APPWIDGET_UPDATE: String

Sent when it is time to update your AppWidget.

This may be sent in response to a new instance for this AppWidget provider having been instantiated, the requested update interval having lapsed, or the system booting.

The intent will contain the following extras:

Value: "android.appwidget.action.APPWIDGET_UPDATE"

EXTRA_APPWIDGET_ID

static val EXTRA_APPWIDGET_ID: String

An intent extra (int) that contains one appWidgetId.

The value will be an int that can be retrieved like this:

Value: "appWidgetId"

EXTRA_APPWIDGET_IDS

static val EXTRA_APPWIDGET_IDS: String

An intent extra that contains multiple appWidgetIds.

The value will be an int array that can be retrieved like this:

Value: "appWidgetIds"

EXTRA_APPWIDGET_OLD_IDS

static val EXTRA_APPWIDGET_OLD_IDS: String

An intent extra that contains multiple appWidgetIds. These are id values as they were provided to the application during a recent restore from backup. It is attached to the ACTION_APPWIDGET_RESTORED broadcast intent.

The value will be an int array that can be retrieved like this:

Value: "appWidgetOldIds"

EXTRA_APPWIDGET_OPTIONS

static val EXTRA_APPWIDGET_OPTIONS: String

An intent extra which points to a bundle of extra information for a particular widget id. In particular this bundle can contain OPTION_APPWIDGET_MIN_WIDTH, OPTION_APPWIDGET_MIN_HEIGHT, OPTION_APPWIDGET_MAX_WIDTH, OPTION_APPWIDGET_MAX_HEIGHT.

Value: "appWidgetOptions"

EXTRA_APPWIDGET_PREVIEW

static val EXTRA_APPWIDGET_PREVIEW: String

An extra that can be passed to requestPinAppWidget(android.content.ComponentName,android.os.Bundle,android.app.PendingIntent). This would allow the launcher app to present a custom preview to the user.

The value should be a RemoteViews similar to what is used with #updateAppWidget calls.

Value: "appWidgetPreview"

EXTRA_APPWIDGET_PROVIDER

static val EXTRA_APPWIDGET_PROVIDER: String

An intent extra that contains the component name of a AppWidget provider.

The value will be an android.content.ComponentName.

Value: "appWidgetProvider"

EXTRA_APPWIDGET_PROVIDER_PROFILE

static val EXTRA_APPWIDGET_PROVIDER_PROFILE: String

An intent extra that contains the user handle of the profile under which an AppWidget provider is registered.

The value will be a android.os.UserHandle.

Value: "appWidgetProviderProfile"

EXTRA_CUSTOM_EXTRAS

static val EXTRA_CUSTOM_EXTRAS: String

An intent extra to pass to the AppWidget picker containing a java.util.List of android.os.Bundle objects to mix in to the list of AppWidgets that are installed. It will be added to the extras object on the android.content.Intent that is returned from the picker activity. {@more}

Value: "customExtras"

EXTRA_CUSTOM_INFO

static val EXTRA_CUSTOM_INFO: String

An intent extra to pass to the AppWidget picker containing a java.util.List of AppWidgetProviderInfo objects to mix in to the list of AppWidgets that are installed. (This is how the launcher shows the search widget).

Value: "customInfo"

EXTRA_HOST_ID

static val EXTRA_HOST_ID: String

An intent extra attached to the ACTION_APPWIDGET_HOST_RESTORED broadcast, indicating the integer ID of the host whose widgets have just been restored.

Value: "hostId"

INVALID_APPWIDGET_ID

static val INVALID_APPWIDGET_ID: Int

A sentinel value that the AppWidget manager will never return as a appWidgetId.

Value: 0

META_DATA_APPWIDGET_PROVIDER

static val META_DATA_APPWIDGET_PROVIDER: String

Field for the manifest meta-data tag.

Value: "android.appwidget.provider"

OPTION_APPWIDGET_HOST_CATEGORY

static val OPTION_APPWIDGET_HOST_CATEGORY: String

A bundle extra that hints to the AppWidgetProvider the category of host that owns this this widget. Can have the value android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_HOME_SCREEN or android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_KEYGUARD or android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_SEARCHBOX.

Value: "appWidgetCategory"

OPTION_APPWIDGET_MAX_HEIGHT

static val OPTION_APPWIDGET_MAX_HEIGHT: String

A bundle extra (int) that contains the upper bound on the current width, in dips, of a widget instance.

Value: "appWidgetMaxHeight"

OPTION_APPWIDGET_MAX_WIDTH

static val OPTION_APPWIDGET_MAX_WIDTH: String

A bundle extra (int) that contains the upper bound on the current width, in dips, of a widget instance.

Value: "appWidgetMaxWidth"

OPTION_APPWIDGET_MIN_HEIGHT

static val OPTION_APPWIDGET_MIN_HEIGHT: String

A bundle extra (int) that contains the lower bound on the current height, in dips, of a widget instance.

Value: "appWidgetMinHeight"

OPTION_APPWIDGET_MIN_WIDTH

static val OPTION_APPWIDGET_MIN_WIDTH: String

A bundle extra (int) that contains the lower bound on the current width, in dips, of a widget instance.

Value: "appWidgetMinWidth"

OPTION_APPWIDGET_RESTORE_COMPLETED

static val OPTION_APPWIDGET_RESTORE_COMPLETED: String

A bundle extra (boolean) that contains whether or not an app has finished restoring a widget.

After restore, the app should set OPTION_APPWIDGET_RESTORE_COMPLETED to true on its widgets followed by calling #updateAppWidget to update the views.

Value: "appWidgetRestoreCompleted"

OPTION_APPWIDGET_SIZES

static val OPTION_APPWIDGET_SIZES: String

A bundle extra (List<SizeF>) that contains the list of possible sizes, in dips, a widget instance can take.

Value: "appWidgetSizes"

bindAppWidgetIdIfAllowed

open fun bindAppWidgetIdIfAllowed(
    appWidgetId: Int, 
    provider: ComponentName!
): Boolean

Set the component for a given appWidgetId. If successful, the app widget provider will receive a ACTION_APPWIDGET_UPDATE broadcast.

You need the BIND_APPWIDGET permission or the user must have enabled binding widgets always for your component. Should be used by apps that host widgets; if this method returns false, call ACTION_APPWIDGET_BIND to request permission to bind

bindAppWidgetIdIfAllowed

open fun bindAppWidgetIdIfAllowed(
    appWidgetId: Int, 
    provider: ComponentName!, 
    options: Bundle!
): Boolean

Set the component for a given appWidgetId. If successful, the app widget provider will receive a ACTION_APPWIDGET_UPDATE broadcast.

You need the BIND_APPWIDGET permission or the user must have enabled binding widgets always for your component. Should be used by apps that host widgets; if this method returns false, call ACTION_APPWIDGET_BIND to request permission to bind

bindAppWidgetIdIfAllowed

open fun bindAppWidgetIdIfAllowed(
    appWidgetId: Int, 
    user: UserHandle!, 
    provider: ComponentName!, 
    options: Bundle!
): Boolean

Set the provider for a given appWidgetId if the caller has a permission. If successful, the app widget provider will receive a ACTION_APPWIDGET_UPDATE broadcast.

Note: You need the android.Manifest.permission#BIND_APPWIDGET permission or the user must have enabled binding widgets always for your component. Should be used by apps that host widgets. If this method returns false, call ACTION_APPWIDGET_BIND to request permission to bind.

getAppWidgetIds

open fun getAppWidgetIds(provider: ComponentName!): IntArray!

Get the list of appWidgetIds that have been bound to the given AppWidget provider.

getAppWidgetInfo

open fun getAppWidgetInfo(appWidgetId: Int): AppWidgetProviderInfo!

Get the available info about the AppWidget.

getAppWidgetOptions

open fun getAppWidgetOptions(appWidgetId: Int): Bundle!

Get the extras associated with a given widget instance.

The extras can be used to embed additional information about this widget to be accessed by the associated widget's AppWidgetProvider.

getInstalledProviders

open fun getInstalledProviders(): MutableList<AppWidgetProviderInfo!>!

Return a list of the AppWidget providers that are currently installed.

getInstalledProvidersForPackage

open fun getInstalledProvidersForPackage(
    packageName: String, 
    profile: UserHandle?
): MutableList<AppWidgetProviderInfo!>

Gets the AppWidget providers for the given package and user profile. User profile can only be the current user or a profile of the current user. For example, the current user may have a corporate profile. In this case the parent user profile has a child profile, the corporate one.

getInstalledProvidersForProfile

open fun getInstalledProvidersForProfile(profile: UserHandle?): MutableList<AppWidgetProviderInfo!>

Gets the AppWidget providers for the given user profile. User profile can only be the current user or a profile of the current user. For example, the current user may have a corporate profile. In this case the parent user profile has a child profile, the corporate one.

getInstance

open static fun getInstance(context: Context!): AppWidgetManager!

Get the AppWidgetManager instance to use for the supplied Context object.

getWidgetPreview

open fun getWidgetPreview(
    provider: ComponentName, 
    profile: UserHandle?, 
    widgetCategory: Int
): RemoteViews?

Get the RemoteViews previews for this widget.

isRequestPinAppWidgetSupported

open fun isRequestPinAppWidgetSupported(): Boolean

Return TRUE if the default launcher supports requestPinAppWidget(android.content.ComponentName,android.os.Bundle,android.app.PendingIntent)

notifyAppWidgetViewDataChanged

open fun notifyAppWidgetViewDataChanged(
    appWidgetIds: IntArray!, 
    viewId: Int
): Unit

Deprecated: The corresponding API RemoteViews#setRemoteAdapter(int, Intent) associated with this method has been deprecated. Moving forward please use RemoteViews#setRemoteAdapter(int, android.widget.RemoteViews.RemoteCollectionItems) instead to set android.widget.RemoteViews.RemoteCollectionItems for the remote adapter and update the widget views by calling updateAppWidget(int[],android.widget.RemoteViews), updateAppWidget(int,android.widget.RemoteViews), updateAppWidget(android.content.ComponentName,android.widget.RemoteViews), partiallyUpdateAppWidget(int[],android.widget.RemoteViews), or partiallyUpdateAppWidget(int,android.widget.RemoteViews), whichever applicable.

Notifies the specified collection view in all the specified AppWidget instances to invalidate their data.

notifyAppWidgetViewDataChanged

open fun notifyAppWidgetViewDataChanged(
    appWidgetId: Int, 
    viewId: Int
): Unit

Deprecated: The corresponding API RemoteViews#setRemoteAdapter(int, Intent) associated with this method has been deprecated. Moving forward please use RemoteViews#setRemoteAdapter(int, android.widget.RemoteViews.RemoteCollectionItems) instead to set android.widget.RemoteViews.RemoteCollectionItems for the remote adapter and update the widget views by calling updateAppWidget(int[],android.widget.RemoteViews), updateAppWidget(int,android.widget.RemoteViews), updateAppWidget(android.content.ComponentName,android.widget.RemoteViews), partiallyUpdateAppWidget(int[],android.widget.RemoteViews), or partiallyUpdateAppWidget(int,android.widget.RemoteViews), whichever applicable.

Notifies the specified collection view in the specified AppWidget instance to invalidate its data.

partiallyUpdateAppWidget

open fun partiallyUpdateAppWidget(
    appWidgetIds: IntArray!, 
    views: RemoteViews!
): Unit

Perform an incremental update or command on the widget(s) specified by appWidgetIds.

This update differs from updateAppWidget(int[],android.widget.RemoteViews) in that the RemoteViews object which is passed is understood to be an incomplete representation of the widget, and hence does not replace the cached representation of the widget. As of API level 17, the new properties set within the views objects will be appended to the cached representation of the widget, and hence will persist. Use with RemoteViews#showNext(int), RemoteViews#showPrevious(int), RemoteViews#setScrollPosition(int, int) and similar commands.

It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE broadcast, and outside of the handler. This method will only work when called from the uid that owns the AppWidget provider.

This method will be ignored if a widget has not received a full update via updateAppWidget(int[],android.widget.RemoteViews).

partiallyUpdateAppWidget

open fun partiallyUpdateAppWidget(
    appWidgetId: Int, 
    views: RemoteViews!
): Unit

Perform an incremental update or command on the widget specified by appWidgetId.

This update differs from updateAppWidget(int,android.widget.RemoteViews) in that the RemoteViews object which is passed is understood to be an incomplete representation of the widget, and hence is not cached by the AppWidgetService. Note that because these updates are not cached, any state that they modify that is not restored by restoreInstanceState will not persist in the case that the widgets are restored using the cached version in AppWidgetService. Use with RemoteViews#showNext(int), RemoteViews#showPrevious(int), RemoteViews#setScrollPosition(int, int) and similar commands.

It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE broadcast, and outside of the handler. This method will only work when called from the uid that owns the AppWidget provider.

This method will be ignored if a widget has not received a full update via updateAppWidget(int[],android.widget.RemoteViews).

removeWidgetPreview

open fun removeWidgetPreview(
    provider: ComponentName, 
    widgetCategories: Int
): Unit

Remove this provider's preview for the specified widget categories. If the provider does not have a preview for the specified widget category, this is a no-op.

requestPinAppWidget

open fun requestPinAppWidget(
    provider: ComponentName, 
    extras: Bundle?, 
    successCallback: PendingIntent?
): Boolean

Request to pin an app widget on the current launcher. It's up to the launcher to accept this request (optionally showing a user confirmation). If the request is accepted, the caller will get a confirmation with extra EXTRA_APPWIDGET_ID.

When a request is denied by the user, the caller app will not get any response.

Only apps with a foreground activity or a foreground service can call it. Otherwise it'll throw IllegalStateException.

It's up to the launcher how to handle previous pending requests when the same package calls this API multiple times in a row. It may ignore the previous requests, for example.

Launcher will not show the configuration activity associated with the provider in this case. The app could either show the configuration activity as a response to the callback, or show if before calling the API (various configurations can be encapsulated in successCallback to avoid persisting them before the widgetId is known).

setWidgetPreview

open fun setWidgetPreview(
    provider: ComponentName, 
    widgetCategories: Int, 
    preview: RemoteViews
): Boolean

Set a preview for this widget. This preview will be used instead of the provider's previewLayout or previewImage for previewing the widget in the widget picker and pin app widget flow.

updateAppWidget

open fun updateAppWidget(
    appWidgetIds: IntArray!, 
    views: RemoteViews!
): Unit

Set the RemoteViews to use for the specified appWidgetIds.

Note that the RemoteViews parameter will be cached by the AppWidgetService, and hence should contain a complete representation of the widget. For performing partial widget updates, see partiallyUpdateAppWidget(int[],android.widget.RemoteViews).

It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE broadcast, and outside of the handler. This method will only work when called from the uid that owns the AppWidget provider.

The total Bitmap memory used by the RemoteViews object cannot exceed that required to fill the screen 1.5 times, ie. (screen width x screen height x 4 x 1.5) bytes.

updateAppWidget

open fun updateAppWidget(
    appWidgetId: Int, 
    views: RemoteViews!
): Unit

Set the RemoteViews to use for the specified appWidgetId.

Note that the RemoteViews parameter will be cached by the AppWidgetService, and hence should contain a complete representation of the widget. For performing partial widget updates, see partiallyUpdateAppWidget(int,android.widget.RemoteViews).

It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE broadcast, and outside of the handler. This method will only work when called from the uid that owns the AppWidget provider.

The total Bitmap memory used by the RemoteViews object cannot exceed that required to fill the screen 1.5 times, ie. (screen width x screen height x 4 x 1.5) bytes.

updateAppWidget

open fun updateAppWidget(
    provider: ComponentName!, 
    views: RemoteViews!
): Unit

Set the RemoteViews to use for all AppWidget instances for the supplied AppWidget provider.

It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE broadcast, and outside of the handler. This method will only work when called from the uid that owns the AppWidget provider.

updateAppWidgetOptions

open fun updateAppWidgetOptions(
    appWidgetId: Int, 
    options: Bundle!
): Unit

Update the extras for a given widget instance.

The extras can be used to embed additional information about this widget to be accessed by the associated widget's AppWidgetProvider.

The new options are merged into existing options using android.os.Bundle#putAll semantics.

updateAppWidgetProviderInfo

open fun updateAppWidgetProviderInfo(
    provider: ComponentName!, 
    metaDataKey: String?
): Unit

Updates the info for the supplied AppWidget provider. Apps can use this to change the default behavior of the widget based on the state of the app (for e.g., if the user is logged in or not). Calling this API completely replaces the previous definition.

The manifest entry of the provider should contain an additional meta-data tag similar to META_DATA_APPWIDGET_PROVIDER which should point to any alternative definitions for the provider.

This is persisted across device reboots and app updates. If this meta-data key is not present in the manifest entry, the info reverts to default.