FileDocCategorySizeDatePackage
AppWidgetManager.javaAPI DocAndroid 5.1 API44173Thu Mar 12 22:22:10 GMT 2015android.appwidget

AppWidgetManager

public class AppWidgetManager extends Object
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.

Fields Summary
public static final String
ACTION_APPWIDGET_PICK
Activity action to launch from your {@link AppWidgetHost} activity when you want to pick an AppWidget to display. The AppWidget picker activity will be launched.

You must supply the following extras:
{@link #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:
{@link #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 {@link 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 {@link android.app.Activity#RESULT_CANCELED} is returned, you should delete the appWidgetId.

public static final String
ACTION_KEYGUARD_APPWIDGET_PICK
Similar to ACTION_APPWIDGET_PICK, but used from keyguard
public static final String
ACTION_APPWIDGET_BIND
Activity action to launch from your {@link AppWidgetHost} activity when you want to bind an AppWidget to display and bindAppWidgetIdIfAllowed returns false.

You must supply the following extras:
{@link #EXTRA_APPWIDGET_ID} A newly allocated appWidgetId, which will be bound to the AppWidget provider you provide.
{@link #EXTRA_APPWIDGET_PROVIDER} The BroadcastReceiver that will be the AppWidget provider for this AppWidget.
{@link #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:
{@link #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 {@link 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 {@link android.app.Activity#RESULT_CANCELED} is returned, you should delete the appWidgetId.

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 {@link AppWidgetProviderInfo AppWidgetProviderInfo meta-data}.

The intent will contain the following extras:
{@link #EXTRA_APPWIDGET_ID} The appWidgetId to configure.

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

public static final String
EXTRA_APPWIDGET_ID
An intent extra that contains one appWidgetId.

The value will be an int that can be retrieved like this: {@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/src/com/android/tests/appwidgethost/AppWidgetHostActivity.java getExtra_EXTRA_APPWIDGET_ID}

public static final String
OPTION_APPWIDGET_MIN_WIDTH
A bundle extra that contains the lower bound on the current width, in dips, of a widget instance.
public static final String
OPTION_APPWIDGET_MIN_HEIGHT
A bundle extra that contains the lower bound on the current height, in dips, of a widget instance.
public static final String
OPTION_APPWIDGET_MAX_WIDTH
A bundle extra that contains the upper bound on the current width, in dips, of a widget instance.
public static final String
OPTION_APPWIDGET_MAX_HEIGHT
A bundle extra that contains the upper bound on the current width, in dips, of a widget instance.
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 {@link AppWidgetProviderInfo#WIDGET_CATEGORY_HOME_SCREEN} or {@link AppWidgetProviderInfo#WIDGET_CATEGORY_KEYGUARD} or {@link AppWidgetProviderInfo#WIDGET_CATEGORY_SEARCHBOX}.
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 {@link #OPTION_APPWIDGET_MIN_WIDTH}, {@link #OPTION_APPWIDGET_MIN_HEIGHT}, {@link #OPTION_APPWIDGET_MAX_WIDTH}, {@link #OPTION_APPWIDGET_MAX_HEIGHT}.
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: {@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/src/com/android/tests/appwidgethost/TestAppWidgetProvider.java getExtra_EXTRA_APPWIDGET_IDS}

public static final String
EXTRA_APPWIDGET_PROVIDER
An intent extra that contains the component name of a AppWidget provider.

The value will be an {@link android.content.ComponentName}.

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 {@link android.os.UserHandle}.

public static final String
EXTRA_CUSTOM_INFO
An intent extra to pass to the AppWidget picker containing a {@link java.util.List} of {@link AppWidgetProviderInfo} objects to mix in to the list of AppWidgets that are installed. (This is how the launcher shows the search widget).
public static final String
EXTRA_HOST_ID
An intent extra attached to the {@link #ACTION_APPWIDGET_HOST_RESTORED} broadcast, indicating the integer ID of the host whose widgets have just been restored.
public static final String
EXTRA_CUSTOM_EXTRAS
An intent extra to pass to the AppWidget picker containing a {@link java.util.List} of {@link 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 {@link android.content.Intent} that is returned from the picker activity. {@more}
public static final String
EXTRA_CATEGORY_FILTER
An intent extra to pass to the AppWidget picker which allows the picker to filter the list based on the {@link AppWidgetProviderInfo#widgetCategory}.
public static final String
EXTRA_CUSTOM_SORT
An intent extra to pass to the AppWidget picker to specify whether or not to sort the list of caller-specified extra AppWidgets along with the rest of the AppWidgets
public static final int
INVALID_APPWIDGET_ID
A sentinel value that the AppWidget manager will never return as a appWidgetId.
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 {@link AppWidgetProviderInfo#updatePeriodMillis update interval} having lapsed, or the system booting.

The intent will contain the following extras:
{@link #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
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.

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.

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.

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.

public static final String
ACTION_APPWIDGET_RESTORED
Sent to an {@link 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:
{@link #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 {@link #EXTRA_APPWIDGET_IDS} extra.
{@link #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 {@link #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.

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:
{@link #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 {@link #EXTRA_APPWIDGET_IDS} extra.
{@link #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 {@link #EXTRA_APPWIDGET_OLD_IDS} array to its new value found at the corresponding index within this array.
{@link #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.

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 {@link #ACTION_APPWIDGET_RESTORED} broadcast intent.

The value will be an int array that can be retrieved like this: {@sample frameworks/base/tests/appwidgets/AppWidgetHostTest/src/com/android/tests/appwidgethost/TestAppWidgetProvider.java getExtra_EXTRA_APPWIDGET_IDS}

public static final String
META_DATA_APPWIDGET_PROVIDER
Field for the manifest meta-data tag.
private final String
mPackageName
private final com.android.internal.appwidget.IAppWidgetService
mService
private final android.util.DisplayMetrics
mDisplayMetrics
Constructors Summary
public AppWidgetManager(android.content.Context context, com.android.internal.appwidget.IAppWidgetService service)
Creates a new instance.

param
context The current context in which to operate.
param
service The backing system service.
hide

        mPackageName = context.getOpPackageName();
        mService = service;
        mDisplayMetrics = context.getResources().getDisplayMetrics();
Methods Summary
public voidbindAppWidgetId(int appWidgetId, android.content.ComponentName provider)
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. This method is used by the AppWidget picker and should not be used by other apps.

param
appWidgetId The AppWidget instance for which to set the RemoteViews.
param
provider The {@link android.content.BroadcastReceiver} that will be the AppWidget provider for this AppWidget.
hide

        if (mService == null) {
            return;
        }
        bindAppWidgetId(appWidgetId, provider, null);
public voidbindAppWidgetId(int appWidgetId, android.content.ComponentName provider, android.os.Bundle options)
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. This method is used by the AppWidget picker and should not be used by other apps.

param
appWidgetId The AppWidget instance for which to set the RemoteViews.
param
provider The {@link android.content.BroadcastReceiver} that will be the AppWidget provider for this AppWidget.
param
options Bundle containing options for the AppWidget. See also {@link #updateAppWidgetOptions(int, Bundle)}
hide

        if (mService == null) {
            return;
        }
        bindAppWidgetIdIfAllowed(appWidgetId, Process.myUserHandle(), provider, options);
public booleanbindAppWidgetIdIfAllowed(int appWidgetId, android.content.ComponentName provider)
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 {@link #ACTION_APPWIDGET_BIND} to request permission to bind

param
appWidgetId The AppWidget id under which to bind the provider.
param
provider The {@link android.content.BroadcastReceiver} that will be the AppWidget provider for this AppWidget.
return
true if this component has permission to bind the AppWidget

        if (mService == null) {
            return false;
        }
        return bindAppWidgetIdIfAllowed(appWidgetId, UserHandle.myUserId(), provider, null);
public booleanbindAppWidgetIdIfAllowed(int appWidgetId, android.content.ComponentName provider, android.os.Bundle options)
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 {@link #ACTION_APPWIDGET_BIND} to request permission to bind

param
appWidgetId The AppWidget id under which to bind the provider.
param
provider The {@link android.content.BroadcastReceiver} that will be the AppWidget provider for this AppWidget.
param
options Bundle containing options for the AppWidget. See also {@link #updateAppWidgetOptions(int, Bundle)}
return
true if this component has permission to bind the AppWidget

        if (mService == null) {
            return false;
        }
        return bindAppWidgetIdIfAllowed(appWidgetId, UserHandle.myUserId(), provider, options);
public booleanbindAppWidgetIdIfAllowed(int appWidgetId, android.os.UserHandle user, android.content.ComponentName provider, android.os.Bundle options)
Set the provider for a given appWidgetId if the caller has a permission.

Note: You need the {@link 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 {@link #ACTION_APPWIDGET_BIND} to request permission to bind.

param
appWidgetId The AppWidget id under which to bind the provider.
param
user The user id in which the provider resides.
param
provider The component name of the provider.
param
options An optional Bundle containing options for the AppWidget.
return
true if this component has permission to bind the AppWidget

        if (mService == null) {
            return false;
        }
        return bindAppWidgetIdIfAllowed(appWidgetId, user.getIdentifier(), provider, options);
private booleanbindAppWidgetIdIfAllowed(int appWidgetId, int profileId, android.content.ComponentName provider, android.os.Bundle options)

        if (mService == null) {
            return false;
        }
        try {
            return mService.bindAppWidgetId(mPackageName, appWidgetId,
                    profileId, provider, options);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public voidbindRemoteViewsService(java.lang.String packageName, int appWidgetId, android.content.Intent intent, android.os.IBinder connection)
Binds the RemoteViewsService for a given appWidgetId and intent. The appWidgetId specified must already be bound to the calling AppWidgetHost via {@link android.appwidget.AppWidgetManager#bindAppWidgetId AppWidgetManager.bindAppWidgetId()}.

param
packageName The package from which the binding is requested.
param
appWidgetId The AppWidget instance for which to bind the RemoteViewsService.
param
intent The intent of the service which will be providing the data to the RemoteViewsAdapter.
param
connection The callback interface to be notified when a connection is made or lost.
hide

        if (mService == null) {
            return;
        }
        try {
            mService.bindRemoteViewsService(packageName, appWidgetId, intent, connection);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
private voidconvertSizesToPixels(AppWidgetProviderInfo info)

        // Converting complex to dp.
        info.minWidth = TypedValue.complexToDimensionPixelSize(info.minWidth,
                mDisplayMetrics);
        info.minHeight = TypedValue.complexToDimensionPixelSize(info.minHeight,
                mDisplayMetrics);
        info.minResizeWidth = TypedValue.complexToDimensionPixelSize(info.minResizeWidth,
                mDisplayMetrics);
        info.minResizeHeight = TypedValue.complexToDimensionPixelSize(info.minResizeHeight,
                mDisplayMetrics);
public int[]getAppWidgetIds(android.content.ComponentName provider)
Get the list of appWidgetIds that have been bound to the given AppWidget provider.

param
provider The {@link android.content.BroadcastReceiver} that is the AppWidget provider to find appWidgetIds for.

        if (mService == null) {
            return new int[0];
        }
        try {
            return mService.getAppWidgetIds(provider);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public AppWidgetProviderInfogetAppWidgetInfo(int appWidgetId)
Get the available info about the AppWidget.

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

        if (mService == null) {
            return null;
        }
        try {
            AppWidgetProviderInfo info = mService.getAppWidgetInfo(mPackageName, appWidgetId);
            if (info != null) {
                // Converting complex to dp.
                convertSizesToPixels(info);
            }
            return info;
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public android.os.BundlegetAppWidgetOptions(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.

see
#updateAppWidgetOptions(int, Bundle)
param
appWidgetId The AppWidget instances for which to set the RemoteViews.
return
The options associated with the given widget instance.

        if (mService == null) {
            return Bundle.EMPTY;
        }
        try {
            return mService.getAppWidgetOptions(mPackageName, appWidgetId);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public java.util.ListgetInstalledProviders()
Return a list of the AppWidget providers that are currently installed.

        if (mService == null) {
            return Collections.emptyList();
        }
        return getInstalledProvidersForProfile(AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
                null);
public java.util.ListgetInstalledProviders(int categoryFilter)
Gets the AppWidget providers for the current user.

param
categoryFilter Will only return providers which register as any of the specified specified categories. See {@link AppWidgetProviderInfo#widgetCategory}.
return
The intalled providers.
see
android.os.Process#myUserHandle()
see
android.os.UserManager#getUserProfiles()
hide

        if (mService == null) {
            return Collections.emptyList();
        }
        return getInstalledProvidersForProfile(categoryFilter, null);
public java.util.ListgetInstalledProvidersForProfile(android.os.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.

param
profile The profile for which to get providers. Passing null is equivaled to passing only the current user handle.
return
The intalled providers.
see
android.os.Process#myUserHandle()
see
android.os.UserManager#getUserProfiles()

        if (mService == null) {
            return Collections.emptyList();
        }
        return getInstalledProvidersForProfile(AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
                profile);
public java.util.ListgetInstalledProvidersForProfile(int categoryFilter, android.os.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.

param
categoryFilter Will only return providers which register as any of the specified specified categories. See {@link AppWidgetProviderInfo#widgetCategory}.
param
profile A profile of the current user which to be queried. The user is itself also a profile. If null, the providers only for the current user are returned.
return
The intalled providers.
see
android.os.Process#myUserHandle()
see
android.os.UserManager#getUserProfiles()
hide

        if (mService == null) {
            return Collections.emptyList();
        }

        if (profile == null) {
            profile = Process.myUserHandle();
        }

        try {
            List<AppWidgetProviderInfo> providers = mService.getInstalledProvidersForProfile(
                    categoryFilter, profile.getIdentifier());
            if (providers == null) {
                return Collections.emptyList();
            }
            for (AppWidgetProviderInfo info : providers) {
                // Converting complex to dp.
                convertSizesToPixels(info);
            }
            return providers;
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public static android.appwidget.AppWidgetManagergetInstance(android.content.Context context)
Get the AppWidgetManager instance to use for the supplied {@link android.content.Context Context} object.


                      
         
        return (AppWidgetManager) context.getSystemService(Context.APPWIDGET_SERVICE);
public booleanhasBindAppWidgetPermission(java.lang.String packageName, int userId)
Query if a given package was granted permission by the user to bind app widgets

You need the MODIFY_APPWIDGET_BIND_PERMISSIONS permission

param
packageName The package for which the permission is being queried
param
userId The user id of the user under which the package runs.
return
true if the package was granted permission by the user to bind app widgets
hide

        if (mService == null) {
            return false;
        }
        try {
            return mService.hasBindAppWidgetPermission(packageName, userId);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public booleanhasBindAppWidgetPermission(java.lang.String packageName)
Query if a given package was granted permission by the user to bind app widgets

You need the MODIFY_APPWIDGET_BIND_PERMISSIONS permission

param
packageName The package for which the permission is being queried
return
true if the package was granted permission by the user to bind app widgets
hide

        if (mService == null) {
            return false;
        }
        try {
            return mService.hasBindAppWidgetPermission(packageName, UserHandle.myUserId());
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public voidnotifyAppWidgetViewDataChanged(int[] appWidgetIds, int viewId)
Notifies the specified collection view in all the specified AppWidget instances to invalidate their data.

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

        if (mService == null) {
            return;
        }
        try {
            mService.notifyAppWidgetViewDataChanged(mPackageName, appWidgetIds, viewId);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public voidnotifyAppWidgetViewDataChanged(int appWidgetId, int viewId)
Notifies the specified collection view in the specified AppWidget instance to invalidate its data.

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

        if (mService == null) {
            return;
        }
        notifyAppWidgetViewDataChanged(new int[] { appWidgetId }, viewId);
public voidpartiallyUpdateAppWidget(int[] appWidgetIds, android.widget.RemoteViews views)
Perform an incremental update or command on the widget(s) specified by appWidgetIds.

This update differs from {@link #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 {@link RemoteViews#showNext(int)}, {@link RemoteViews#showPrevious(int)}, {@link RemoteViews#setScrollPosition(int, int)} and similar commands.

It is okay to call this method both inside an {@link #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 {@link #updateAppWidget(int[], RemoteViews)}.

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

        if (mService == null) {
            return;
        }
        try {
            mService.partiallyUpdateAppWidgetIds(mPackageName, appWidgetIds, views);
        } catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public voidpartiallyUpdateAppWidget(int appWidgetId, android.widget.RemoteViews views)
Perform an incremental update or command on the widget specified by appWidgetId.

This update differs from {@link #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 {@link RemoteViews#showNext(int)}, {@link RemoteViews#showPrevious(int)}, {@link RemoteViews#setScrollPosition(int, int)} and similar commands.

It is okay to call this method both inside an {@link #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 {@link #updateAppWidget(int[], RemoteViews)}.

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

        if (mService == null) {
            return;
        }
        partiallyUpdateAppWidget(new int[] { appWidgetId }, views);
public voidsetBindAppWidgetPermission(java.lang.String packageName, boolean permission)
Changes any user-granted permission for the given package to bind app widgets

You need the MODIFY_APPWIDGET_BIND_PERMISSIONS permission

param
packageName The package whose permission is being changed
param
permission Whether to give the package permission to bind widgets
hide

        if (mService == null) {
            return;
        }
        setBindAppWidgetPermission(packageName, UserHandle.myUserId(), permission);
public voidsetBindAppWidgetPermission(java.lang.String packageName, int userId, boolean permission)
Changes any user-granted permission for the given package to bind app widgets

You need the MODIFY_APPWIDGET_BIND_PERMISSIONS permission

param
packageName The package whose permission is being changed
param
userId The user under which the package is running.
param
permission Whether to give the package permission to bind widgets
hide

        if (mService == null) {
            return;
        }
        try {
            mService.setBindAppWidgetPermission(packageName, userId, permission);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public voidunbindRemoteViewsService(java.lang.String packageName, int appWidgetId, android.content.Intent intent)
Unbinds the RemoteViewsService for a given appWidgetId and intent. The appWidgetId specified muse already be bound to the calling AppWidgetHost via {@link android.appwidget.AppWidgetManager#bindAppWidgetId AppWidgetManager.bindAppWidgetId()}.

param
packageName The package from which the binding is requested.
param
appWidgetId The AppWidget instance for which to bind the RemoteViewsService.
param
intent The intent of the service which will be providing the data to the RemoteViewsAdapter.
hide

        if (mService == null) {
            return;
        }
        try {
            mService.unbindRemoteViewsService(packageName, appWidgetId, intent);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public voidupdateAppWidget(int[] appWidgetIds, android.widget.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 {@link #partiallyUpdateAppWidget(int[], RemoteViews)}.

It is okay to call this method both inside an {@link #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.

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

        if (mService == null) {
            return;
        }
        try {
            mService.updateAppWidgetIds(mPackageName, appWidgetIds, views);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public voidupdateAppWidget(int appWidgetId, android.widget.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 {@link #partiallyUpdateAppWidget(int, RemoteViews)}.

It is okay to call this method both inside an {@link #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.

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

        if (mService == null) {
            return;
        }
        updateAppWidget(new int[] { appWidgetId }, views);
public voidupdateAppWidget(android.content.ComponentName provider, android.widget.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 {@link #ACTION_APPWIDGET_UPDATE} broadcast, and outside of the handler. This method will only work when called from the uid that owns the AppWidget provider.

param
provider The {@link ComponentName} for the {@link android.content.BroadcastReceiver BroadcastReceiver} provider for your AppWidget.
param
views The RemoteViews object to show.

        if (mService == null) {
            return;
        }
        try {
            mService.updateAppWidgetProvider(provider, views);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
public voidupdateAppWidgetOptions(int appWidgetId, android.os.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.

see
#getAppWidgetOptions(int)
param
appWidgetId The AppWidget instances for which to set the RemoteViews.
param
options The options to associate with this widget

        if (mService == null) {
            return;
        }
        try {
            mService.updateAppWidgetOptions(mPackageName, appWidgetId, options);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }