1 /* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.appwidget; 18 19 import android.content.BroadcastReceiver; 20 import android.content.Context; 21 import android.content.Intent; 22 import android.os.Bundle; 23 24 /** 25 * A convenience class to aid in implementing an AppWidget provider. 26 * Everything you can do with AppWidgetProvider, you can do with a regular {@link BroadcastReceiver}. 27 * AppWidgetProvider merely parses the relevant fields out of the Intent that is received in 28 * {@link #onReceive(Context,Intent) onReceive(Context,Intent)}, and calls hook methods 29 * with the received extras. 30 * 31 * <p>Extend this class and override one or more of the {@link #onUpdate}, {@link #onDeleted}, 32 * {@link #onEnabled} or {@link #onDisabled} methods to implement your own AppWidget functionality. 33 * </p> 34 * 35 * <div class="special reference"> 36 * <h3>Developer Guides</h3> 37 * <p>For more information about how to write an app widget provider, read the 38 * <a href="{@docRoot}guide/topics/appwidgets/index.html#AppWidgetProvider">App Widgets</a> 39 * developer guide.</p> 40 * </div> 41 */ 42 public class AppWidgetProvider extends BroadcastReceiver { 43 /** 44 * Constructor to initialize AppWidgetProvider. 45 */ AppWidgetProvider()46 public AppWidgetProvider() { 47 } 48 49 /** 50 * Implements {@link BroadcastReceiver#onReceive} to dispatch calls to the various 51 * other methods on AppWidgetProvider. 52 * 53 * @param context The Context in which the receiver is running. 54 * @param intent The Intent being received. 55 */ 56 // BEGIN_INCLUDE(onReceive) onReceive(Context context, Intent intent)57 public void onReceive(Context context, Intent intent) { 58 // Protect against rogue update broadcasts (not really a security issue, 59 // just filter bad broacasts out so subclasses are less likely to crash). 60 String action = intent.getAction(); 61 if (AppWidgetManager.ACTION_APPWIDGET_UPDATE.equals(action)) { 62 Bundle extras = intent.getExtras(); 63 if (extras != null) { 64 int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS); 65 if (appWidgetIds != null && appWidgetIds.length > 0) { 66 this.onUpdate(context, AppWidgetManager.getInstance(context), appWidgetIds); 67 } 68 } 69 } else if (AppWidgetManager.ACTION_APPWIDGET_DELETED.equals(action)) { 70 Bundle extras = intent.getExtras(); 71 if (extras != null && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_ID)) { 72 final int appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID); 73 this.onDeleted(context, new int[] { appWidgetId }); 74 } 75 } else if (AppWidgetManager.ACTION_APPWIDGET_OPTIONS_CHANGED.equals(action)) { 76 Bundle extras = intent.getExtras(); 77 if (extras != null && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_ID) 78 && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS)) { 79 int appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID); 80 Bundle widgetExtras = extras.getBundle(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS); 81 this.onAppWidgetOptionsChanged(context, AppWidgetManager.getInstance(context), 82 appWidgetId, widgetExtras); 83 } 84 } else if (AppWidgetManager.ACTION_APPWIDGET_ENABLED.equals(action)) { 85 this.onEnabled(context); 86 } else if (AppWidgetManager.ACTION_APPWIDGET_DISABLED.equals(action)) { 87 this.onDisabled(context); 88 } else if (AppWidgetManager.ACTION_APPWIDGET_RESTORED.equals(action)) { 89 Bundle extras = intent.getExtras(); 90 if (extras != null) { 91 int[] oldIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_OLD_IDS); 92 int[] newIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS); 93 if (oldIds != null && oldIds.length > 0) { 94 this.onRestored(context, oldIds, newIds); 95 this.onUpdate(context, AppWidgetManager.getInstance(context), newIds); 96 } 97 } 98 } 99 } 100 // END_INCLUDE(onReceive) 101 102 /** 103 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_UPDATE} and 104 * {@link AppWidgetManager#ACTION_APPWIDGET_RESTORED} broadcasts when this AppWidget 105 * provider is being asked to provide {@link android.widget.RemoteViews RemoteViews} 106 * for a set of AppWidgets. Override this method to implement your own AppWidget functionality. 107 * 108 * {@more} 109 * 110 * @param context The {@link android.content.Context Context} in which this receiver is 111 * running. 112 * @param appWidgetManager A {@link AppWidgetManager} object you can call {@link 113 * AppWidgetManager#updateAppWidget} on. 114 * @param appWidgetIds The appWidgetIds for which an update is needed. Note that this 115 * may be all of the AppWidget instances for this provider, or just 116 * a subset of them. 117 * 118 * @see AppWidgetManager#ACTION_APPWIDGET_UPDATE 119 */ onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds)120 public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { 121 } 122 123 /** 124 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_OPTIONS_CHANGED} 125 * broadcast when this widget has been layed out at a new size. 126 * 127 * {@more} 128 * 129 * @param context The {@link android.content.Context Context} in which this receiver is 130 * running. 131 * @param appWidgetManager A {@link AppWidgetManager} object you can call {@link 132 * AppWidgetManager#updateAppWidget} on. 133 * @param appWidgetId The appWidgetId of the widget whose size changed. 134 * @param newOptions The appWidgetId of the widget whose size changed. 135 * 136 * @see AppWidgetManager#ACTION_APPWIDGET_OPTIONS_CHANGED 137 */ onAppWidgetOptionsChanged(Context context, AppWidgetManager appWidgetManager, int appWidgetId, Bundle newOptions)138 public void onAppWidgetOptionsChanged(Context context, AppWidgetManager appWidgetManager, 139 int appWidgetId, Bundle newOptions) { 140 } 141 142 /** 143 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DELETED} broadcast when 144 * one or more AppWidget instances have been deleted. Override this method to implement 145 * your own AppWidget functionality. 146 * 147 * {@more} 148 * 149 * @param context The {@link android.content.Context Context} in which this receiver is 150 * running. 151 * @param appWidgetIds The appWidgetIds that have been deleted from their host. 152 * 153 * @see AppWidgetManager#ACTION_APPWIDGET_DELETED 154 */ onDeleted(Context context, int[] appWidgetIds)155 public void onDeleted(Context context, int[] appWidgetIds) { 156 } 157 158 /** 159 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_ENABLED} broadcast when 160 * the a AppWidget for this provider is instantiated. Override this method to implement your 161 * own AppWidget functionality. 162 * 163 * {@more} 164 * When the last AppWidget for this provider is deleted, 165 * {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} is sent by the AppWidget manager, and 166 * {@link #onDisabled} is called. If after that, an AppWidget for this provider is created 167 * again, onEnabled() will be called again. 168 * 169 * @param context The {@link android.content.Context Context} in which this receiver is 170 * running. 171 * 172 * @see AppWidgetManager#ACTION_APPWIDGET_ENABLED 173 */ onEnabled(Context context)174 public void onEnabled(Context context) { 175 } 176 177 /** 178 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} broadcast, which 179 * is sent when the last AppWidget instance for this provider is deleted. Override this method 180 * to implement your own AppWidget functionality. 181 * 182 * {@more} 183 * 184 * @param context The {@link android.content.Context Context} in which this receiver is 185 * running. 186 * 187 * @see AppWidgetManager#ACTION_APPWIDGET_DISABLED 188 */ onDisabled(Context context)189 public void onDisabled(Context context) { 190 } 191 192 /** 193 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_RESTORED} broadcast 194 * when instances of this AppWidget provider have been restored from backup. If your 195 * provider maintains any persistent data about its widget instances, override this method 196 * to remap the old AppWidgetIds to the new values and update any other app state that may 197 * be relevant. 198 * 199 * <p>This callback will be followed immediately by a call to {@link #onUpdate} so your 200 * provider can immediately generate new RemoteViews suitable for its newly-restored set 201 * of instances. 202 * 203 * {@more} 204 * 205 * @param context 206 * @param oldWidgetIds 207 * @param newWidgetIds 208 */ onRestored(Context context, int[] oldWidgetIds, int[] newWidgetIds)209 public void onRestored(Context context, int[] oldWidgetIds, int[] newWidgetIds) { 210 } 211 } 212