Added in API level 3

Summary: Constants | Methods | Inherited Methods

AppWidgetManager

---

Kotlin |Java

public class AppWidgetManager
extends Object

java.lang.Object
↳	android.appwidget.AppWidgetManager

---

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.

Requires the PackageManager#FEATURE_APP_WIDGETS feature which can be detected using PackageManager.hasSystemFeature(String).

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 the last AppWidget of this provider 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 (int) 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_PREVIEW An extra that can be passed to requestPinAppWidget(android.content.ComponentName, android.os.Bundle, android.app.PendingIntent).
String	EXTRA_APPWIDGET_PROVIDER An intent extra that contains the component name of a AppWidget provider.
String	EXTRA_APPWIDGET_PROVIDER_PROFILE An intent extra that contains the user handle of the profile under which an AppWidget provider is registered.
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 (int) that contains the upper bound on the current width, in dips, of a widget instance.
String	OPTION_APPWIDGET_MAX_WIDTH A bundle extra (int) that contains the upper bound on the current width, in dips, of a widget instance.
String	OPTION_APPWIDGET_MIN_HEIGHT A bundle extra (int) that contains the lower bound on the current height, in dips, of a widget instance.
String	OPTION_APPWIDGET_MIN_WIDTH A bundle extra (int) that contains the lower bound on the current width, in dips, of a widget instance.
String	OPTION_APPWIDGET_RESTORE_COMPLETED A bundle extra (boolean) that contains whether or not an app has finished restoring a widget.
String	OPTION_APPWIDGET_SIZES A bundle extra (List<SizeF>) that contains the list of possible sizes, in dips, a widget instance can take.

Public methods
boolean	bindAppWidgetIdIfAllowed(int appWidgetId, ComponentName provider) Set the component for a given appWidgetId.
boolean	bindAppWidgetIdIfAllowed(int appWidgetId, UserHandle user, ComponentName provider, Bundle options) Set the provider for a given appWidgetId if the caller has a permission.
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) Returns the AppWidgetProviderInfo for the specified 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.
List<AppWidgetProviderInfo>	getInstalledProvidersForPackage(String packageName, UserHandle profile) Gets the AppWidget providers for the given package and user profile.
List<AppWidgetProviderInfo>	getInstalledProvidersForProfile(UserHandle profile) Gets the AppWidget providers for the given user profile.
static AppWidgetManager	getInstance(Context context) Get the AppWidgetManager instance to use for the supplied Context object.
RemoteViews	getWidgetPreview(ComponentName provider, UserHandle profile, int widgetCategory) Get the RemoteViews previews for this widget.
boolean	isRequestPinAppWidgetSupported() Return TRUE if the default launcher supports requestPinAppWidget(android.content.ComponentName, android.os.Bundle, android.app.PendingIntent)
void	notifyAppWidgetViewDataChanged(int appWidgetId, int viewId) This method was deprecated in API level 35. 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 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.
void	notifyAppWidgetViewDataChanged(int[] appWidgetIds, int viewId) This method was deprecated in API level 35. 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 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.
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	removeWidgetPreview(ComponentName provider, int widgetCategories) Remove this provider's preview for the specified widget categories.
boolean	requestPinAppWidget(ComponentName provider, Bundle extras, PendingIntent successCallback) Request to pin an app widget on the current launcher.
boolean	setWidgetPreview(ComponentName provider, int widgetCategories, RemoteViews preview) Set a preview for this widget.
void	updateAppWidget(ComponentName provider, RemoteViews views) Set the RemoteViews to use for all AppWidget instances for the supplied AppWidget provider.
void	updateAppWidget(int[] appWidgetIds, RemoteViews views) Set the RemoteViews to use for the specified appWidgetIds.
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.
void	updateAppWidgetProviderInfo(ComponentName provider, String metaDataKey) Updates the info for the supplied AppWidget provider.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

ACTION_APPWIDGET_BIND

Added in API level 16

public static final 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.

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.
EXTRA_APPWIDGET_PROVIDER_PROFILE	An optional handle to a user profile under which runs the 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 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 Activity.RESULT_CANCELED is returned, you should delete the appWidgetId.

See also:

• ACTION_APPWIDGET_CONFIGURE

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

ACTION_APPWIDGET_CONFIGURE

Added in API level 3

public static final String ACTION_APPWIDGET_CONFIGURE

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:

EXTRA_APPWIDGET_ID

The appWidgetId to configure.

If you return Activity.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 Activity.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"

ACTION_APPWIDGET_DELETED

Added in API level 3

public static final String ACTION_APPWIDGET_DELETED

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.

See also:

• AppWidgetProvider.onDeleted(Context context, int[] appWidgetIds)

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

ACTION_APPWIDGET_DISABLED

Added in API level 3

