satya - Friday, December 09, 2011 3:10:18 PM

What are home screen 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.

satya - Friday, December 09, 2011 3:10:37 PM

widgets and remote views

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.

satya - Friday, December 09, 2011 3:10:52 PM

widgets and notications

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

satya - Friday, December 09, 2011 3:15:54 PM

A widget provider is a broadcast receiver invoked at certain intervals


<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>

satya - Friday, December 09, 2011 3:16:28 PM

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

satya - Friday, December 09, 2011 3:17:18 PM

Players


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

satya - Friday, December 09, 2011 3:18:14 PM

Peripheral players


widet layouts
Remote views
widget state management

satya - Friday, December 09, 2011 3:25:03 PM

Here is an example of widget definition xml


<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>

satya - Friday, December 09, 2011 3:26:41 PM

Key assets


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

satya - Saturday, December 10, 2011 9:42:16 AM

A typical widget provider responsibilities


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) {}
}

satya - Saturday, December 10, 2011 9:43:38 AM

onEnabled

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

satya - Saturday, December 10, 2011 9:44:00 AM

onDeleted()

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.

satya - Saturday, December 10, 2011 9:52:48 AM

onDisabled

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

satya - Saturday, December 10, 2011 9:53:57 AM

onUpdate()

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.

satya - Saturday, December 10, 2011 9:55:57 AM

onUpdate must finish its work in less than 10 seconds to avoid ANR

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.

satya - Saturday, December 10, 2011 10:02:10 AM

The configurator activity definition


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

satya - Saturday, December 10, 2011 10:03:39 AM

the label

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

satya - Saturday, December 10, 2011 10:24:51 AM

How choose a widget

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.

satya - Saturday, December 10, 2011 11:03:51 AM

See the complete list of code snippets for an example