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 } 77d2097ebacf3a3658624cad10669a4d98e8d7d846Adam Cohen else if (AppWidgetManager.ACTION_APPWIDGET_OPTIONS_CHANGED.equals(action)) { 78e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen Bundle extras = intent.getExtras(); 79e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen if (extras != null && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_ID) 80d2097ebacf3a3658624cad10669a4d98e8d7d846Adam Cohen && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS)) { 81e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen int appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID); 82d2097ebacf3a3658624cad10669a4d98e8d7d846Adam Cohen Bundle widgetExtras = extras.getBundle(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS); 83d2097ebacf3a3658624cad10669a4d98e8d7d846Adam Cohen this.onAppWidgetOptionsChanged(context, AppWidgetManager.getInstance(context), 84e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen appWidgetId, widgetExtras); 85e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen } 86e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen } 87c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project else if (AppWidgetManager.ACTION_APPWIDGET_ENABLED.equals(action)) { 88c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project this.onEnabled(context); 89c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 90c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project else if (AppWidgetManager.ACTION_APPWIDGET_DISABLED.equals(action)) { 91c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project this.onDisabled(context); 92c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 93c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 94c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project // END_INCLUDE(onReceive) 95e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen 96c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 97c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_UPDATE} broadcast when 98c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * this AppWidget provider is being asked to provide {@link android.widget.RemoteViews RemoteViews} 99c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * for a set of AppWidgets. Override this method to implement your own AppWidget functionality. 100c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 101c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 102c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 103c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 104c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 105c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param appWidgetManager A {@link AppWidgetManager} object you can call {@link 106c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * AppWidgetManager#updateAppWidget} on. 107c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param appWidgetIds The appWidgetIds for which an update is needed. Note that this 108c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * may be all of the AppWidget instances for this provider, or just 109c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * a subset of them. 110c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 111c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_UPDATE 112c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 113c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { 114c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 115e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen 116e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen /** 117d2097ebacf3a3658624cad10669a4d98e8d7d846Adam Cohen * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_OPTIONS_CHANGED} 118e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * broadcast when this widget has been layed out at a new size. 119e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * 120e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * {@more} 121e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * 122e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * @param context The {@link android.content.Context Context} in which this receiver is 123e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * running. 124e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * @param appWidgetManager A {@link AppWidgetManager} object you can call {@link 125e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * AppWidgetManager#updateAppWidget} on. 126e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * @param appWidgetId The appWidgetId of the widget who's size changed. 127d2097ebacf3a3658624cad10669a4d98e8d7d846Adam Cohen * @param newOptions The appWidgetId of the widget who's size changed. 128e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen * 129d2097ebacf3a3658624cad10669a4d98e8d7d846Adam Cohen * @see AppWidgetManager#ACTION_APPWIDGET_OPTIONS_CHANGED 130e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen */ 131d2097ebacf3a3658624cad10669a4d98e8d7d846Adam Cohen public void onAppWidgetOptionsChanged(Context context, AppWidgetManager appWidgetManager, 132d2097ebacf3a3658624cad10669a4d98e8d7d846Adam Cohen int appWidgetId, Bundle newOptions) { 133e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen } 134e8724c82ab1479f13c85a2c6219841e1fd95f2d2Adam Cohen 135c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 136c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DELETED} broadcast when 137c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * one or more AppWidget instances have been deleted. Override this method to implement 138c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * your own AppWidget functionality. 139c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 140c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 141c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 142c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 143c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 144c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param appWidgetIds The appWidgetIds that have been deleted from their host. 145c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 146c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_DELETED 147c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 148c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onDeleted(Context context, int[] appWidgetIds) { 149c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 150c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 151c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 152c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_ENABLED} broadcast when 153c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * the a AppWidget for this provider is instantiated. Override this method to implement your 154c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * own AppWidget functionality. 155c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 156c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 157c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * When the last AppWidget for this provider is deleted, 158c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} is sent by the AppWidget manager, and 159c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@link #onDisabled} is called. If after that, an AppWidget for this provider is created 160c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * again, onEnabled() will be called again. 161c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 162c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 163c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 164c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 165c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_ENABLED 166c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 167c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onEnabled(Context context) { 168c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 169c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project 170c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project /** 171c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} broadcast, which 172c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * is sent when the last AppWidget instance for this provider is deleted. Override this method 173c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * to implement your own AppWidget functionality. 174c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 175c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * {@more} 176c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 177c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @param context The {@link android.content.Context Context} in which this receiver is 178c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * running. 179c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * 180c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project * @see AppWidgetManager#ACTION_APPWIDGET_DISABLED 181c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project */ 182c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project public void onDisabled(Context context) { 183c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project } 184c39a6e0c51e182338deb8b63d07933b585134929The Android Open Source Project} 185