Android APIs
public class

AppWidgetManager

extends Object
java.lang.Object
   ↳ android.appwidget.AppWidgetManager

Class Overview

Updates AppWidget state; gets information about installed AppWidget providers and other AppWidget related state.

Developer Guides

For more information about creating app widgets, read the App Widgets developer guide.

Summary

Constants
String ACTION_APPWIDGET_BIND Activity action to launch from your AppWidgetHost activity when you want to bind an AppWidget to display and bindAppWidgetIdIfAllowed returns false.
String ACTION_APPWIDGET_CONFIGURE Sent when it is time to configure your AppWidget while it is being added to a host.
String ACTION_APPWIDGET_DELETED Sent when an instance of an AppWidget is deleted from its host.
String ACTION_APPWIDGET_DISABLED Sent when an instance of an AppWidget is removed from the last host.
String ACTION_APPWIDGET_ENABLED Sent when an instance of an AppWidget is added to a host for the first time.
String ACTION_APPWIDGET_HOST_RESTORED Sent to widget hosts after AppWidget state related to the host has been restored from backup.
String ACTION_APPWIDGET_OPTIONS_CHANGED Sent when the custom extras for an AppWidget change.
String ACTION_APPWIDGET_PICK Activity action to launch from your AppWidgetHost activity when you want to pick an AppWidget to display.
String ACTION_APPWIDGET_RESTORED Sent to an AppWidgetProvider after AppWidget state related to that provider has been restored from backup.
String ACTION_APPWIDGET_UPDATE Sent when it is time to update your AppWidget.
String EXTRA_APPWIDGET_ID An intent extra that contains one appWidgetId.
String EXTRA_APPWIDGET_IDS An intent extra that contains multiple appWidgetIds.
String EXTRA_APPWIDGET_OLD_IDS An intent extra that contains multiple appWidgetIds.
String EXTRA_APPWIDGET_OPTIONS An intent extra which points to a bundle of extra information for a particular widget id.
String EXTRA_APPWIDGET_PROVIDER An intent extra that contains the component name of a AppWidget provider.
String EXTRA_CUSTOM_EXTRAS An intent extra to pass to the AppWidget picker containing a List of Bundle objects to mix in to the list of AppWidgets that are installed. It will be added to the extras object on the Intent that is returned from the picker activity.
String EXTRA_CUSTOM_INFO An intent extra to pass to the AppWidget picker containing a List of AppWidgetProviderInfo objects to mix in to the list of AppWidgets that are installed.
String EXTRA_HOST_ID An intent extra attached to the ACTION_APPWIDGET_HOST_RESTORED broadcast, indicating the integer ID of the host whose widgets have just been restored.
int INVALID_APPWIDGET_ID A sentinel value that the AppWidget manager will never return as a appWidgetId.
String META_DATA_APPWIDGET_PROVIDER Field for the manifest meta-data tag.
String OPTION_APPWIDGET_HOST_CATEGORY A bundle extra that hints to the AppWidgetProvider the category of host that owns this this widget.
String OPTION_APPWIDGET_MAX_HEIGHT A bundle extra that contains the upper bound on the current width, in dips, of a widget instance.
String OPTION_APPWIDGET_MAX_WIDTH A bundle extra that contains the upper bound on the current width, in dips, of a widget instance.
String OPTION_APPWIDGET_MIN_HEIGHT A bundle extra that contains the lower bound on the current height, in dips, of a widget instance.
String OPTION_APPWIDGET_MIN_WIDTH A bundle extra that contains the lower bound on the current width, in dips, of a widget instance.
Public Methods
boolean bindAppWidgetIdIfAllowed(int appWidgetId, ComponentName provider)
Set the component for a given appWidgetId.
boolean bindAppWidgetIdIfAllowed(int appWidgetId, ComponentName provider, Bundle options)
Set the component for a given appWidgetId.
int[] getAppWidgetIds(ComponentName provider)
Get the list of appWidgetIds that have been bound to the given AppWidget provider.
AppWidgetProviderInfo getAppWidgetInfo(int appWidgetId)
Get the available info about the AppWidget.
Bundle getAppWidgetOptions(int appWidgetId)
Get the extras associated with a given widget instance.
List<AppWidgetProviderInfo> getInstalledProviders()
Return a list of the AppWidget providers that are currently installed.
static AppWidgetManager getInstance(Context context)
Get the AppWidgetManager instance to use for the supplied Context object.
void notifyAppWidgetViewDataChanged(int[] appWidgetIds, int viewId)
Notifies the specified collection view in all the specified AppWidget instances to invalidate their data.
void notifyAppWidgetViewDataChanged(int appWidgetId, int viewId)
Notifies the specified collection view in the specified AppWidget instance to invalidate its data.
void partiallyUpdateAppWidget(int appWidgetId, RemoteViews views)
Perform an incremental update or command on the widget specified by appWidgetId.
void partiallyUpdateAppWidget(int[] appWidgetIds, RemoteViews views)
Perform an incremental update or command on the widget(s) specified by appWidgetIds.
void updateAppWidget(int[] appWidgetIds, RemoteViews views)
Set the RemoteViews to use for the specified appWidgetIds.
void updateAppWidget(ComponentName provider, RemoteViews views)
Set the RemoteViews to use for all AppWidget instances for the supplied AppWidget provider.
void updateAppWidget(int appWidgetId, RemoteViews views)
Set the RemoteViews to use for the specified appWidgetId.
void updateAppWidgetOptions(int appWidgetId, Bundle options)
Update the extras for a given widget instance.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_APPWIDGET_BIND

