AppWidgetProvider.java revision 60b88edea7132ddce90f2dced07c6706f1502270
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 17package android.appwidget; 18 19import android.content.BroadcastReceiver; 20import android.content.Context; 21import android.content.Intent; 22import 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 */ 37public 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) { 68 int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS); 69 if (appWidgetIds != null && appWidgetIds.length > 0) { 70 this.onDeleted(context, appWidgetIds); 71 } 72 } 73 } 74 else if (AppWidgetManager.ACTION_APPWIDGET_ENABLED.equals(action)) { 75 this.onEnabled(context); 76 } 77 else if (AppWidgetManager.ACTION_APPWIDGET_DISABLED.equals(action)) { 78 this.onDisabled(context); 79 } 80 } 81 // END_INCLUDE(onReceive) 82 83 /** 84 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_UPDATE} broadcast when 85 * this AppWidget provider is being asked to provide {@link android.widget.RemoteViews RemoteViews} 86 * for a set of AppWidgets. Override this method to implement your own AppWidget functionality. 87 * 88 * {@more} 89 * 90 * @param context The {@link android.content.Context Context} in which this receiver is 91 * running. 92 * @param appWidgetManager A {@link AppWidgetManager} object you can call {@link 93 * AppWidgetManager#updateAppWidget} on. 94 * @param appWidgetIds The appWidgetIds for which an update is needed. Note that this 95 * may be all of the AppWidget instances for this provider, or just 96 * a subset of them. 97 * 98 * @see AppWidgetManager#ACTION_APPWIDGET_UPDATE 99 */ 100 public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { 101 } 102 103 /** 104 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DELETED} broadcast when 105 * one or more AppWidget instances have been deleted. Override this method to implement 106 * 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 appWidgetIds The appWidgetIds that have been deleted from their host. 113 * 114 * @see AppWidgetManager#ACTION_APPWIDGET_DELETED 115 */ 116 public void onDeleted(Context context, int[] appWidgetIds) { 117 } 118 119 /** 120 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_ENABLED} broadcast when 121 * the a AppWidget for this provider is instantiated. Override this method to implement your 122 * own AppWidget functionality. 123 * 124 * {@more} 125 * When the last AppWidget for this provider is deleted, 126 * {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} is sent by the AppWidget manager, and 127 * {@link #onDisabled} is called. If after that, an AppWidget for this provider is created 128 * again, onEnabled() will be called again. 129 * 130 * @param context The {@link android.content.Context Context} in which this receiver is 131 * running. 132 * 133 * @see AppWidgetManager#ACTION_APPWIDGET_ENABLED 134 */ 135 public void onEnabled(Context context) { 136 } 137 138 /** 139 * Called in response to the {@link AppWidgetManager#ACTION_APPWIDGET_DISABLED} broadcast, which 140 * is sent when the last AppWidget instance for this provider is deleted. Override this method 141 * to implement your own AppWidget functionality. 142 * 143 * {@more} 144 * 145 * @param context The {@link android.content.Context Context} in which this receiver is 146 * running. 147 * 148 * @see AppWidgetManager#ACTION_APPWIDGET_DISABLED 149 */ 150 public void onDisabled(Context context) { 151 } 152} 153