Widgets
A widget is a simple application extension that is often part of a larger application already installed on the device. Widgets come in all shapes and sizes, are customizable, and reside on any available Home screen for quick access. Widgets provide you with quick access to information without requiring you to open the app that manages this information. An example is the Calendar widget, which provides you a quick view of your upcoming calendar events without opening the Calendar application.
Home screen widgets
Home screen widgets are broadcast receivers which provide interactive components. They are primarily used on the Android home screen. They typically display some kind of data and allow the user to perform actions with them. For example, a widget can display a short summary of new emails and if the user selects an email, it could start the email application with the selected email. To avoid confusion with views, this text uses the term home screen widgets, if it speaks about widgets. A widget runs as part of the process of its host. This requires that the widget preserves the permissions of their application.
The widget uses RemoteView to create their user interface. A RemoteView can be executed by another process with the same permissions as the original application. This way the widget runs with the permissions of its defining application. The user interface for a Widget is defined by a broadcast receiver. This receiver inflates its layout into an object of type RemoteView This object is delivered to Android, which hands it over the home screen application.
Steps to create a Widget
To create a widget:
- Define a layout file
- Create an XML file which describes the properties of the widget, e.g. size or the fixed update frequency.
- Create a BroadcastReceiver which is used to build the user interface of the widget.
- Enter the Widget configuration in the XML file.
- Optional you can specify a configuration activity which is called once a new instance of the widget is added to the widget host.
Widget size
Before Android 3.1 a widget always took a fixed amount of cells on the home screen. A cell is usually used to display the icon of one application. As a calculation rule you should define the size of the widget with the formula: ((Number of columns/rows) * 74) – 2. These are device independent pixels and the -2 is used to avoid rounding errors.
As of Android 3.1, a widget can be flexible in size, e.g., the user can make it larger or smaller. To enable this for the widget, you can use the android:resizeMode=”horizontal|vertical” attribute in the XML configuration file for the widget.
Creating the Broadcast receiver for the widget
Create and configure a widget
<receiver
android:icon="@drawable/icon"
android:label="Example Widget"
android:name="MyWidgetProvider" >
<intent-filter >
<action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
</intent-filter>
<meta-data
android:name="android.appwidget.provider"
android:resource="@xml/widget_info" />
</receiver>
The receiver can get a label and icon assigned. These are used in the list of available widgets in the Android launcher.
Also specify the meta-data for the widget via the android:name=”android.appwidget.provider attribute. The configuration file referred by this metadata contains the configuration settings for the widget. It contains, for example, the update interface, the size and the initial layout of the widget.
<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
android:initialLayout="@layout/widget_layout"
android:minHeight="72dp"
android:minWidth="146dp"
android:updatePeriodMillis="1800000" >
</appwidget-provider>
Available views and layouts
A widget is restricted in the View classes it can use. As layouts, you can use the FrameLayout, LinearLayout and RelativeLayout classes. As views, you can use Analog Clock, Button, ChromoMeter, Image Button, ImageView, Progress Bar and TextView. As for Android, 3.0 more views are available: GridView, ListView, StackView, ViewFlipper, and AdapterViewFlipper. The only interaction that is possible with the views of a widget is via an OnClickListener event. This OnClickListener can be registered on a widget and is triggered by the user.
AppWidgetProvider
Your BroadcastReceiver implementation typically extends the AppWidgetProvider class. The AppWidgetProvider class implements the onReceive() method, extracts the required information and calls the following widget lifecycle methods. As you can add several instances of a widget to the home screen, you have lifecycle methods which are called only for the first instance added/removed to the home screen and others which are called for every instance of your widget.
Lifecycle methods
-
OnEnabled()-
Called the first time an instance of your widget is added to the home screen.
-
onDisabled()-
Called once the last instance of your widget is removed from the home screen.
-
onUpdate()-
Called for every update of the widget. Contains the ids of appWidgetIds for which an update is needed. Note that this may be all of the AppWidget instances for this provider, or just a subset of them, as stated in the method’s JavaDoc. For example, if more than one widget is added to the home screen, only the last one changes (until reinstall).
-
onDeleted()–
The widget instance is removed from the home screen
Receiver and asynchronous processing
A widget has the same runtime restrictions as a normal broadcast receiver, i.e., it has only 5 seconds to finish its processing. A receive (widget) should, therefore, perform time-consuming operations in a service and perform the update of the widgets from the service.
Widget updates
A widget gets its data on a periodic timetable. There are two methods to update a widget, one is based on an XML configuration file and the other is based on the Android AlarmManager service. In the widget configuration file, you can specify a fixed update interval. The system will wake up after this time interval and call your broadcast receiver to update the widget. The smallest update interval is 1800000 milliseconds (30 minutes).
The AlarmManager allows you to be more resource efficient and to have a higher frequency of updates. To use this approach, you define a service and schedule this service via the AlarmManager regularly. This service updates the widget. A higher update frequency will wake up the phone from the energy safe mode. As a result, your widget consumes more energy.