- 1. Prerequisites
- 2. Android Widgets
- 3. Creating the Broadcast receiver for the widget
- 4. Widget updates
- 5. Exercise: widget with fixed update interval
- 6. Collection View Widgets
- 7. Enabling a app widget for the lock Screen
- 8. Exercise: Update widget via a service
- 9. About this website
- 10. Links and Literature
- Appendix A: Copyright and License
Developing Android Widgets. This article describes how to create home screen widgets in Android.
1. Prerequisites
The following description assume that you already have experience in building standard Android application. Please see http://www.vogella.com/tutorials/Android/article.html – Android Tutorial. It also partly uses Android services. You find an introduction into Android Services in http://www.vogella.com/tutorials/AndroidServices/article.html – Android Service Tutorial.
2. Android Widgets
2.1. Overview about AppWidgets
Widgets are little applications which can be placed on a widget host, typically the home screen or the lock screen of your Android device.
A widget runs as part of the process of its host. This requires that the widget preserves the permissions of their application.
Widget use RemoteViews
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 RemoteViews
. This object is delivered to Android, which hands it over the home screen application.
2.2. Steps to create a Widget
To create a widget, you:
- Define a layout file
- Create an XML file (
AppWidgetProviderInfo
) 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 AndroidManifest.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.
2.3. 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 widget, you can use the android:resizeMode="horizontal|vertical"
attribute in the XML configuration file for the widget.
3. Creating the Broadcast receiver for the widget
3.1. Create and configure widget
To register a widget, you create a broadcast receiver with an intent filter for the android.appwidget.action.APPWIDGET_UPDATE
action.
<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.
You 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>
3.2. 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 AnalogClock
, Button
, Chromometer
, ImageButton
, ImageView
, ProgressBar
and TextView
.
As of Android 3.0 more views are available: GridView
, ListView
, StackView
, ViewFlipper
and AdapterViewFlipper
. These adapter views require that you define a collection view widget which is described later in this {textselfreference}.