Creating a Home Screen App Widget on Android

Android users got their first taste of the App Widget when some basic controls like the Clock

and Picture Frame Home Screen controls shipped with the first Android handsets. However,

the App Widget API was not publicly available for developers to use until recently. This

interface gives developers two new and interesting ways to provide Android application

functionality outside the traditional boundaries of a phone application. Developers can use

the App Widget API (released in Android 1.5) to create simple controls and craft new App

Widget hosts to display and use these controls.

This article shows you how to create a Home Screen App Widget that updates at a user-

configured time interval by using the AlarmManager interface. Specifically, you will see how

to create an App Widget that displays an image chosen randomly from a set of images. The

displayed image changes periodically according to a timing interval configured by the user.

Creating a simple App Widget involves several steps:

1. Create a RemoteView, which provides the user interface for the App Widget. 2. Tie the RemoteView to an Activity that implements the AppWidgetProvider interface. 3. Provide key App Widget configuration information in the Android manifest file.

Preparing Your Project for an App Widget

An App Widget is basically just a BroadcastReceiver that handles specific actions. The

AppWidgetProvider interface simplifies handling these actions by providing a framework for

developers to implement the following methods:

onEnabled(): Called when the first App Widget is created. Global initialization should take place here, if applicable.

onDisabled(): The inverse of the onEnabled() method, called when the last App Widget handled by this definition is deleted. Global cleanup should take place here, if applicable.

onUpdate(): Called when the App Widget needs to update its View, which could be when the user first creates the widget.

onDeleted(): Called when a particular instance of this App Widget is deleted. Cleanup for the specific instance in question should take place here.

onReceive(): The default implementation of this method handles the BroadcastReceiver actions and makes the appropriate calls to the methods shown above. (Warning: A well-documented defect exists that requires the developer to handle certain cases explicitly. See the following note for more information.)

Author's Note: Check this link for more

information about the current defects of the

AppWidget framework. The discussion

includes code to work around the issue (also

found in the downloadable sample code for

this article) and instances in which App Widget

identifiers can be passed to the onUpdate()

method even when they don't actually exist.

For the Android system to know about the App Widget, place a standard <receiver> tag in

the Android manifest file. The following snippet shows an example:

<receiver android:name="ImagesWidgetProvider">

<intent-filter>

<action

android:name="android.appwidget.action.APPWIDGET_UPDATE" />

</intent-filter>

<meta-data

android:name="android.appwidget.provider"

android:resource="@xml/imageswidget_info" />

</receiver>

You'll notice that, unlike a typical <receiver> definition, a <meta-data> section references

an XML file resource. This file defines addition data for App Widget, corresponding to the

AppWidgetProviderInfo class. The information defined here is immutable, so, this example

does not include the value for updatePeriodMillis, because this app lets users modify the

timing between updates—which can't be done if you assign updatePeriodMillis here. The

following code shows the complete imageswidget_info.xml file:

<?xml version="1.0" encoding="utf-8"?>

<appwidget-provider

xmlns:android="http://schemas.android.com/apk/res/android"

android:minWidth="146dp"

android:minHeight="146dp"

android:initialLayout="@layout/widget"

android:configure=

"com.mamlambo.imageswidget.ImagesWidgetConfiguration" />

The <appwidget-provider> tag defines the size of the App Widget, the default layout to

use, and the configuration Activity to launch whenever an instance of the App Widget is

created. To display nicely on the Home screen, widgets must adhere to certain size

guidelines. The Home screen is divided into cells of a particular size. The basic formula

(helpfully provided by Google) is to multiply the number of cells you want to occupy by 74,

and then subtract 2. In this case, the App Widget should be square: two cells high and two

cells wide. Therefore, use a size of ((74*2)-2), or 146.

Implementing onUpdate()

An App Widget that doesn't display anything isn't very useful. Luckily, the implementation

for the RemoteView object of this App Widget is straightforward; it uses a set of images

stored in the drawable resource directory of the application. The application references these

image resources as R.drawable.[imagename]. The code creates an array holding the names,

which makes it easy to randomly draw one of the images. The following snippet shows the

onUpdate() implementation, which randomly draws one of the included images:

@Override

public void onUpdate(Context context,

AppWidgetManager appWidgetManager,

int[] appWidgetIds) {

for (int appWidgetId : appWidgetIds) {

int imageNum = (new

java.util.Random().nextInt(IMAGES.length));

RemoteViews remoteView = new

RemoteViews(context.getPackageName(),

R.layout.widget);

remoteView.setImageViewResource(

R.id.image, IMAGES[imageNum]);

appWidgetManager.updateAppWidget(

appWidgetId, remoteView);

}

}

Note that the onUpdate() method expects a list of App Widget instances as the last

parameter. Each instance must be handled separately. Due to existing defects with the App

Widget framework, some instances provided may not be visible or enabled; however you can

safely ignore the problem for this example. Bear in mind that your particular implementation

may want to track which App Widgets are actually active.

You can review the simple R.layout.widget XML layout definition within the included

code download; it is basically just an ImageView. RemoteViews can use only a limited set of

View objects, including Button, ImageButton, ImageView, TextView, AnalogClock,

Chronometer, and ProgressBar—and only within FrameLayout, LinearLayout, or

RelativeLayout. Keep the RemoteView simple, because access is controlled through such

