Autoriser les utilisateurs à configurer des widgets d'application

Les widgets d'application peuvent être configurables. Par exemple, un widget d'horloge permet aux utilisateurs 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é automatiquement par l'hôte du widget d'application, que ce soit lors de la création du widget ou ultérieure, en fonction des options de configuration que vous spécifier.

Déclarer l'activité de configuration

Déclarez l'activité de configuration en tant qu'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 la android:configure. Pour en savoir plus sur la déclaration de ce fichier, consultez la documentation. 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 qualifié complet, car le lanceur la référence en dehors de la portée de votre package.

Il vous suffit de cela pour démarrer une activité de configuration. Ensuite, vous devez implémenter l'activité réelle.

Implémenter l'activité de configuration

Il y a deux points importants à retenir lorsque vous mettez en œuvre l'activité:

• L'hôte du widget d'application appelle l'activité de configuration, et l'activité de configuration doit toujours renvoyer un résultat. Le résultat doit inclure le widget d'application. ID transmis par l'intent qui a lancé l'activité (enregistré dans l'intent) extras comme EXTRA_APPWIDGET_ID
• Le système n'envoie pas ACTION_APPWIDGET_UPDATE lorsqu'une activité de configuration est lancée, ce qui signifie qu'elle n'est pas appeler la méthode onUpdate() lors de la création du widget. L'activité de configuration est chargée de demander une mise à jour à AppWidgetManager lors de la création du widget pour la première fois. Toutefois, onUpdate() est appelé pour les mises à jour ultérieures. Il n'est ignoré que la première fois.

Consultez les extraits de code de la section suivante pour savoir comment renvoyer un résultat de la configuration et mettre à jour le widget.

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

Lorsqu'un widget utilise une activité de configuration, l'activité pour mettre à jour le widget une fois la configuration terminée. Vous pouvez le faire en demandant une mise à jour directement AppWidgetManager

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

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

   Kotlin

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

   Java

   Intent intent = getIntent();
   Bundle extras = intent.getExtras();
   int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
   if (extras != null) {
       appWidgetId = extras.getInt(
               AppWidgetManager.EXTRA_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 d'atteindre la fin, le système informe l'hôte du widget de l'application que la configuration est annulée et que l'hôte n'ajoute pas le widget :

   Kotlin

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

   Java

   int resultValue = new 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.

4. Une fois la configuration terminée, récupérez une instance de AppWidgetManager en appelant getInstance(Context):

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)
   

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
   

5. Mettez à jour le widget avec une la mise en page RemoteViews en appelant updateAppWidget(int,RemoteViews):

   Kotlin

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)
   

   Java

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);
   

6. Créez l'intent renvoyé, définissez-le avec le résultat de l'activité, puis terminer l'activité:

   Kotlin

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

   Java

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();
   

Pour obtenir un exemple, consultez l'exemple de classe ListWidgetConfigureActivity.kt sur GitHub.

Options de configuration du widget

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. Cependant, vous Vous pouvez spécifier des options permettant aux utilisateurs de reconfigurer des widgets existants ignorer la configuration initiale du widget en fournissant une configuration de widget par défaut.

Remarque :Ces options ne sont disponibles qu'à partir d'Android 12 (niveau d'API 31). Toi vous pouvez les spécifier pour les versions précédentes d'Android, mais le système les ignore et suit le comportement 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. Consultez le guide pour déclarer la AppWidgetProviderInfo.xml pour en savoir plus des informations. Exemple :

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

Les utilisateurs peuvent reconfigurer leur widget en appuyant sur & en maintenant le widget enfoncé et en appuyant le bouton Reconfigure (Reconfigurer) : 1 sur la figure 1.

Figure 1 Bouton Reconfigurer du widget.

Remarque :L'indicateur reconfigurable a été introduit dans Android 9 (niveau d'API 28), mais il n'a été largement pris en charge qu'à partir d'Android 12.

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 à la fois configuration_optional et reconfigurable dans le champ widgetFeatures. Cela permet de contourner lancer l'activité de configuration après qu'un utilisateur a ajouté le widget. Comme indiqué précédemment auparavant, 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 marquage de votre activité de configuration comme étant à la fois reconfigurable et facultative :

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