public static final String ACTION_APPWIDGET_DISABLED

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.

See also:

• AppWidgetProvider.onDisabled(Context context)

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

ACTION_APPWIDGET_ENABLED

Added in API level 3

public static final String ACTION_APPWIDGET_ENABLED

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.

See also:

• AppWidgetProvider.onEnabled(Context context)

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

ACTION_APPWIDGET_HOST_RESTORED

Added in API level 21

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.

See also:

• ACTION_APPWIDGET_RESTORED

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

ACTION_APPWIDGET_OPTIONS_CHANGED

Added in API level 16

public static final String ACTION_APPWIDGET_OPTIONS_CHANGED

Sent when the custom extras for an AppWidget change.

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

See also:

• AppWidgetProvider.onAppWidgetOptionsChanged(Context context, AppWidgetManager appWidgetManager, int appWidgetId, Bundle newExtras)

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

ACTION_APPWIDGET_PICK

Added in API level 3

public static final String ACTION_APPWIDGET_PICK

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 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 Activity.RESULT_CANCELED is returned, you should delete the appWidgetId.

See also:

• ACTION_APPWIDGET_CONFIGURE

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

ACTION_APPWIDGET_RESTORED

Added in API level 21

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.

See also:

• ACTION_APPWIDGET_HOST_RESTORED

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

ACTION_APPWIDGET_UPDATE

Added in API level 3

public static final String ACTION_APPWIDGET_UPDATE

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.

See also:

• AppWidgetProvider.onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds)

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

EXTRA_APPWIDGET_ID

Added in API level 3

public static final String EXTRA_APPWIDGET_ID

An intent extra (int) 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"

EXTRA_APPWIDGET_IDS

Added in API level 3

public static final String EXTRA_APPWIDGET_IDS

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"

EXTRA_APPWIDGET_OLD_IDS

Added in API level 21

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"

EXTRA_APPWIDGET_OPTIONS

Added in API level 16

public static final String EXTRA_APPWIDGET_OPTIONS

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.

Constant Value: "appWidgetOptions"

EXTRA_APPWIDGET_PREVIEW

Added in API level 26

public static final String EXTRA_APPWIDGET_PREVIEW

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(ComponentName, RemoteViews) calls.

Constant Value: "appWidgetPreview"

EXTRA_APPWIDGET_PROVIDER

Added in API level 16

public static final String EXTRA_APPWIDGET_PROVIDER

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

The value will be an ComponentName.

Constant Value: "appWidgetProvider"

EXTRA_APPWIDGET_PROVIDER_PROFILE

Added in API level 21

public static final String EXTRA_APPWIDGET_PROVIDER_PROFILE

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

The value will be a UserHandle.

Constant Value: "appWidgetProviderProfile"

EXTRA_CUSTOM_EXTRAS

Added in API level 3

public static final 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.

Constant Value: "customExtras"

EXTRA_CUSTOM_INFO

Added in API level 3

public static final 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. (This is how the launcher shows the search widget).

Constant Value: "customInfo"

EXTRA_HOST_ID

Added in API level 21

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"

INVALID_APPWIDGET_ID

Added in API level 3

public static final int INVALID_APPWIDGET_ID

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

Constant Value: 0 (0x00000000)

META_DATA_APPWIDGET_PROVIDER

Added in API level 3

public static final String META_DATA_APPWIDGET_PROVIDER

Field for the manifest meta-data tag.

See also:

• AppWidgetProviderInfo

Constant Value: "android.appwidget.provider"

OPTION_APPWIDGET_HOST_CATEGORY

Added in API level 17

public static final String OPTION_APPWIDGET_HOST_CATEGORY

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

Constant Value: "appWidgetCategory"

OPTION_APPWIDGET_MAX_HEIGHT

Added in API level 16

public static final String OPTION_APPWIDGET_MAX_HEIGHT

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

Constant Value: "appWidgetMaxHeight"

OPTION_APPWIDGET_MAX_WIDTH

Added in API level 16

public static final String OPTION_APPWIDGET_MAX_WIDTH

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

Constant Value: "appWidgetMaxWidth"

OPTION_APPWIDGET_MIN_HEIGHT

Added in API level 16

public static final String OPTION_APPWIDGET_MIN_HEIGHT

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

Constant Value: "appWidgetMinHeight"

OPTION_APPWIDGET_MIN_WIDTH

Added in API level 16

public static final String OPTION_APPWIDGET_MIN_WIDTH

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

Constant Value: "appWidgetMinWidth"

OPTION_APPWIDGET_RESTORE_COMPLETED

Added in API level 30

public static final String OPTION_APPWIDGET_RESTORE_COMPLETED

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(ComponentName, RemoteViews) to update the views.

See also:

• updateAppWidgetOptions(int, Bundle)

Constant Value: "appWidgetRestoreCompleted"