Added in API level 16

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:

EXTRA_APPWIDGET_ID A newly allocated appWidgetId, which will be bound to the AppWidget provider you provide.
EXTRA_APPWIDGET_PROVIDER The BroadcastReceiver that will be the AppWidget provider for this AppWidget.

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

EXTRA_APPWIDGET_ID The appWidgetId that you supplied in the original intent.

When you receive the result from the AppWidget bind activity, if the resultCode is 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 RESULT_CANCELED is returned, you should delete the appWidgetId.

Constant Value: "android.appwidget.action.APPWIDGET_BIND"

public static final String ACTION_APPWIDGET_CONFIGURE

Added in API level 3

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 AppWidgetProviderInfo meta-data.

The intent will contain the following extras:

EXTRA_APPWIDGET_ID The appWidgetId to configure.

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

Constant Value: "android.appwidget.action.APPWIDGET_CONFIGURE"

public static final String ACTION_APPWIDGET_DELETED

Added in API level 3

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.

Constant Value: "android.appwidget.action.APPWIDGET_DELETED"

public static final String ACTION_APPWIDGET_DISABLED

Added in API level 3

Sent when an instance of an AppWidget is removed from the last host.

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

Constant Value: "android.appwidget.action.APPWIDGET_DISABLED"

public static final String ACTION_APPWIDGET_ENABLED

Added in API level 3

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.

Constant Value: "android.appwidget.action.APPWIDGET_ENABLED"

public static final String ACTION_APPWIDGET_HOST_RESTORED

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:

EXTRA_APPWIDGET_OLD_IDS The set of appWidgetIds represented in a restored backup that have been successfully incorporated into the current environment. This may be all of the AppWidgets known to this application, or just a subset. Each entry in this array of appWidgetIds has a corresponding entry in the EXTRA_APPWIDGET_IDS extra.
EXTRA_APPWIDGET_IDS The set of appWidgetIds now valid for this application. The app should look at its restored widget configuration and translate each appWidgetId in the EXTRA_APPWIDGET_OLD_IDS array to its new value found at the corresponding index within this array.
EXTRA_HOST_ID The integer ID of the widget host instance whose state has just been restored.

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

Constant Value: "android.appwidget.action.APPWIDGET_HOST_RESTORED"

public static final String ACTION_APPWIDGET_OPTIONS_CHANGED

Added in API level 16

Sent when the custom extras for an AppWidget change.

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

Constant Value: "android.appwidget.action.APPWIDGET_UPDATE_OPTIONS"

public static final String ACTION_APPWIDGET_PICK

Added in API level 3

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:

