Summary: Constants | Methods | Inherited Methods | [Expand All]

Since: API Level 3

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.

Summary

Constants
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_PICK	Send this from your `AppWidgetHost` activity when you want to pick an AppWidget to display.
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_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.
int	INVALID_APPWIDGET_ID	A sentiel value that the AppWidget manager will never return as a appWidgetId.
String	META_DATA_APPWIDGET_PROVIDER	Field for the manifest meta-data tag.

Public Methods
void	bindAppWidgetId(int appWidgetId, ComponentName provider) 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.
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 currently data.
void	notifyAppWidgetViewDataChanged(int appWidgetId, int viewId) Notifies the specified collection view in all the specified AppWidget instance to invalidate it's currently data.
void	partiallyUpdateAppWidget(int[] appWidgetIds, RemoteViews views) Perform an incremental update or command on the widget(s) specified by appWidgetIds.
void	partiallyUpdateAppWidget(int appWidgetId, RemoteViews views) Perform an incremental update or command on the widget specified by appWidgetId.
void	updateAppWidget(int appWidgetId, RemoteViews views) Set the RemoteViews to use for the specified appWidgetId.
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.

[Expand]

Inherited Methods

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

Constants

public static final String ACTION_APPWIDGET_CONFIGURE

Since: 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

Since: API Level 3

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

public static final String ACTION_APPWIDGET_DISABLED

Since: API Level 3

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

public static final String ACTION_APPWIDGET_ENABLED

Since: 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.

public static final String ACTION_APPWIDGET_PICK

Since: API Level 3

Send this 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.

public static final String ACTION_APPWIDGET_UPDATE

Since: 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.

public static final String EXTRA_APPWIDGET_ID

Since: 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

Since: 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_CUSTOM_EXTRAS

Since: 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

Since: 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 int INVALID_APPWIDGET_ID

Since: API Level 3

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

Constant Value: 0 (0x00000000)

public static final String META_DATA_APPWIDGET_PROVIDER

Since: API Level 3

Field for the manifest meta-data tag.

Public Methods

public void bindAppWidgetId (int appWidgetId, ComponentName provider)

Since: API Level 3

Set the component for a given appWidgetId.

You need the APPWIDGET_LIST permission. This method is to be used by the AppWidget picker.

Parameters

appWidgetId	The AppWidget instance for which to set the RemoteViews.
provider	The `BroadcastReceiver` that will be the AppWidget provider for this AppWidget.

public int[] getAppWidgetIds (ComponentName provider)

Since: 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)

Since: 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 List<AppWidgetProviderInfo> getInstalledProviders ()

Since: API Level 3

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

public static AppWidgetManager getInstance (Context context)

Since: API Level 3

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

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

Since: API Level 11

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

Parameters

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

public void notifyAppWidgetViewDataChanged (int appWidgetId, int viewId)

Since: API Level 11

Notifies the specified collection view in all the specified AppWidget instance to invalidate it's currently data.

Parameters

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

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

Since: 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 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.