AppWidgets are small views or widgets that can be embedded in another application. The containing application is called App Widget Host. One example of host application is the Home Screen application. When you long-press the home screen and selecting Widgets option will present you a list of widgets available. This is a two part series on how to create App Widgets. In this part I will stick on to the basics of creating the widget. In the second part I will explain how to provide more advanced topics.
We can create our own App Widgets by extending AppWidgetProvider class, which is actually a BroadcastReceiver with action android.appwidget.action.APPWIDGET_UPDATE. To create an App Widget we extends this class and override the onUpdate method. Then we have to specify the App Widget in AndroidManifest.xml file using the <receiver> tag. Finally we have to describe the App Widget in using AppWidgetProviderInfo object in an XML file.
To create and App Widget, we create a class extending AppWidgetProvider. The AppWidgetProvider class has following methods:
void onEnabled(Context context) void onDisabled(Context context) void onDeleted(Context context, int appWidgetIds) void onUpdate(Context context, AppWidgetManager appWidgetManager, int appWidgetIds) void onReceive(Context context, Intent intent)
The method onEnabled is called when an instance is create for the first time, i.e. when the user add the widget for the first time. It will not be called for subsequent additions. In this method we can perform any startup tasks.
The method onDisabled is called when the last instance of the widget is deleted. This method is to do some cleanup tasks.
The onDeleted is called when each instance of the widget is deleted.
The onUpdate method is first called when the widget is added to the host. After that this method will be called after the specified time intervals. This is the most important method of the App Widget. In this method we update the view with the data we want to display. If the data is readily available, we can display it in this method itself, if the data is not available and need to be fetched then it is better to create a Service application which actually fetch the data and update the widget. This is to avoid the ANR (Application Not Responding) error. We can update the widgets using AppWidgetManager’s updateAppWidget() method.
Declaring the App Widget
We have to declare the App Widget in the AndroidManifest.xml file using the <receiver> tag. As I told you before the AppWidgetProvider is actually is a BroadcastReceiver. Anything that can be done using this class can also be done using the BroadcastReceiver. Following snippet specifies the GPS App Widget:
<receiver android:name=".GPSWidgetProvider"> <intent-filter> <action android:name="android.appwidget.action.APPWIDGET_UPDATE" /> </intent-filter> <meta-data android:name="android.appwidget.provider" android:resource="@xml/gpswidgetinfo" /> </receiver>
Everything is same as specifying BroadcastReceiver except the meta-data section, here we describe our App Widget in a separate XML file.
Describing the App Widget
App Widget description is specified in a separate XML file. In this XML file we specify the minimum width and height of the widget, update period, widget layout, configuration screen layout, etc. Following snippet describes the GPS App Widget:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" android:minWidth="294dp" android:minHeight="72dp" android:updatePeriodMillis="900000" android:initialLayout="@layout/gpswidget"> <appwidget-provider>
The minWidth specifies the minimum width the widget, minHeight specifies the minimum height of the widget. The updatePeriodMillis specifies the update period in milliseconds. The initialLayout specifies the widget’s layout.
The sample application provided is a widget that displays the GPS coordinates the device. The GPS coordinates are reverse geo-coded to get the name of location and will be displayed if it is available. To reverse geo-code the location I used the class Geocoder. The widget will be updated in every 15 minutes.
Happy App Widget coding