Gérer et mettre à jour GlanceAppWidget

Les sections suivantes expliquent comment mettre à jour GlanceAppWidget et gérer son état.

Gérer l'état GlanceAppWidget

La classe GlanceAppWidget fournie est instanciée chaque fois que le widget est créé ou nécessite une mise à jour. Elle doit donc être sans état et passive.

Le concept d'état peut être divisé comme suit :

• État de l'application : état ou contenu de l'application requis par le widget. Par exemple, une liste de destinations stockées (c'est-à-dire une base de données) définie par l'utilisateur.
• État Glance : état spécifique qui ne concerne que le widget d'application et qui ne modifie ni n'affecte nécessairement l'état de l'application. Par exemple, une case à cocher a été sélectionnée dans le widget ou un compteur a été incrémenté.

Utiliser l'état de l'application

Les widgets d'application doivent être passifs. Chaque application est responsable de la gestion de la couche de données et de la gestion des états, tels que l'état inactif, l'état de chargement et l'état d'erreur, qui se reflètent dans l'UI du widget.

Par exemple, le code suivant récupère les destinations du cache en mémoire à partir de la couche de dépôt, fournit la liste des destinations stockées et affiche une interface utilisateur différente en fonction de son état :

class DestinationAppWidget : GlanceAppWidget() {

    // ...

    @Composable
    fun MyContent() {
        val repository = remember { DestinationsRepository.getInstance() }
        // Retrieve the cache data everytime the content is refreshed
        val destinations by repository.destinations.collectAsState(State.Loading)

        when (destinations) {
            is State.Loading -> {
                // show loading content
            }

            is State.Error -> {
                // show widget error content
            }

            is State.Completed -> {
                // show the list of destinations
            }
        }
    }
}
GlanceSnippets.kt

Chaque fois que l'état ou les données changent, il incombe à l'application de notifier et de mettre à jour le widget. Pour en savoir plus, consultez Mettre à jour GlanceAppWidget.

Mettre à jour GlanceAppWidget

Vous pouvez demander la mise à jour du contenu de votre widget à l'aide de GlanceAppWidget. Comme expliqué dans la section Gérer l'état GlanceAppWidget, les widgets d'application sont hébergés dans un processus différent. Glance traduit le contenu en RemoteViews et l'envoie à l'hôte. Pour mettre à jour le contenu, Glance doit recréer les RemoteViews et les renvoyer.

Pour envoyer la mise à jour, appelez la méthode update de l'instance GlanceAppWidget, en fournissant context et glanceId :

MyAppWidget().update(context, glanceId)
GlanceSnippets.kt

Pour obtenir le glanceId, interrogez GlanceAppWidgetManager :

val manager = GlanceAppWidgetManager(context)
val widget = GlanceSizeModeWidget()
val glanceIds = manager.getGlanceIds(widget.javaClass)
glanceIds.forEach { glanceId ->
    widget.update(context, glanceId)
}
GlanceSnippets.kt

Vous pouvez également utiliser l'une des extensions GlanceAppWidget update :

// Updates all placed instances of MyAppWidget
MyAppWidget().updateAll(context)

// Iterate over all placed instances of MyAppWidget and update if the state of
// the instance matches the given predicate
MyAppWidget().updateIf<State>(context) { state ->
    state == State.Completed
}
GlanceSnippets.kt

Ces méthodes peuvent être appelées depuis n'importe quelle partie de votre application. Étant donné qu'il s'agit de fonctions suspend, nous vous recommandons de les lancer en dehors de la portée du thread principal. Dans l'exemple suivant, ils sont lancés dans un CoroutineWorker :

class DataSyncWorker(
    val context: Context,
    val params: WorkerParameters,
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        // Fetch data or do some work and then update all instance of your widget
        MyAppWidget().updateAll(context)
        return Result.success()
    }
}
GlanceSnippets.kt

Pour en savoir plus sur les coroutines, consultez Coroutines Kotlin sur Android.

Quand mettre à jour les widgets

Mettez à jour les widgets immédiatement ou à intervalles réguliers.

Votre widget peut se mettre à jour immédiatement lorsque votre application est active. Exemple :

• Lorsqu'un utilisateur interagit avec un widget, ce qui déclenche une action, un appel lambda ou un intent pour lancer une activité.
• Lorsque votre utilisateur interagit avec votre application au premier plan ou lorsque l'application est déjà en cours de mise à jour en réponse à un message Firebase Cloud Messaging (FCM) ou à une diffusion.

Dans ce cas, appelez la méthode update comme décrit dans ce guide.

Votre widget peut se mettre à jour périodiquement lorsque votre application n'est pas active. Exemple :

• Utilisez updatePeriodMillis pour mettre à jour le widget jusqu'à une fois toutes les 30 minutes.
• Utilisez WorkManager pour planifier des mises à jour plus fréquentes, par exemple toutes les 15 minutes.
• Mettez à jour le widget en réponse à une diffusion.

Ressources

• Créer un widget avec Glance (atelier de programmation)
• Préparer l'avenir d'Android : chapitre sur les widgets (vidéo)