Création de Widget sous Android

Les widgets sont de petites applications qui peuvent être placées sur un hôte de widgets, généralement l'écran d'accueil ou l'écran de verrouillage de votre appareil Android.

Un widget s'exécute dans le cadre du processus de son hôte. Cela exige qu'il conserve les autorisations de son application.

Les widgets utilisent RemoteViews pour créer leur interface utilisateur. Une RemoteView peut être exécutée par un autre processus, avec les mêmes autorisations que l'application d'origine. De cette façon, le widget s'exécute avec les autorisations de son application déterminante.

L'interface utilisateur d'un Widget est définie par un récepteur de diffusion. Ce récepteur déploie sa mise en page en un objet de type RemoteViews. Cet objet est livré à Android, qui le remet à l'application d'écran d'accueil.

Pour créer un widget, vous devez :

• définir un fichier de mise en page ;
• créer un fichier XML (AppWidgetProviderInfo) qui décrit les propriétés du widget, par exemple la taille ou la fréquence fixe de mise à jour ;
• créer un BroadcastReceiver, utilisé pour générer l'interface utilisateur du widget ;
• saisir la configuration du Widget dans le fichier AndroidManifest.xml ;
• optionnel : vous pouvez spécifier une activité de configuration, appelée lorsqu'une nouvelle instance du widget est ajoutée à l'hôte.

Avant Android 3.1, un widget occupait toujours un nombre fixe de cellules sur l'écran d'accueil. Une cellule est généralement utilisée pour afficher l'icône d'une application. Comme règle de calcul, vous devez définir la taille du widget avec la formule : ((Nombre de colonnes / lignes) * 74) - 2. Ce sont des pixels indépendants du périphérique et le -2 est utilisé pour éviter les erreurs d'arrondi.

À partir d'Android 3.1, un widget peut avoir une taille flexible et l'utilisateur peut l'agrandir ou le diminuer. Pour activer cette caractéristique, vous pouvez utiliser l'attribut android:resizeMode="horizontal|vertical" dans le fichier XML de configuration du widget.

Pour enregistrer un widget, vous créez un récepteur de diffusion avec un filtre d'intention pour l'action android.appwidget.action.APPWIDGET_UPDATE.

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

Le récepteur peut obtenir une étiquette et une icône. Celles-ci sont utilisées dans la liste de widgets disponibles du lanceur Android.

Vous spécifiez également les métadonnées du widget par l'attribut android:name="android.appwidget.provider". Le fichier de configuration référencé par ces métadonnées contient les paramètres de configuration du widget, par exemple l'interface de mise à jour, la taille et la mise en page initiale du 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>

L'utilisation des classes View par un widget est restreinte. Pour la mise en page, vous pouvez utiliser les classes FrameLayout, LinearLayout et RelativeLayout. Comme vues, vous disposez d'AnalogClock, Button, Chronometer, ImageButton, ImageView, ProgressBar et TextView.

À partir d'Android 3.0, plusieurs vues sont disponibles : GridView, ListView, StackView, ViewFlipper et AdapterViewFlipper. Ces adaptateurs de vues exigent que vous définissiez un collection view widget, décrit plus loin.

La seule interaction possible entre un widget et les vues s'effectue par un événement OnClickListener, qui peut être enregistré sur le widget et est déclenché par l'utilisateur.

Votre implémentation de BroadcastReceiver étend généralement la classe AppWidgetProvider.

La classe AppWidgetProvider implémente la méthode OnReceive(), extrait les informations nécessaires et appelle les méthodes de cycle de vie du widget ci-dessous.

Comme vous pouvez ajouter plusieurs instances d'un widget à l'écran d'accueil, vous avez des méthodes de cycle de vie appelées uniquement pour la première instance ajoutée à (ou supprimée de) l'écran d'accueil et d'autres qui sont appelées pour chaque instance de votre widget.

Table 1. Méthodes de cycle de vie

Un widget a les mêmes restrictions d'exécution qu'un récepteur normal de diffusion, c'est-à-dire qu'il n'a que cinq secondes pour terminer son traitement.

Un récepteur (widget) devrait donc dérouler des opérations chronophages dans un service et effectuer la mise à jour des widgets à partir du service.