OPTION_APPWIDGET_SIZES

Added in API level 31

public static final String OPTION_APPWIDGET_SIZES

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

Constant Value: "appWidgetSizes"

Public methods

bindAppWidgetIdIfAllowed

Added in API level 16

public boolean bindAppWidgetIdIfAllowed (int appWidgetId, 
                ComponentName provider)

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

Parameters
appWidgetId	int: The AppWidget id under which to bind the provider.
provider	ComponentName: The BroadcastReceiver that will be the AppWidget provider for this AppWidget.

Returns
boolean	true if this component has permission to bind the AppWidget

bindAppWidgetIdIfAllowed

Added in API level 21

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

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

Parameters
appWidgetId	int: The AppWidget id under which to bind the provider.
user	UserHandle: The user id in which the provider resides.
provider	ComponentName: The component name of the provider.
options	Bundle: An optional Bundle containing options for the AppWidget.

Returns
boolean	true if this component has permission to bind the AppWidget

bindAppWidgetIdIfAllowed

Added in API level 17

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

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

Parameters
appWidgetId	int: The AppWidget id under which to bind the provider.
provider	ComponentName: The BroadcastReceiver that will be the AppWidget provider for this AppWidget.
options	Bundle: Bundle containing options for the AppWidget. See also updateAppWidgetOptions(int, android.os.Bundle)

Returns
boolean	true if this component has permission to bind the AppWidget

getAppWidgetIds

Added in API level 3

public int[] getAppWidgetIds (ComponentName provider)

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

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

Returns
int[]

getAppWidgetInfo

Added in API level 3

public AppWidgetProviderInfo getAppWidgetInfo (int appWidgetId)

Returns the AppWidgetProviderInfo for the specified AppWidget.

Parameters
appWidgetId	int

Returns
AppWidgetProviderInfo	Information regarding the provider of speficied widget, returns null if the appWidgetId has not been bound to a provider yet, or you don't have access to that widget.

getAppWidgetOptions

Added in API level 16

public Bundle getAppWidgetOptions (int appWidgetId)

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	int: The AppWidget instances for which to set the RemoteViews.

Returns
Bundle	The options associated with the given widget instance.

See also:

• updateAppWidgetOptions(int, Bundle)

getInstalledProviders

Added in API level 3

public List<AppWidgetProviderInfo> getInstalledProviders ()

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

Returns
List<AppWidgetProviderInfo>

getInstalledProvidersForPackage

Added in API level 26

public List<AppWidgetProviderInfo> getInstalledProvidersForPackage (String packageName, 
                UserHandle profile)

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.

Parameters
packageName	String: The package for which to get providers. If null, this method is equivalent to getInstalledProvidersForProfile(android.os.UserHandle).
profile	UserHandle: The profile for which to get providers. Passing null is equivalent to querying for only the calling user.

Returns
List<AppWidgetProviderInfo>	The installed providers, or an empty list if none are found for the given package and user. This value cannot be null.

Throws
NullPointerException	if the provided package name is null

See also:

• Process.myUserHandle()
• UserManager.getUserProfiles()

getInstalledProvidersForProfile

Added in API level 21

public List<AppWidgetProviderInfo> getInstalledProvidersForProfile (UserHandle profile)

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.

Parameters
profile	UserHandle: The profile for which to get providers. Passing null is equivalent to querying for only the calling user.

Returns
List<AppWidgetProviderInfo>	The installed providers, or an empty list if none are found for the given user. This value cannot be null.

See also:

• Process.myUserHandle()
• UserManager.getUserProfiles()

getInstance

Added in API level 3

public static AppWidgetManager getInstance (Context context)

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

Parameters
context	Context

Returns
AppWidgetManager

getWidgetPreview

Added in API level 35

public RemoteViews getWidgetPreview (ComponentName provider, 
                UserHandle profile, 
                int widgetCategory)

Get the RemoteViews previews for this widget.

Parameters
provider	ComponentName: The ComponentName for the BroadcastReceiver provider for the AppWidget you intend to get a preview for. This value cannot be null.
profile	UserHandle: The profile in which the provider resides. Passing null is equivalent to querying for only the calling user.
widgetCategory	int: The widget category for which you want to display previews. This should be a single category. If a combination of categories is provided, this function will return a preview that matches at least one of the categories. Value is either 0 or a combination of AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN, AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD, AppWidgetProviderInfo.WIDGET_CATEGORY_SEARCHBOX, and AppWidgetProviderInfo.WIDGET_CATEGORY_NOT_KEYGUARD

Returns
RemoteViews	The widget preview for the selected category, if available. This value may be null.

See also:

• AppWidgetProviderInfo.generatedPreviewCategories

isRequestPinAppWidgetSupported

Added in API level 26

