Android Widgets – Tutorial

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.

by

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}.

You may also like