Android Phone-Top Programming: Part 1

The Differentiator

There are a lot of reasons to like today’s smartphones.

Connectivity.

Speed

Status symbol even.

Battery life. Just kidding — this one isn’t so hot.

What I like the best about my Android device is the “phone-top”.

I have spent a fair amount of time customizing my phone’s home pages.

Having a picture of my kids on the background certainly helps personalize the experience with the phone, however that is nothing new — there is so much more available with Android compared to the BlackBerry I toted for years.

The ability to have various application functionality at the ready across multiple “home screens” is quite powerful and is a major “stickiness” factor for using the device; particularly when my Nexus One locks up when answering a call and I am tempted to break it in half like one of those old soap commercials.

My setup

One page of my phone’s “desktop” has my direct dial and email shortcuts — this is the most heavily used aspect of my phone.

Another page is for the “M’s”: Messaging, Music, Maps and the Market. Oh, and the browser. No “M”, but it has a similar usage profile to the others — once or twice a day on average.

Every page has the phone shortcut in the same spot so I can easily place a call without having to navigate to a particular page.

Lastly I have the “power widget” on one page so I can easily toggle GPS on and off. With “marginal at best” battery life, turning a feature off that is not needed can go a long way. Having the power feature very accessible is actually a key driver in making GPS accessible to me.

With my BlackBerry, turning GPS on and off was buried in menus — it was just too much of a bother so I very rarely used it. And then only if I was super lost and my wife wasn’t there to ask for directions. Enabling this feature in Android with the power widget is remarkably easy and means I don’t have to stop for directions. There is a lesson in that somewhere!

If desktop widgets are so helpful as a user, I thought it might be fun to take a look at building an AppWidget myself — and that is what this article is about — a quick primer on Android AppWidget construction.

Simple App Widget

Over time we will flesh out a more useful AppWidget, but for now we’re going to take a look at the basic ingredients of an AppWidget.

An AppWidget is typically a complement to another application. The application may be a Service which periodically updates data such as in a News or Weather application. Or an AppWidget may be a convenient means of launching another application. For example, the Music AppWidget represents the “remote control” for the underlying media player application.

Most Android applications start with the construction of an “Activity”. Breaking with tradition, this application does not have an Activity (yet!) but starts with an instance of a BroadcastReceiver which is one of the four Android application types:

• Activity
• Service
• Content Provider
• Broadcast Receiver

A BroadcastReceiver “handles” certain events on the platform and must register for the specific events of interest in its AndroidManifest.xml file. In the case of the AppWidget, the specific message handled is the android.appwidget.action.APPWIDGET_UPDATE. The intent-filter tag specifies the actions of interest.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.msi.linuxmagazine"
      android:versionCode="1"
      android:versionName="1.0">
<application android:icon="@drawable/icon" android:label="LMAppWidget">
	<receiver android:name=".LMAppWidgetImpl">
		<intent-filter>
			<action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
		</intent-filter>
		<meta-data android:name="android.appwidget.provider"
			android:resource="@xml/lmappwidget" />
	</receiver>
	</application>
</manifest>

In addition to the normal receiver tag in the AndroidManifest.xml file, an AppWidget also requires a meta-data entry which points to an AppWidget-Provider xml file.

<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider
  xmlns:android="http://schemas.android.com/apk/res/android"
  android:minHeight="72dp"
  android:minWidth="294dp"
  android:initialLayout="@layout/main"
  android:updatePeriodMillis="3600000"
  >
</appwidget-provider>

This AppWidget Provider configuration file specifies the height and width of the user interface, the resource file which contains the layout and a couple of other elements. The additional item shown in this example is the refresh or update frequency. To conserve battery life, the minimum duty cycle on this update process is one hour.

There are techniques for updating an AppWidget on a more appropriate ad-hoc basis which will be covered in a future article.

The Code

An AppWidget application implements an extension of the BroadcastReceiver: the AppWidgetProvider, as shown in the file LMAppWidgetImpl.java.

package com.msi.linuxmagazine;

import android.content.Context;
import android.content.Intent;
import android.appwidget.AppWidgetProvider;
import android.appwidget.AppWidgetManager;
import android.widget.RemoteViews;
import android.util.Log;

public class LMAppWidgetImpl extends AppWidgetProvider {

	private final String tag = "LMAppWidget";
	@Override
	public void onUpdate(Context context,AppWidgetManager appWidgetManager,int[] appWidgetIds ) {

		super.onUpdate(context, appWidgetManager, appWidgetIds);
		int count = appWidgetIds.length;
		Log.i(tag,"onUpdate::" + count);
		// we may have multiple instances of this widget ... make sure we hit each one ...
		for (int i=0;i
Even though the AppWidget does not contain an Activity, it does require a user interface layout, as referred to by the meta-data entry in the AndroidManifest.xml file.  This application has a simple layout of only a TextView to hold a single line of text.
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="horizontal"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:background="#000000"
    android:padding="15px"
    >
<TextView
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:id="@+id/simpleText"
    android:text="simpleText goes here"
    android:layout_gravity="center"/>
</LinearLayout>

The code for this AppWidget simply prints the current date and time to the screen.

Simple Date/Time AppWidget
To review, the basic ingredients for an AppWidget include:


AndroidManifest.xml refers to a BroadcastReceiver, plus a reference to the AppWidget specific meta-data
The meta-data file which contains the AppWidget-Provider details
A layout file to represent the user interface of the AppWidget
A java file which extends an AppWidgetProvider

In an upcoming article we will look at extending this simple AppWidget.