AppWidget Tutorial

AppWidget Overview

Most applications on Android have to be launched with a launcher, but classes extending the AppWidgetProvider class will be shown among your available widgets.  This tutorial loosely follows the AppWidget Guide

How Widgets Work

AppWidgets need the following to work:

• AppWidgetProviderInfo object: This object describes the metadata for an AppWidget; things like the layout, update frequency and the WppWidgetProvider class. This will be an xml file you create later.
• AppWidgetProvder class: Defines the basic methods that allow you to interface with the AppWidget though broadcast events for when the AppWidget is updated,enabled,disabled and deleted.
• AppWidgetConfiguration activity: OPTIONAL activity that runs when the user adds your AppWidget, it allows them to modify settings at create-time.

Part 1: Setup

Create a new Android project with no activity in eclipse (this tutorial assumes you have already setup eclipse and android if you haven’t visit: Developing Android with Eclipse

Part 2: AppWidgetProviderInfo

Now that we have created a new project, go to file->new->other..->Android->Android XML File and create the AppWidgetProviderInfo file. Now that we have created the xml file, edit its info:

Part 3: AppWidget Layout

You must define an initial layout for the AppWidget with an xml file saved in res/layout. The only caveat is that AppWidget are based on RemoteViews and therefore only support a few layout classes, namely the following:

• FrameLayout
• LinearLayout
• RelativeLayout

and the following widget classes:

• AnalogClock
• Button
• Chronometer
• ImageButton
• ImageView
• ProgressBar
• TextView

We will next define a simple file, widget_layout.xml by creating a new file in eclipse: file->new->file:

Right click the file in eclipse and select Open With -> XML Editor and enter the following code:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout
	xmlns:android="http://schemas.android.com/apk/res/android"
	android:layout_width="wrap_content"
	android:layout_height="wrap_content"
	android:orientation="vertical">
 
	<TextView
		android:id="@+id/date"
		android:layout_width="wrap_content"
		android:layout_height="wrap_content">
	</TextView>
	<TextView
		android:id="@id/event"
		android:layout_width="wrap_content"
		android:layout_height="wrap_content">
	</TextView>
</LinearLayout>

This will setup our layout to have a date textView and an event textView – simple initial layout.

Part 3: Extending the AppWidgetProvider Class

AppWidgetProvider extends the BroadcastReciever class to handle AppWidget broadcasts. It only receives broadcasts related to the AppWidget such as when the AppWidget is updated, deleted,enabled or disabled. First, let’s create our own AppWidgetProvider, notice how it extends AppWidgetProvider:
Here is the code to extend the AppWidgetProvider:

package com.eosgood.itsdue.widget;
 
import java.text.SimpleDateFormat;
import java.util.Calendar;
 
import android.appwidget.AppWidgetManager;
import android.appwidget.AppWidgetProvider;
import android.content.Context;
import android.widget.RemoteViews;
 
public class ItsdueAppWidgetProvider extends AppWidgetProvider {
 
	public static final String DATE_FORMAT_NOW = "yyyy-MM-dd HH:mm:ss";
 
	public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        final int N = appWidgetIds.length;
 
        // loop through all app widgets the user has enabled
        for (int i=0;i<N; i++){
        	int widgetId = appWidgetIds[i];
 
        	// get the current date
        	String current = now();
 
        	// get our view so we can edit the time
        	RemoteViews views = new RemoteViews(context.getPackageName(),
					R.layout.initial_layout);
 
        	views.setTextViewText(R.id.date, current);
 
        	// download an event from gmail and set it up (to come...)
        	// for now well just make a dummy one
        	views.setTextViewText(R.id.event, "Some sweet Event text!!!!");
 
        	// update the widget
        	appWidgetManager.updateAppWidget(widgetId, views);
 
        }
	}
 
	public static String now(){
		Calendar cal = Calendar.getInstance();
		SimpleDateFormat sdf = new SimpleDateFormat(DATE_FORMAT_NOW);
		return sdf.format(cal.getTime());
	}
}

Part 4: Updating the Manifest

We need to update our manifest to reflect how our appwidget works. Open AndroidManifest.xml by right-clicking it and Open With->XML Editor.
Add the following code between the tags:

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

Part 5: Adding Your Widget

Navigate to a free screen on your phone and long-click and add your widget – you’re done you have successfully created your first app widget