Handling User Interaction with Android App Widgets

Introduction

The App Widget interface for Android is very powerful. Through it, developers can create simple controls that can be hosted on the Home Screen or in any application that provides similar host functionality. In Creating a Home Screen App Widget on Android, you learned how to create and configure an App Widget. This simple App Widget displays a slideshow of images with a time interval configured by the user up-front. But what if the user wants to change this interval? What if they want to pause the slideshow or skip to the next image immediately? In this article, you will learn how to add user controls to the App Widget for handing these actions.

In order to handle user interaction with an App Widget, the following tasks must be performed:

1. Set a unique click handler for each App Widget control
2. Have the click handler send a command to a registered receiver
3. Process the command received and perform any action necessary
4. Update the App Widget to reflect the changes

For this example, we will modify the App Widget created in the previous article (Figure 1, top App Widget) to include a button bar with three controls (Figure 1, bottom App Widgets). Each of the buttons on the button bar will perform a specific action and clicking anywhere else in the App Widget will hide the button bar. The left-hand button (tool set) will launch the configuration Activity so users can change the time interval between image transitions in the slideshow. The middle button will pause or resume, the slideshow. The right-hand button allows the user to skip to the next image immediately.

Figure 1: Three different states of the App Widget

Working with RemoteViews

An App Widget uses a special display control called RemoteViews. Unlike a regular View, a RemoteViews control is designed to display a collection of View controls in another process. Consequently, you can’t simply add a button handler because that code would run in your application process, not in the process displaying the RemoteViews object (in this case, the Home Screen process).

In order to enable user interaction with a RemoteViews control, you must register for a PendingIntent to be triggered when a specific View within the RemoteViews object is clicked. This is done with a call to the setOnClickPendingIntent() method of the RemoteViews object. For instance, to add the PendingIntent for launching the Activity to configure the slideshow time interval, we would add the following code:

  PendingIntent pendingIntent = PendingIntent.getActivity
     (context, 0, configIntent,
     PendingIntent.FLAG_UPDATE_CURRENT);
  remoteView.
     setOnClickPendingIntent(R.id.config, pendingIntent);

Next, let’s look more closely at the inner Intent called configIntent, which is wrapped by the PendingIntent.