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:
- Create a RemoteView, which provides the user interface for the App Widget.
- Tie the RemoteView to an Activity that implements the AppWidgetProvider interface.
- 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:
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"?>
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.