Autoriser les utilisateurs à configurer des widgets d'application

Concevez votre widget de sorte que les utilisateurs puissent configurer des caractéristiques spécifiques. Par exemple, un widget d'horloge peut permettre aux utilisateurs de configurer le fuseau horaire à afficher.

Si vous souhaitez autoriser les utilisateurs à configurer les paramètres de votre widget, créez une configuration de widget Activity. Cette activité est lancée automatiquement par l'hôte du widget d'application, soit lors de la création du widget, soit ultérieurement, en fonction des options de configuration que vous spécifiez.

Déclarer l'activité de configuration

Déclarez l'activité de configuration comme une activité normale dans le fichier manifeste Android. L'hôte du widget d'application le lance avec l'action ACTION_APPWIDGET_CONFIGURE. L'activité doit donc accepter cet intent. Exemple :

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

Déclarez l'activité dans le fichier AppWidgetProviderInfo.xml avec l'attribut android:configure. Pour en savoir plus sur la déclaration de ce fichier, cliquez ici. Voici un exemple de déclaration de l'activité de configuration :

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

L'activité est déclarée avec un espace de noms complet, car le lanceur y fait référence en dehors de la portée de votre package.

C'est tout ce dont vous avez besoin pour démarrer une activité de configuration. Ensuite, vous devez implémenter l'activité proprement dite.

Implémenter l'activité de configuration

Lorsque vous implémentez l'activité, deux points importants sont à retenir :

• L'hôte du widget d'application appelle l'activité de configuration, qui doit toujours renvoyer un résultat. Le résultat doit inclure l'ID du widget d'application transmis par l'intent qui a lancé l'activité enregistrée dans les extras de l'intent en tant que EXTRA_APPWIDGET_ID.
  • Le système n'envoie pas la diffusion ACTION_APPWIDGET_UPDATE lorsqu'une activité de configuration est lancée, ce qui signifie qu'il n'appelle pas vos mises à jour de widget initialement lorsque le widget est créé. Il incombe à l'activité de configuration de demander une mise à jour à partir du GlanceAppWidget lors de la création du widget pour la première fois. Toutefois, les mises à jour sont déclenchées automatiquement pour les cycles suivants.

Consultez les extraits de code de la section suivante pour obtenir un exemple de la façon de renvoyer un résultat à partir de la configuration et de mettre à jour le widget Glance.

Mettre à jour le widget à partir de l'activité de configuration

Lorsqu'un widget utilise une activité de configuration, il incombe à l'activité de mettre à jour le widget une fois la configuration terminée. Pour ce faire, déclenchez une mise à jour manuelle directement depuis l'instance GlanceAppWidget.

Voici un récapitulatif de la procédure à suivre pour mettre à jour correctement le widget et fermer l'activité de configuration :

1. Obtenez l'ID du widget d'application à partir de l'intent qui a lancé l'activité :

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. Définissez le résultat de l'activité sur RESULT_CANCELED.

   De cette façon, si l'utilisateur quitte l'activité avant d'atteindre la fin, le système avertit l'hôte du widget d'application que la configuration est annulée et l'hôte n'ajoute pas le widget :

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. Configurez le widget en fonction des préférences de l'utilisateur, par exemple en écrivant les sélections dans un DataStore persistant ou une base de données locale.

4. Une fois la configuration terminée, récupérez le GlanceId correspondant à l'ID du widget de plate-forme :

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. Mettez à jour le contenu du widget en appelant la fonction de suspension update sur votre instance GlanceAppWidget :

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. Créez l'intent de retour, définissez-le avec le résultat de l'activité et terminez l'activité :

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

Options de configuration des widgets

Par défaut, l'hôte du widget d'application ne lance l'activité de configuration qu'une seule fois, immédiatement après que l'utilisateur a ajouté le widget à son écran d'accueil. Toutefois, vous pouvez spécifier des options qui permettent à l'utilisateur de reconfigurer les widgets existants ou d'ignorer la configuration initiale des widgets en fournissant une configuration de widget par défaut.

Permettre aux utilisateurs de reconfigurer les widgets placés

Pour permettre aux utilisateurs de reconfigurer des widgets existants, spécifiez l'option reconfigurable dans l'attribut widgetFeatures de appwidget-provider. Exemple :

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

Les utilisateurs peuvent reconfigurer leur widget en appuyant de manière prolongée dessus, puis en appuyant sur le bouton Reconfigurer, qui porte le numéro 1 sur la figure 1.

Utiliser la configuration par défaut du widget

Vous pouvez offrir une expérience plus fluide avec les widgets en permettant aux utilisateurs d'ignorer l'étape de configuration initiale. Pour ce faire, spécifiez les indicateurs configuration_optional et reconfigurable dans le champ widgetFeatures. Cela évite de lancer l'activité de configuration après qu'un utilisateur a ajouté le widget. Comme mentionné précédemment, l'utilisateur peut toujours reconfigurer le widget par la suite. Par exemple, un widget d'horloge peut contourner la configuration initiale et afficher le fuseau horaire de l'appareil par défaut.

Voici un exemple de la façon de marquer votre activité de configuration comme reconfigurable et facultative :

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>