Les bases de l'AppWidget

Il y a une différence entre les widgets au niveau utilisateurs des widgets au niveau des développeurs...

- Les widgets que l'on posent sur le bureau pour un utilisateur se nomme appWidget pour un développeur

- Les boutons, calendrier... pour un utilisateur sont plus généralement nommés des widgets pour un développeur.

Les premiers fichiers XML

Tous comme les applications standard, les app widgets seront paramétrées à partir de fichiers XML.

Le tout premier sera évidemment AndroidManifest.xml !

Deux choses seront à définir:

Tout d'abord un receiver (et oui, comme expliqué précédemment, il s'agit d'un broadcast receiver) qui sera placé entre les balises <application> </application>

<receiver android:name="fr.free.supertos.MonWidget"> <intent-filter> <action android:name="android.appwidget.action.APPWIDGET_UPDATE" /> </intent-filter> <meta-data android:name="android.appwidget.provider" android:resource="@xml/mon_widget_meta" /> </receiver>

Les choses importantes à déclarer sont:

- Les filtres d'intentions d'un appWidget. Ici, il s'agit uniquement de l'action APPWIDGET_UPDATE qui sera déclenchée par le système pour maj le widget à l'écran.

- Une ressource XML nommée ici mon_widget_meta qui sera à créer dans res/xml de votre projet (si le répertoire xml n'existe pas, et bien créez le !).

Puis une activité permettant de configurer éventuellement l'appWidget:

<activity android:name="fr.free.supertos.WidgetConfigureWidgetConfigureActivity" android:theme="@android:style/Theme.Dialog"> <intent-filter> <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" /> </intent-filter> </activity>

Dans la ressource XML mon_widget_meta, nous pourrons trouver:

<?xml version="1.0" encoding="utf-8"?> <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" android:minWidth="110dp" android:minHeight="40dp" android:label="@string/widget_label" android:previewImage="@drawable/preview" android:initialLayout="@layout/mon_widget_layout" android:updatePeriodMillis="0" android:configure="fr.free.supertos.WidgetConfigureActivity" > </appwidget-provider>

Les objets widgets doivent définir:

• android:minWidth et android:minHeight: Une largeur et une hauteur minimales. Cependant, les appwidgets placées sur l'écran d'accueil occuperont généralement plus de place que nécessaire. En effet, ces écrans sont découpés en bloc de cellules (une grille s'affiche d'ailleurs lorsque vous allez positionner une appwidget à l'écran). Ces cellules auront une taille qui dépendra de l'écran du périphérique. Les AppWidgets se positionneront donc dans un certain nombre de cellules suivant la taille que vous aurez indiqués. Une cellule même partiellement occupée est réservée entièrement pour l'appwidget (la taille d'une cellule étant en quelque sorte égale à l'unité qui est donc indivisible) et l'appwidget sera agrandie pour occuper la totalité de l'espace de ce(s) cellule(s).

  Une formule permet de déterminer la taille approximative qu'il faut indiquer dans android:minWidth et android:minHeight: taille requise= 70dp * (nb. cellules) – 30dp, d'où le 110dp et 40dp de mon exemple. L'app widget devrait donc prendre une dimension de 2 cellules en horizontal et 1 en vertical.

Le nombre total de cellules sur l'écran d'accueil dépendra de la taille de l'écran de l'appareil (par exemple 4x4 sur galaxy note 2).

Durant le développement, si vous venez à modifier la taille mini et maxi de votre widget, pensez à supprimer le widget de votre écran d'accueil pour le reposer de nouveau, ainsi, le système prendra en compte les nouvelles dimensions.

• android:initialLayout: Le layout XML à utiliser initialement. Il s'agit d'indiquer le nom complet du layout à utiliser.
• android:configure: permet d'indiquer l'activité à lancer lorsque l'utilisateur désire pauser le widget sur l'écran d'accueil. Permet de configurer l'app widget.
• android:previewImage: permet d'afficher une image à afficher lors de l'installation de l'appWidget sur l'écran.
• Enfin, android:updatePeriodmillis: une période en milliseconde indiquant quand devra se produire le prochain raffraichissement du contenu du widget (par un appel à onUpdate() dans l'app Widget). Le délai indiqué risque de ne pas être rigoureusement respecté (suivant les ressources). Si la machine est en sommeil, il en sortira pour effectuer la maj. Cette valeur pourra être positionnée à 0 s'il n'y a pas de raffraichissement à faire, ou si vous voulez gérer vous même ce raffraichissement. Google préconise un minimum d'un quart d'heure mais préfère évidemment un délai bien plus grand pour optimiser la durée de vire de la batterie.

Définir le layout

Encore un fichier XML, désolé. Il fonctionne exactement sur le même principe que les layouts des activités d'une application et sera donc stocké sous res/layout.

Cependant, tous les widgets ne pourront pas être utilisés dans un app widget.

Voici une liste (qui devrait évoluer dans le temps) de ce que peut avoir un app widget:

1. Les layouts
2. FrameLayout
3. LinearLayout
4. RelativeLayout
5. GridLayout

Les widgets

1. AdapterViewFlipper
2. AnalogClock
3. Button
4. Chronometer
5. GridView
6. ImageButton
7. ImageView
8. ListView
9. ProgressBar
10. StackView
11. TextView
12. ViewFlipper

Les descendants de ces classes ne seront cependant pas supportés.

En fait, seuls ces objets peuvent être maj depuis un autre processus.

Exemple de layout:

<?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/anniversaire_widget" android:layout_width="match_parent" android:layout_height="match_parent" android:orientation="vertical" android:layout_margin="4dp" android:padding="16dp"> <TextView android:id="@+id/texte_info" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Mon premier layout !" /> <TextView android:id="@+id/texte_info_suite" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Il est beau non ?" /> </LinearLayout>

Cette solution très simpliste ne prend pas en compte les marges que Google veut imposer entre les AppWidget. Ce cas étant expliqué dans un autre chapitre. De plus, aucun fond n'est déclaré pour notre AppWidget. La lecture des informations risque donc d'être délicate (dépendra de l'image de l'écran d'accueil).

Du code JAVA (enfin !)

Un receiver a été indiqué dans le AndroidManifest.xml, il faut donc le coder !

Il devra se nommer fr.free.supertos.MonWidget (puisque c'est ce nom que nous lui avons donné !):

package fr.free.supertos; import fr.free.supertos.appwidget.R; import android.appwidget.AppWidgetManager; import android.appwidget.AppWidgetProvider; import android.content.Context; import android.util.Log; import android.widget.RemoteViews; public class MonWidget extends AppWidgetProvider { @Override public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { final int n = appWidgetIds.length; Log.d ("Widget","onUpdate pour " + n + " App Widget !"); // On boucle ici sur toutes les instances de notre app widget for (int i = 0; i < n; i++) { int appWidgetId = appWidgetIds[i]; updateAppWidget(context, appWidgetManager, appWidgetId); } } /** * Maj du widget * * @param context * @param appWidgetManager * @param appWidgetId */ static void updateAppWidget(Context context, AppWidgetManager appWidgetManager, int appWidgetId) { // Preparation du widget views Log.d ("Widget","updateAppWidget..."); RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.mon_widget_layout); // Nous pourrons modifier le contenu de nos widgets comme dans une application traditionnelle // views.setTextViewText(R.id.texte_info, "Hello world !!!"); appWidgetManager.updateAppWidget(appWidgetId, views); } }

Bon, il n'y a pas grand choix dans la codification, tout vous sera imposé:

Une méthode onUpdate qui est envoyée à la class MonWidget lors de l'envoi d'un intent avec l’action APPWIDGET_UPDATE et qui permettra de mettre à jour toutes les instances de votre app widget posées sur l'écran d'accueil (d'où la boucle for). Puis une méthode updateAppWidget qui doit travailler sur une view d'une instance qui n'est pas dans le processus de l'application. D'où l'utilisation de la classe RemoteViews pour pouvoir tout de même intervenir dessus.

Vous noterez que j'ai mis en commentaire du code, celui-ci permet d'intervenir directement sur un widget TextView pour modifier le texte. Juste pour montrer que cela est possible...

Puis une activité de configuration. Elle sera lancée lorsque l'utilisateur choisira votre app widget pour le poser sur l'écran:

package fr.free.supertos; import android.app.Activity; import android.appwidget.AppWidgetManager; import android.content.Context; import android.content.Intent; import android.os.Bundle; import android.util.Log; public class WidgetConfigureActivity extends Activity { private final static String CLASSE = MainActivity.class.getName(); private int mAppWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID; /** Called when the activity is created */ @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // En cas de fermeture de la fenêtre, ne pas créé l'app widget setResult(RESULT_CANCELED); // Retrouver l'ID du widget depuis son intent Intent intent = getIntent(); Bundle extras = intent.getExtras(); if (extras != null) { mAppWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID); } // Vérification qu'il y a bien un ID de positionné pour cet app widget, sinon problème ! if (mAppWidgetId == AppWidgetManager.INVALID_APPWIDGET_ID) { Log.e(CLASSE, "WidgetConfigureActivity: Aucun ID positionné pour l'app widget"); finish(); } configureWidget(getApplicationContext()); // Et nous retournons l'appWidgetId avant de mettre fin à l'activité Intent resultValue = new Intent(); resultValue.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, mAppWidgetId); setResult(RESULT_OK, resultValue); finish(); } /** * Configuration de app widget créé, ce qui va lancer le premier onUpdate du widget * @param context */ public void configureWidget(Context context) { AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context); MonWidget.updateAppWidget(context, appWidgetManager, mAppWidgetId); } }

Là aussi, un squelette de code va s'imposer:

Lors de la création de notre widget, l'activité de configuration est lancée et informe le gestionnaire de app widget qu'elle est ok pour travailler et indique son ID récupéré depuis sa propre intention.

Il n'y a plus qu'à lancer le tout !

Suite...

Vous avez vu les bases. Reste à approndir tout cela maintenant !