Dans l'exercice suivant, vous créez un widget qui affiche un nombre aléatoire. Celui-ci est mis à jour toutes les 30 minutes. Vous enregistrez également un OnClickListener, pour que le widget soit mis à jour chaque fois que l'utilisateur clique dessus.

Le widget devrait ressembler à ceci :

Créez un nouveau projet Android appelé de.vogella.android.widget.example, avec une activité dans le paquetage de.vogella.android.widget.example.

Créez un nouveau fichier myshape.xml dans le répertoire /res/drawable. Ce fichier définit le drawable utilisé comme arrière-plan pour le widget.

<?xml version="1.0" encoding="UTF-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle" >

    <stroke
        android:width="2dp"
        android:color="#FFFFFFFF" />

    <gradient
        android:angle="225"
        android:endColor="#DD2ECCFA"
        android:startColor="#DD000000" />

    <corners
        android:bottomLeftRadius="7dp"
        android:bottomRightRadius="7dp"
        android:topLeftRadius="7dp"
        android:topRightRadius="7dp" />

</shape>

Définissez le fichier widget_layout.xml suivant sous le répertoire res/layout.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/layout"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:layout_margin="8dip"
    android:background="@drawable/myshape" >

    <TextView
        android:id="@+id/update"
        style="@android:style/TextAppearance.Medium"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:layout_gravity="center"
        android:gravity="center_horizontal|center_vertical"
        android:layout_margin="4dip"
        android:text="Static Text" >
    </TextView>

</LinearLayout>

Créez le fichier widget_info.xml de métadonnées AppWidgetProvider, via Fichier -> Nouveau -> Android -> fichier XML Android.

<?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="300dp"
    android:updatePeriodMillis="300000" >

</appwidget-provider>

Créez la classe réceptrice suivante, qui est appelée pendant les mises à jour.

package de.vogella.android.widget.example;

import java.util.Random;

import android.app.PendingIntent;
import android.appwidget.AppWidgetManager;
import android.appwidget.AppWidgetProvider;
import android.content.ComponentName;
import android.content.Context;
import android.content.Intent;
import android.util.Log;
import android.widget.RemoteViews;

public class MyWidgetProvider extends AppWidgetProvider {

  private static final String ACTION_CLICK = "ACTION_CLICK";

  @Override
  public void onUpdate(Context context, AppWidgetManager appWidgetManager,
      int[] appWidgetIds) {

    // Retrouver tous les id
    ComponentName thisWidget = new ComponentName(context,
        MyWidgetProvider.class);
    int[] allWidgetIds = appWidgetManager.getAppWidgetIds(thisWidget);
    for (int widgetId : allWidgetIds) {
      // créer des données aléatoires
      int number = (new Random().nextInt(100));

      RemoteViews remoteViews = new RemoteViews(context.getPackageName(),
          R.layout.widget_layout);
      Log.w("WidgetExample", String.valueOf(number));
      // Définir le texte
      remoteViews.setTextViewText(R.id.update, String.valueOf(number));

      // Enregistrer un onClickListener
      Intent intent = new Intent(context, MyWidgetProvider.class);

      intent.setAction(AppWidgetManager.ACTION_APPWIDGET_UPDATE);
      intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS, appWidgetIds);

      PendingIntent pendingIntent = PendingIntent.getBroadcast(context,
          0, intent, PendingIntent.FLAG_UPDATE_CURRENT);
      remoteViews.setOnClickPendingIntent(R.id.update, pendingIntent);
      appWidgetManager.updateAppWidget(widgetId, remoteViews);
    }
  }
}

Ouvrez AndroidManifest.xml et déclarez votre widget comme ci-dessous.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="de.vogella.android.widget.example"
    android:versionCode="1"
    android:versionName="1.0" >

    <application
        android:icon="@drawable/icon"
        android:label="@string/app_name" >
        <receiver 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>
    </application>

    <uses-sdk android:minSdkVersion="8" />

</manifest>

Cet attribut indique qu'AppWidgetProvider accepte la diffusion d'ACTION_APPWIDGET_UPDATE et spécifie les métadonnées pour le widget.

Déployez l'application sur votre appareil Android. Une fois qu'elle a été déployée, utilisez le lanceur Android pour installer votre nouveau widget sur l'écran d'accueil et le tester.

Codes source d'exemple

• Example Widget from Android API demos
• Wiktionary Example Widget