methods as setImageViewResource() and setTextViewText(). Their purpose is to draw a

View within another process, thus your application has less control over them than a normal

layout.

At this point, the basics of the App Widget are complete. However, to allow users to

configure the time between image updates, you must implement the configuration Activity

and then handle scheduling of the RemoteView updates.

Implementing the App Widget Configuration Activity

The configuration Activity, defined in the manifest file as ImagesWidgetConfiguration, is

like any Activity, with two exceptions:

1. When launched, it's intended to return a result, so the implementation must always call the setResult() method with an appropriate result (either RESULT_CANCELED or RESULT_OK).

2. When setting the result, the App Widget identifier value must be placed in the extra referenced by AppWidgeManager.EXTRA_APPWIDGET_ID.

The following snippet of code demonstrates dealing with both exceptions, calling

setResult() and setting the default result as RESULT_CANCELED in case the user backs out of

the Activity:

Bundle extras = launchIntent.getExtras();

if (extras != null) {

appWidgetId = extras.getInt(

AppWidgetManager.EXTRA_APPWIDGET_ID,

AppWidgetManager.INVALID_APPWIDGET_ID);

Intent cancelResultValue = new Intent();

cancelResultValue.putExtra(

AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);

setResult(RESULT_CANCELED, cancelResultValue);

}

Aside from those two restrictions, you may implement the configuration Activity however

you like. Figure 1 shows the simple configuration Activity for this example. If you return

RESULT_CANCELED, the App Widget won't be displayed to the user. If you return RESULT_OK,

it will be. You can use any storage mechanism you prefer for saving configuration data for

this particular instance of the App Widget. The example uses the SharedPreferences interface,

storing the time between updates with the particular App Widget identifier. You can see the

full implementation in the downloadable code for this article.

Figure 1. Configuration Screen: This simple configuration screen lets users set the time interval

between image display changes for this App Widget.

Implementing the Update Scheduling

As mentioned earlier, the configuration values within the AppWidgetProviderInfo class are

immutable. Because the updateTimeMillis value is within this class, any App Widget

instance created with an AppWidgetProviderInfo that has this value set will update at that

frequency, with no way to change it. Because this application should let users configure the

frequency at which the images are displayed within each App Widget instance, you must

implement the functionality yourself.

The AlarmManager class is the most logical update mechanism to use, because it lets

supports recurring notifications. These notifications are simple PendingIntent objects that will

be triggered.

You might think that you can just create an Intent object with the action value of

AppWidgetManager.ACTION_APPWIDGET_UPDATE and set the extras value to the particular

App Widget identifier. Then you would simply schedule it to update repeatedly by calling the

AlarmManager's setRepeating() method. Unfortunately, this does not work. The Android

system reuses Intents that match both action and scheme values—the "extras" values are not

compared. In practice, this means the Intent for each App Widget identifier would actually be

the same Intent. Fortunately, the solution is straightforward: define a scheme for your App

Widget and use it to define unique Intent instances. The following code snippet demonstrates

how to do this:

Intent widgetUpdate = new Intent();

widgetUpdate.setAction(

AppWidgetManager.ACTION_APPWIDGET_UPDATE);

widgetUpdate.putExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS,

new int[] { appWidgetId });

// make this pending intent unique

widgetUpdate.setData(

Uri.withAppendedPath(Uri.parse(

ImagesWidgetProvider.URI_SCHEME + "://widget/id/"),

String.valueOf(appWidgetId)));

PendingIntent newPending = PendingIntent.getBroadcast(

getApplicationContext(), 0, widgetUpdate,

PendingIntent.FLAG_UPDATE_CURRENT);

// now schedule it

AlarmManager alarms = (AlarmManager) getApplicationContext().

getSystemService(Context.ALARM_SERVICE);

alarms.setRepeating(AlarmManager.ELAPSED_REALTIME,

SystemClock.elapsedRealtime(), updateRateSeconds * 1000,

newPending);

You'll find the preceding code in the ImagesWidgetConfiguration Activity. The manifest file

shows the <receiver> block for handling this particular scheme. You will also need to halt

the repeating alarm within onDeleted() method in the AppWidgetProvider interface.

Finally, when the handset restarts, update scheduling must be restarted as well.

Figure 2. Multiple Widget Instances: This figure shows two different instances of the final App

Widget running at the same time.

A straightforward solution to this involves leveraging some logic directly within the

AppWidgetProvider's onReceive() method. First, check for the update action. If it's an

update, ensure that it doesn't contain a scheme value. If it does not, then the PendingIntent,

scheduled with the AlarmManager, did not trigger this action. In that case, check to see if

there is a configured preference value for each of the App Widget identifiers. If not, then you

know this update action was received before the App Widget has been configured. However,

if the preference value is available, then you know you can schedule the PendingIntent.

Again, you can see this full logic implemented within the onReceive() method.

This scheme allows multiple App Widgets of a given type to be displayed simultaneously, as

shown in Figure 2. The updates can occur at different frequencies, and each displayed image

is selected randomly from the included set.

You've seen how to create a basic App Widget on the Android platform. Each instance of this

App Widget (shown on the Home screen) runs on a separate schedule, configured by the user,

even though that capability is not available directly through the App Widget framework. A

future article will show you how to expand the functionality of this App Widget to use

images downloaded from the Internet, and explain how to enhance it with an on-screen

interface to control the display of images directly.