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