EXTRA_APPWIDGET_ID A newly allocated appWidgetId, which will be bound to the AppWidget provider once the user has selected one.

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

EXTRA_APPWIDGET_ID The appWidgetId that you supplied in the original intent.

When you receive the result from the AppWidget pick activity, if the resultCode is 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 RESULT_CANCELED is returned, you should delete the appWidgetId.

Constant Value: "android.appwidget.action.APPWIDGET_PICK"

public static final String ACTION_APPWIDGET_RESTORED

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:

EXTRA_APPWIDGET_OLD_IDS The set of appWidgetIds represented in a restored backup that have been successfully incorporated into the current environment. This may be all of the AppWidgets known to this application, or just a subset. Each entry in this array of appWidgetIds has a corresponding entry in the EXTRA_APPWIDGET_IDS extra.
EXTRA_APPWIDGET_IDS The set of appWidgetIds now valid for this application. The app should look at its restored widget configuration and translate each appWidgetId in the EXTRA_APPWIDGET_OLD_IDS array to its new value found at the corresponding index within this array.

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

Constant Value: "android.appwidget.action.APPWIDGET_RESTORED"

public static final String ACTION_APPWIDGET_UPDATE

Added in API level 3

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:

EXTRA_APPWIDGET_IDS The appWidgetIds to update. This may be all of the AppWidgets created for this provider, or just a subset. The system tries to send updates for as few AppWidget instances as possible.

Constant Value: "android.appwidget.action.APPWIDGET_UPDATE"

public static final String EXTRA_APPWIDGET_ID

Added in API level 3

An intent extra that contains one appWidgetId.

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

Bundle extras = intent.getExtras();
int appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID);

Constant Value: "appWidgetId"

public static final String EXTRA_APPWIDGET_IDS

Added in API level 3

An intent extra that contains multiple appWidgetIds.

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

Bundle extras = intent.getExtras();
int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS);

Constant Value: "appWidgetIds"

public static final String EXTRA_APPWIDGET_OLD_IDS

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:

Bundle extras = intent.getExtras();
int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS);

Constant Value: "appWidgetOldIds"

public static final String EXTRA_APPWIDGET_OPTIONS

Added in API level 16

An intent extra which points to a bundle of extra information for a particular widget id. In particular this bundle can contain EXTRA_APPWIDGET_WIDTH and EXTRA_APPWIDGET_HEIGHT.

Constant Value: "appWidgetOptions"

public static final String EXTRA_APPWIDGET_PROVIDER

Added in API level 16

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

The value will be an ComponentName.

Constant Value: "appWidgetProvider"

public static final String EXTRA_CUSTOM_EXTRAS

Added in API level 3

An intent extra to pass to the AppWidget picker containing a List of Bundle objects to mix in to the list of AppWidgets that are installed. It will be added to the extras object on the Intent that is returned from the picker activity.

Constant Value: "customExtras"

public static final String EXTRA_CUSTOM_INFO

Added in API level 3

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

Constant Value: "customInfo"

public static final String EXTRA_HOST_ID

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

Constant Value: "hostId"

public static final int INVALID_APPWIDGET_ID

Added in API level 3

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

Constant Value: 0 (0x00000000)

public static final String META_DATA_APPWIDGET_PROVIDER

Added in API level 3

Field for the manifest meta-data tag.

Constant Value: "android.appwidget.provider"

public static final String OPTION_APPWIDGET_HOST_CATEGORY

Added in API level 17

A bundle extra that hints to the AppWidgetProvider the category of host that owns this this widget. Can have the value WIDGET_CATEGORY_HOME_SCREEN or WIDGET_CATEGORY_KEYGUARD or WIDGET_CATEGORY_RECENTS.

Constant Value: "appWidgetCategory"

public static final String OPTION_APPWIDGET_MAX_HEIGHT

Added in API level 16

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

Constant Value: "appWidgetMaxHeight"

public static final String OPTION_APPWIDGET_MAX_WIDTH

Added in API level 16

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

Constant Value: "appWidgetMaxWidth"

public static final String OPTION_APPWIDGET_MIN_HEIGHT

