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