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 permettre aux utilisateurs de 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 lors de la création du widget ou 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 la lance avec l'ACTION_APPWIDGET_CONFIGURE action. 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. En savoir plus sur la déclaration de ce fichier 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.

Vous n'avez besoin de rien d'autre pour démarrer une activité de configuration. Ensuite, vous devez implémenter l'activité proprement dite.

Implémenter l'activité de configuration

Voici deux points importants à retenir lorsque vous implémentez l'activité :

• L'hôte du widget d'application appelle l'activité de configuration, et celle-ci 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 les mises à jour de votre widget initialement lors de sa création. Il incombe à l'activité de configuration de demander une mise à jour à partir de GlanceAppWidget lors de la première création du widget. 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 renvoi d'un résultat à partir de la configuration et de mise à jour du 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, vous pouvez déclencher une mise à jour manuelle directement à partir de l'instance GlanceAppWidget.

Voici un résumé 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.

   Ainsi, si l'utilisateur quitte l'activité avant la fin, le système informe l'hôte du widget d'application que la configuration est annulée et que 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 la 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 permettant à l'utilisateur de reconfigurer des widgets existants ou d'ignorer la configuration initiale du widget en fournissant une configuration par défaut.

Autoriser les utilisateurs à reconfigurer les widgets placés

Pour permettre aux utilisateurs de reconfigurer des widgets existants, spécifiez l'indicateur 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 , libellé 1 sur la figure 1.

Utiliser la configuration par défaut du widget

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

Voici un exemple de marquage de votre activité de configuration comme reconfigurable et facultative :

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