AppWidgetProvider.java revision 8a4c53a7c7911b8f4c73a8fcfbbad3ac903b3367
1c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project/* 2c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Copyright (C) 2006 The Android Open Source Project 3c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 4c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); 5c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * you may not use this file except in compliance with the License. 6c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * You may obtain a copy of the License at 7c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 8c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 9c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 10c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Unless required by applicable law or agreed to in writing, software 11c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 12c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * See the License for the specific language governing permissions and 14c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * limitations under the License. 15c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 16c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 17c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Projectpackage android.appwidget; 18c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 19c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Projectimport android.content.BroadcastReceiver; 20c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Projectimport android.content.Context; 21c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Projectimport android.content.Intent; 22c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Projectimport android.os.Bundle; 23c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 24c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project/** 25c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * A conveience class to aid in implementing an AppWidget provider. 26c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Everything you can do with AppWidgetProvider, you can do with a regular {@link BroadcastReceiver}. 27c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * AppWidgetProvider merely parses the relevant fields out of the Intent that is received in 28c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@link #onReceive(Context,Intent) onReceive(Context,Intent)}, and calls hook methods 29c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * with the received extras. 30c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 31c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * <p>Extend this class and override one or more of the {@link #onUpdate}, {@link #onDeleted}, 32c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@link #onEnabled} or {@link #onDisabled} methods to implement your own AppWidget functionality. 338a4c53a7c7911b8f4c73a8fcfbbad3ac903b3367Scott Main * </p> 348a4c53a7c7911b8f4c73a8fcfbbad3ac903b3367Scott Main * <p>For an example of how to write a AppWidget provider, see the 358a4c53a7c7911b8f4c73a8fcfbbad3ac903b3367Scott Main * <a href="{@docRoot}guide/topics/appwidgets/index.html#Providers">AppWidgets</a> documentation.</p> 36c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 37c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Projectpublic class AppWidgetProvider extends BroadcastReceiver { 38c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 39c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Constructor to initialize AppWidgetProvider. 40c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 41c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public AppWidgetProvider() { 42c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 43c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 44c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 45c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Implements {@link BroadcastReceiver#onReceive} to dispatch calls to the various 46c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * other methods on AppWidgetProvider. 47c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 48c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The Context in which the receiver is running. 49c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param intent The Intent being received. 50c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 51c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project // BEGIN_INCLUDE(onReceive) 52c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onReceive(Context context, Intent intent) { 53c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project // Protect against rogue update broadcasts (not really a security issue, 54c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project // just filter bad broacasts out so subclasses are less likely to crash). 55c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project String action = intent.getAction(); 56c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project if (AppWidgetManager.ACTION_APPWIDGET_UPDATE.equals(action)) { 57c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project Bundle extras = intent.getExtras(); 58c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project if (extras != null) { 59c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS); 60c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project if (appWidgetIds != null && appWidgetIds.length > 0) { 61c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project this.onUpdate(context, AppWidgetManager.getInstance(context), appWidgetIds); 62c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 63c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 64c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 65c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project else if (AppWidgetManager.ACTION_APPWIDGET_DELETED.equals(action)) { 66c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project Bundle extras = intent.getExtras(); 67c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project if (extras != null) { 68c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS); 69c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project if (appWidgetIds != null && appWidgetIds.length > 0) { 70c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project this.onDeleted(context, appWidgetIds); 71c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 72c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 73c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 74c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project else if (AppWidgetManager.ACTION_APPWIDGET_ENABLED.equals(action)) { 75c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project this.onEnabled(context); 76c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 77c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project else if (AppWidgetManager.ACTION_APPWIDGET_DISABLED.equals(action)) { 78c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project this.onDisabled(context); 79c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 80c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 81c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project // END_INCLUDE(onReceive) 82c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 83c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 84c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_UPDATE} broadcast when 85c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * this AppWidget provider is being asked to provide {@link android.widget.RemoteViews RemoteViews} 86c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * for a set of AppWidgets. Override this method to implement your own AppWidget functionality. 87c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 88c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 89c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 90c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 91c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 92c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param appWidgetManager A {@link AppWidgetManager} object you can call {@link 93c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * AppWidgetManager#updateAppWidget} on. 94c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param appWidgetIds The appWidgetIds for which an update is needed. Note that this 95c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * may be all of the AppWidget instances for this provider, or just 96c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * a subset of them. 97c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 98c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_UPDATE 99c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 100c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { 101c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 102c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 103c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 104c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DELETED} broadcast when 105c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * one or more AppWidget instances have been deleted. Override this method to implement 106c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * your own AppWidget functionality. 107c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 108c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 109c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 110c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 111c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 112c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param appWidgetIds The appWidgetIds that have been deleted from their host. 113c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 114c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_DELETED 115c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 116c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onDeleted(Context context, int[] appWidgetIds) { 117c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 118c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 119c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 120c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_ENABLED} broadcast when 121c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * the a AppWidget for this provider is instantiated. Override this method to implement your 122c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * own AppWidget functionality. 123c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 124c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 125c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * When the last AppWidget for this provider is deleted, 126c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} is sent by the AppWidget manager, and 127c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@link #onDisabled} is called. If after that, an AppWidget for this provider is created 128c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * again, onEnabled() will be called again. 129c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 130c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 131c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 132c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 133c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_ENABLED 134c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 135c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onEnabled(Context context) { 136c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 137c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 138c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 139c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} broadcast, which 140c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * is sent when the last AppWidget instance for this provider is deleted. Override this method 141c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * to implement your own AppWidget functionality. 142c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 143c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 144c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 145c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 146c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 147c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 148c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_DISABLED 149c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 150c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onDisabled(Context context) { 151c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 152c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project} 153