FileDocCategorySizeDatePackage
AppWidgetManager.javaAPI DocAndroid 1.5 API13082Wed May 06 22:41:54 BST 2009android.appwidget

AppWidgetManager

public class AppWidgetManager extends Object
Updates AppWidget state; gets information about installed AppWidget providers and other AppWidget related state.

Fields Summary
static final String
TAG
public static final String
ACTION_APPWIDGET_PICK
Send this 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_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
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_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_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 int
INVALID_APPWIDGET_ID
A sentiel 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_DELETED
Sent when an instance of an AppWidget is deleted from its host.
public static final String
ACTION_APPWIDGET_DISABLED
Sent when an instance of an AppWidget is removed from the last host.
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.
public static final String
META_DATA_APPWIDGET_PROVIDER
Field for the manifest meta-data tag.
static WeakHashMap
sManagerCache
static com.android.internal.appwidget.IAppWidgetService
sService
android.content.Context
mContext
Constructors Summary
private AppWidgetManager(android.content.Context context)

        mContext = context;
Methods Summary
public voidbindAppWidgetId(int appWidgetId, android.content.ComponentName provider)
Set the component for a given appWidgetId.

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

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.

        try {
            sService.bindAppWidgetId(appWidgetId, provider);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }
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.

        try {
            return sService.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.

        try {
            return sService.getAppWidgetInfo(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.

        try {
            return sService.getInstalledProviders();
        }
        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.


                      
         
        synchronized (sManagerCache) {
            if (sService == null) {
                IBinder b = ServiceManager.getService(Context.APPWIDGET_SERVICE);
                sService = IAppWidgetService.Stub.asInterface(b);
            }

            WeakReference<AppWidgetManager> ref = sManagerCache.get(context);
            AppWidgetManager result = null;
            if (ref != null) {
                result = ref.get();
            }
            if (result == null) {
                result = new AppWidgetManager(context);
                sManagerCache.put(context, new WeakReference(result));
            }
            return result;
        }
public voidupdateAppWidget(int[] appWidgetIds, android.widget.RemoteViews views)
Set the RemoteViews to use for the specified appWidgetIds.

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
appWidgetIds The AppWidget instances for which to set the RemoteViews.
param
views The RemoteViews object to show.

        try {
            sService.updateAppWidgetIds(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.

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
appWidgetId The AppWidget instance for which to set the RemoteViews.
param
views The RemoteViews object to show.

        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.

        try {
            sService.updateAppWidgetProvider(provider, views);
        }
        catch (RemoteException e) {
            throw new RuntimeException("system server dead?", e);
        }