Added in API level 16

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

Constant Value: "appWidgetMinHeight"

public static final String OPTION_APPWIDGET_MIN_WIDTH

Added in API level 16

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

Constant Value: "appWidgetMinWidth"

Public Methods

public boolean bindAppWidgetIdIfAllowed (int appWidgetId, ComponentName provider)

Added in API level 16

Set the component for a given appWidgetId.

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

Parameters
appWidgetId The AppWidget instance for which to set the RemoteViews.
provider The BroadcastReceiver that will be the AppWidget provider for this AppWidget.
Returns
  • true if this component has permission to bind the AppWidget

public boolean bindAppWidgetIdIfAllowed (int appWidgetId, ComponentName provider, Bundle options)

Added in API level 17

Set the component for a given appWidgetId.

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

Parameters
appWidgetId The AppWidget instance for which to set the RemoteViews.
provider The BroadcastReceiver that will be the AppWidget provider for this AppWidget.
options Bundle containing options for the AppWidget. See also updateAppWidgetOptions(int, Bundle)
Returns
  • true if this component has permission to bind the AppWidget

public int[] getAppWidgetIds (ComponentName provider)

Added in API level 3

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

Parameters
provider The BroadcastReceiver that is the AppWidget provider to find appWidgetIds for.

public AppWidgetProviderInfo getAppWidgetInfo (int appWidgetId)

Added in API level 3

Get the available info about the AppWidget.

Returns
  • A appWidgetId. If the appWidgetId has not been bound to a provider yet, or you don't have access to that appWidgetId, null is returned.

public Bundle getAppWidgetOptions (int appWidgetId)

Added in API level 16

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.

Parameters
appWidgetId The AppWidget instances for which to set the RemoteViews.
Returns
  • The options associated with the given widget instance.

public List<AppWidgetProviderInfo> getInstalledProviders ()

Added in API level 3

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

public static AppWidgetManager getInstance (Context context)

Added in API level 3

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

public void notifyAppWidgetViewDataChanged (int[] appWidgetIds, int viewId)

Added in API level 11

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

Parameters
appWidgetIds The AppWidget instances to notify of view data changes.
viewId The collection view id.

public void notifyAppWidgetViewDataChanged (int appWidgetId, int viewId)

Added in API level 11

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

Parameters
appWidgetId The AppWidget instance to notify of view data changes.
viewId The collection view id.

public void partiallyUpdateAppWidget (int appWidgetId, RemoteViews views)

Added in API level 11

Perform an incremental update or command on the widget specified by appWidgetId. This update differs from updateAppWidget(int, 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 showNext(int), showPrevious(int), 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[], RemoteViews).

Parameters
appWidgetId The AppWidget instance for which to set the RemoteViews.
views The RemoteViews object containing the incremental update / command.

public void partiallyUpdateAppWidget (int[] appWidgetIds, RemoteViews views)

Added in API level 11

Perform an incremental update or command on the widget(s) specified by appWidgetIds. This update differs from updateAppWidget(int[], 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 showNext(int), showPrevious(int), 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[], RemoteViews).

Parameters
appWidgetIds The AppWidget instances for which to set the RemoteViews.
views The RemoteViews object containing the incremental update / command.

public void updateAppWidget (int[] appWidgetIds, RemoteViews views)

Added in API level 3

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[], 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.

Parameters
appWidgetIds The AppWidget instances for which to set the RemoteViews.
views The RemoteViews object to show.

public void updateAppWidget (ComponentName provider, RemoteViews views)

Added in API level 3

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.

Parameters
provider The ComponentName for the BroadcastReceiver provider for your AppWidget.
views The RemoteViews object to show.

public void updateAppWidget (int appWidgetId, RemoteViews views)

Added in API level 3

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, 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.

Parameters
appWidgetId The AppWidget instance for which to set the RemoteViews.
views The RemoteViews object to show.

public void updateAppWidgetOptions (int appWidgetId, Bundle options)

Added in API level 16

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.

Parameters
appWidgetId The AppWidget instances for which to set the RemoteViews.
options The options to associate with this widget