Working with App Widgets in Android

In Android, app widgets (also known as Home screen widgets) are miniature applications that can be embedded within other applications, such as the Home screen. App widgets normally resemble small icons or very small views on your Home screen, and they allow users to interact with your application by simply tapping them.

These app widgets can accept user input through click events and can update themselves on a regular schedule. App widgets are applied to the Home screen by long-pressing (pressing on the screen for a couple of seconds) and then selecting widgets, as shown in Figure 8-1.

To make the Screen Brightness Toggle application more usable, I show you how to build an app widget for the application so that users can add it to their Home screen. After adding the widget, the user can tap it to activate the app's core functionality and toggle the screen brightness mode — without first having to open the application. The widget also updates its layout to inform the user what state the device is in, as shown in Figure 8-2.

Working with remote views

Because Android is based on the Linux 2.6 kernel, the Android platform inherits security idioms from Linux. For example, the Android security model is heavily based around the Linux user, file, and process security model.

Figure 8-1: The dialog box that shows up after you long-press the Home screen.

Figure 8-2: The two states of the app widget you're about to build.

However, this restriction makes it difficult for developers to access or modify the Home screen from within an application. In Android, because the Home screen is actually an application, Android's security restrictions won't allow you as a developer to modify actual running code on the Home screen. Without this rule, malicious developers could do some really evil things, such as shut down your Home screen. How would you use your device then? This is a big issue.

To deal with this problem, the Android engineers implemented the remote view architecture. This architecture allows you to run code inside your application, completely away from the Home screen application, while still allowing you to update a view inside the Home screen. The end result is that no arbitrary code can be run inside the Home screen application — all your app widget code runs within your application.

This app widget stuff may sound confusing, but imagine it like this: The user taps the app widget (in this case, an icon on the Home screen that he added). This action fires off a request to change the brightness mode. Android routes that request to your application. During the processing of that request, your application instructs the Android platform to change the brightness mode as well as to update the app widget on the Home screen with a new image to indicate that the brightness mode has been changed. None of this code was run in the Home screen application — all of it was run remotely in your application with Android messaging performing the message routing to the appropriate application.

Remote views (known as the RemoteView class in the Android platform) are a little bit of magic mixed with innovative engineering. They allow your application to programmatically supply a remote UI to the Home screen in another process. Structuring things this way means that the app widget code is not an actual activity, as it was in Chapter 7, but is an implementation of an AppWidgetProvider. When Android routes a message to your application from the app widget on the Home screen, your implementation of the AppWidgetProvider class is where you handle the message.

Using AppWidgetProviders

The AppWidgetProvider class provides the hooks that allow you to programmatically interface with the app widget on the Home screen. When the user interacts with the app widget, messages are sent to and from the app widget to your application through broadcast events. Through these broadcast events, you can respond to when the app widget is updated, enabled, disabled, and deleted. You can also update the look and feel of the app widget on the Home screen by using a RemoteView to update the layout on the Home screen. All the logic that determines what should happen is initiated through an implementation of an AppWidgetProvider.

The AppWidgetProvider does all the work of responding to events from the RemoteView, but how so? AppWidgetProvider is a direct subclass of BroadcastReceiver, which, at a high level, is a component that can receive broadcast messages from the Android system. When a user taps a clickable view in the RemoteView on the Home screen (such as a button), the Android system broadcasts a message informing the receiver that the view was clicked. The message is broadcast to a particular destination in the Android system. After the message is broadcast, the AppWidgetProvider can handle that message.

Note that these messages are broadcast, meaning that they are sent system-wide. If the message's destination address information is vague enough, a number of BroadcastReceiver objects might handle the message, which is not the effect you're looking for. However, the AppWidgetProvider you build in this chapter will be addressed to a single destination.

The app widget framework that is built into Android can be thought of as a translator for a conversation between two entities. Imagine that you need to speak to someone who knows Italian, but you don't know Italian. How would you do this? You'd find a translator. The translator would accept your input, translate it to Italian, and relay the message to the native Italian speaker. The same goes for the app widget framework. This framework is your translator.

Here's a great analogy: When the Italian native (the Home screen, in this case) needs to let you know that something has happened (such as a button click), the translator (the app widget framework and the Android system) translates that message into one that you (your app) can understand. At that time, you (your app) can respond with a message instructing the Italian native (the Home screen) to do something (such as changing the app widget background color to lime green), and the translator (the app widget framework) relays the message to the native Italian speaker (through the Android system to the Home screen). When all the translation is done, the Home screen updates the view to have a background color of green.

Because a user's actions are translated through the Android messaging architecture (which requires the apps to communicate across process boundaries), your app will not be immediately notified when the user taps the app widget. However, this does not mean your app won't be notified at all — it just means it's done a little differently.

App widget click events contain instructions on what to do when a click event happens through the use of the PendingIntent class in the Android framework. I explain this in the next section.