Understand homescreen widgets

Understand homescreen widgets

home screen widgets are disconnected views (albeit populated with data, also called remote views) that are displayed on the home screen. The data content of these views is updated at regular intervals by background processes.

Once someone makes the widgets available, a user can drag them on to the home screen to see the frequently updated content. These widgets can be resized and scaled in newer android versions.

The remote views that are used for widgets are quite related the way notifications are displayed by a notification manager as well. 


<receiver android:name=".BDayWidgetProvider">
   <meta-data android:name="android.appwidget.provider"
          android:resource="@xml/bday_appwidget_provider" />
   <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
</receiver>

This receiver is ultimately responsible for updating the widget view through the widget manager


Widget Provider (a derived bc receiver)
widget definition XML file
widget configuration activity


widet layouts
Remote views
widget state management


<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="150dp"
    android:minHeight="120dp"
    android:updatePeriodMillis="43200000"
    android:initialLayout="@layout/bday_widget"
    android:configure="com.ai.android.BDayWidget.ConfigureBDayWidgetActivity"
    >
</appwidget-provider>


@xml/bday_appwidget_provider
BDayWidgetProvider
com.ai.android.BDayWidget.ConfigureBDayWidgetActivity
@layout/bday_widget


public class BDayWidgetProvider extends AppWidgetProvider 
{
    public void onUpdate(Context context, 
                        AppWidgetManager appWidgetManager, 
                        int[] appWidgetIds){} 
    
    public void onDeleted(Context context, int[] appWidgetIds){} 
    public void onEnabled(Context context){} 
    public void onDisabled(Context context) {}
}

The onEnabled() callback method indicates that there is at least one instance of the widget up and running on the home screen. This means a user must have dropped the widget on the home page at least once. In this call, you will need to enable receiving messages for this broadcast receiver component (you will see this in Listing 25?9). The base class AppWidgetProvider has the functionality to enable or disable receiving broadcast messages

The onDeleted() callback method is called when a user drags the widget instance view to the trash can. This is where you will need to delete any persistence values you are holding for that widget instance.

The onDisabled() callback method is called after the last widget instance is removed from the home screen. This happens when a user drags the last instance of a widget to the trash. You should use this method to unregister your interest in receiving any broadcast messages intended for this component

The onUpdate() callback method is called every time the timer specified in expires. This method is also called the very first time the widget instance is created if there is no configurator activity. If there is a configurator activity, this method is not called at the creation of a widget instance. This method will subsequently be called when the timer expires at the frequency indicated.

because onUdpate is called through a broadcast receiver that runs on the main thread. If it takes longer you will need to start a service and spawn a thread through that service. Both are important. Starting a thread is not sufficient by itself, as the process can get killed when the broadcast receiver exits. Having a service gurantees the process will be up while the thread does its work. 


<activity android:name=".ConfigureBDayWidgetActivity"
                  android:label="Configure Birthday Widget">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" />
       </intent-filter>
</activity>

The application label identified by "Birthday Widget" in the following line 


<application android:icon="@drawable/icon" android:label="Birthday Widget">

is what shows up in the widget pick list

Previously you long click on the home page to navigate to your widgets. In ICS the widgets is a tab on the list of applications activity. So click on "apps" on the home page. You will see a tab then called "widgets". Again this is the emulator. On a real device there may be more variations.

See the complete list of code snippets for an example