public boolean isRequestPinAppWidgetSupported ()

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

Returns
boolean

notifyAppWidgetViewDataChanged

Added in API level 11
Deprecated in API level 35

public void notifyAppWidgetViewDataChanged (int appWidgetId, 
                int viewId)

This method was deprecated in API level 35.
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 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.

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

notifyAppWidgetViewDataChanged

Added in API level 11
Deprecated in API level 35

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

This method was deprecated in API level 35.
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 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.

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

partiallyUpdateAppWidget

Added in API level 11

public void partiallyUpdateAppWidget (int appWidgetId, 
                RemoteViews views)

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

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

partiallyUpdateAppWidget

Added in API level 11

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

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

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

removeWidgetPreview

Added in API level 35

public void removeWidgetPreview (ComponentName provider, 
                int widgetCategories)

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.

Parameters
provider	ComponentName: The AppWidgetProvider to remove previews for. This value cannot be null.
widgetCategories	int: The categories of the preview to remove. For example, removing the preview for WIDGET_CATEGORY_HOME_SCREEN | WIDGET_CATEGORY_KEYGUARD will remove the previews for both categories. Value is either 0 or a combination of AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN, AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD, AppWidgetProviderInfo.WIDGET_CATEGORY_SEARCHBOX, and AppWidgetProviderInfo.WIDGET_CATEGORY_NOT_KEYGUARD

requestPinAppWidget

Added in API level 26

public boolean requestPinAppWidget (ComponentName provider, 
                Bundle extras, 
                PendingIntent successCallback)

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

Parameters
provider	ComponentName: The ComponentName for the BroadcastReceiver provider for your AppWidget. This value cannot be null.
extras	Bundle: IF not null, this is passed to the launcher app. e.g. EXTRA_APPWIDGET_PREVIEW can be used for a custom preview.
successCallback	PendingIntent: If not null, this intent will be sent when the widget is created.

Returns
boolean	TRUE if the launcher supports this feature. Note the API will return without waiting for the user to respond, so getting TRUE from this API does *not* mean the shortcut is pinned. FALSE if the launcher doesn't support this feature or if calling app belongs to a user-profile with items restricted on home screen.

Throws
IllegalStateException	The caller doesn't have a foreground activity or a foreground service or when the user is locked.

See also:

• ShortcutManager.isRequestPinShortcutSupported()
• ShortcutManager.requestPinShortcut(ShortcutInfo, IntentSender)
• isRequestPinAppWidgetSupported()

setWidgetPreview

Added in API level 35

public boolean setWidgetPreview (ComponentName provider, 
                int widgetCategories, 
                RemoteViews preview)

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.

Parameters
provider	ComponentName: The ComponentName for the BroadcastReceiver provider for the AppWidget you intend to provide a preview for. This value cannot be null.
widgetCategories	int: The categories that this preview should be used for. This can be a single category or combination of categories. If multiple categories are specified, then this preview will be used for each of those categories. For example, if you set a preview for WIDGET_CATEGORY_HOME_SCREEN | WIDGET_CATEGORY_KEYGUARD, the preview will be used when picking widgets for the home screen and keyguard. Note: You should only use the widget categories that the provider supports, as defined in AppWidgetProviderInfo.widgetCategory. Value is either 0 or a combination of AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN, AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD, AppWidgetProviderInfo.WIDGET_CATEGORY_SEARCHBOX, and AppWidgetProviderInfo.WIDGET_CATEGORY_NOT_KEYGUARD
preview	RemoteViews: This preview will be used for previewing the provider when picking widgets for the selected categories. This value cannot be null.

Returns
boolean	true if the call was successful, false if it was rate-limited.

See also:

• AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN
• AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD
• AppWidgetProviderInfo.WIDGET_CATEGORY_SEARCHBOX

updateAppWidget

Added in API level 3

public void updateAppWidget (ComponentName provider, 
                RemoteViews views)

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	ComponentName: The ComponentName for the BroadcastReceiver provider for your AppWidget.
views	RemoteViews: The RemoteViews object to show.

updateAppWidget

Added in API level 3

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

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.

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

updateAppWidget

Added in API level 3

public void updateAppWidget (int appWidgetId, 
                RemoteViews views)

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.

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

updateAppWidgetOptions

Added in API level 16

public void updateAppWidgetOptions (int appWidgetId, 
                Bundle options)

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 Bundle.putAll semantics.

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

See also:

• getAppWidgetOptions(int)

updateAppWidgetProviderInfo

Added in API level 28

public void updateAppWidgetProviderInfo (ComponentName provider, 
                String metaDataKey)

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.

Parameters
provider	ComponentName: ComponentName for the BroadcastReceiver provider for your AppWidget.
metaDataKey	String: key for the meta-data tag pointing to the new provider info. Use null to reset any previously set info.