AppWidgetProvider.java revision 3aef8e1d1b2f0b87d470bcccf37ba4ebb6560c45
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/** 2560b88edea7132ddce90f2dced07c6706f1502270Ken Shirriff * A convenience 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> 343aef8e1d1b2f0b87d470bcccf37ba4ebb6560c45Joe Fernandez * 353aef8e1d1b2f0b87d470bcccf37ba4ebb6560c45Joe Fernandez * <div class="special reference"> 363aef8e1d1b2f0b87d470bcccf37ba4ebb6560c45Joe Fernandez * <h3>Developer Guides</h3> 373aef8e1d1b2f0b87d470bcccf37ba4ebb6560c45Joe Fernandez * <p>For more information about how to write an app widget provider, read the 383aef8e1d1b2f0b87d470bcccf37ba4ebb6560c45Joe Fernandez * <a href="{@docRoot}guide/topics/appwidgets/index.html#AppWidgetProvider">App Widgets</a> 393aef8e1d1b2f0b87d470bcccf37ba4ebb6560c45Joe Fernandez * developer guide.</p> 403aef8e1d1b2f0b87d470bcccf37ba4ebb6560c45Joe Fernandez * </div> 41c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 42c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Projectpublic class AppWidgetProvider extends BroadcastReceiver { 43c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 44c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Constructor to initialize AppWidgetProvider. 45c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 46c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public AppWidgetProvider() { 47c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 48c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 49c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 50c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Implements {@link BroadcastReceiver#onReceive} to dispatch calls to the various 51c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * other methods on AppWidgetProvider. 52c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 53c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The Context in which the receiver is running. 54c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param intent The Intent being received. 55c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 56c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project // BEGIN_INCLUDE(onReceive) 57c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onReceive(Context context, Intent intent) { 58c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project // Protect against rogue update broadcasts (not really a security issue, 59c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project // just filter bad broacasts out so subclasses are less likely to crash). 60c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project String action = intent.getAction(); 61c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project if (AppWidgetManager.ACTION_APPWIDGET_UPDATE.equals(action)) { 62c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project Bundle extras = intent.getExtras(); 63c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project if (extras != null) { 64c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS); 65c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project if (appWidgetIds != null && appWidgetIds.length > 0) { 66c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project this.onUpdate(context, AppWidgetManager.getInstance(context), appWidgetIds); 67c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 68c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 69c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 70c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project else if (AppWidgetManager.ACTION_APPWIDGET_DELETED.equals(action)) { 71c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project Bundle extras = intent.getExtras(); 72eda4be30a2a3a63093faf052be5d804bf633e6f5Jeff Sharkey if (extras != null && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_ID)) { 73eda4be30a2a3a63093faf052be5d804bf633e6f5Jeff Sharkey final int appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID); 74eda4be30a2a3a63093faf052be5d804bf633e6f5Jeff Sharkey this.onDeleted(context, new int[] { appWidgetId }); 75c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 76c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 77c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project else if (AppWidgetManager.ACTION_APPWIDGET_ENABLED.equals(action)) { 78c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project this.onEnabled(context); 79c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 80c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project else if (AppWidgetManager.ACTION_APPWIDGET_DISABLED.equals(action)) { 81c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project this.onDisabled(context); 82c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 83c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 84c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project // END_INCLUDE(onReceive) 85c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 86c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 87c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_UPDATE} broadcast when 88c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * this AppWidget provider is being asked to provide {@link android.widget.RemoteViews RemoteViews} 89c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * for a set of AppWidgets. Override this method to implement your own AppWidget functionality. 90c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 91c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 92c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 93c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 94c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 95c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param appWidgetManager A {@link AppWidgetManager} object you can call {@link 96c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * AppWidgetManager#updateAppWidget} on. 97c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param appWidgetIds The appWidgetIds for which an update is needed. Note that this 98c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * may be all of the AppWidget instances for this provider, or just 99c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * a subset of them. 100c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 101c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_UPDATE 102c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 103c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { 104c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 105c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 106c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 107c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DELETED} broadcast when 108c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * one or more AppWidget instances have been deleted. Override this method to implement 109c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * your own AppWidget functionality. 110c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 111c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 112c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 113c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 114c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 115c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param appWidgetIds The appWidgetIds that have been deleted from their host. 116c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 117c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_DELETED 118c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 119c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onDeleted(Context context, int[] appWidgetIds) { 120c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 121c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 122c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 123c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_ENABLED} broadcast when 124c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * the a AppWidget for this provider is instantiated. Override this method to implement your 125c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * own AppWidget functionality. 126c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 127c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 128c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * When the last AppWidget for this provider is deleted, 129c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} is sent by the AppWidget manager, and 130c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@link #onDisabled} is called. If after that, an AppWidget for this provider is created 131c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * again, onEnabled() will be called again. 132c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 133c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 134c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 135c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 136c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_ENABLED 137c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 138c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onEnabled(Context context) { 139c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 140c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 141c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 142c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} broadcast, which 143c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * is sent when the last AppWidget instance for this provider is deleted. Override this method 144c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * to implement your own AppWidget functionality. 145c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 146c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 147c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 148c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 149c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 150c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 151c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_DISABLED 152c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 153c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onDisabled(Context context) { 154c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 155c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project} 156