Memungkinkan pengguna mengonfigurasi widget aplikasi

Rancang widget Anda sehingga pengguna dapat mengonfigurasi karakteristik tertentu. Misalnya, widget jam dapat memungkinkan pengguna mengonfigurasi zona waktu yang akan ditampilkan.

Jika Anda ingin mengizinkan pengguna mengonfigurasi setelan widget, buat konfigurasi widget Activity. Aktivitas ini diluncurkan secara otomatis oleh host widget aplikasi baik saat widget dibuat atau nanti, bergantung pada opsi konfigurasi yang Anda tentukan.

Mendeklarasikan aktivitas konfigurasi

Deklarasikan aktivitas konfigurasi sebagai aktivitas normal dalam file manifes Android. Host widget aplikasi meluncurkannya dengan tindakan ACTION_APPWIDGET_CONFIGURE, sehingga aktivitas perlu menerima intent ini. Contoh:

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

Deklarasikan aktivitas dalam file AppWidgetProviderInfo.xml dengan atribut android:configure. Lihat informasi selengkapnya tentang mendeklarasikan file ini. Berikut adalah contoh cara mendeklarasikan aktivitas konfigurasi:

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

Aktivitas dideklarasikan dengan namespace yang sepenuhnya memenuhi syarat, karena peluncur mereferensikannya dari luar cakupan paket Anda.

Hanya itu yang Anda perlukan untuk memulai aktivitas konfigurasi. Selanjutnya, Anda perlu menerapkan aktivitas sebenarnya.

Menerapkan aktivitas konfigurasi

Ada dua poin penting yang perlu diingat saat Anda menerapkan aktivitas:

• Host widget aplikasi memanggil aktivitas konfigurasi, dan aktivitas konfigurasi harus selalu menampilkan hasil. Hasil harus menyertakan ID Widget Aplikasi yang diteruskan oleh intent yang meluncurkan aktivitas yang disimpan dalam tambahan intent sebagai EXTRA_APPWIDGET_ID.
  • Sistem tidak mengirim siaran ACTION_APPWIDGET_UPDATE saat aktivitas konfigurasi diluncurkan, yang berarti sistem tidak memanggil update widget Anda pada awalnya saat widget dibuat. Aktivitas konfigurasi bertanggung jawab untuk meminta update dari GlanceAppWidget saat membuat widget untuk pertama kalinya. Namun, update dipicu secara otomatis untuk siklus berikutnya.

Lihat cuplikan kode di bagian berikut untuk contoh cara menampilkan hasil dari konfigurasi dan mengupdate widget Glance.

Memperbarui widget dari aktivitas konfigurasi

Saat widget menggunakan aktivitas konfigurasi, aktivitas tersebut bertanggung jawab untuk mengupdate widget saat konfigurasi selesai. Anda dapat melakukannya dengan memicu update manual langsung dari instance GlanceAppWidget.

Berikut adalah ringkasan prosedur untuk mengupdate widget dengan benar dan menutup aktivitas konfigurasi:

1. Dapatkan ID Widget Aplikasi dari intent yang meluncurkan aktivitas:

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

2. Tetapkan hasil aktivitas ke RESULT_CANCELED.

   Dengan begitu, jika pengguna keluar dari aktivitas sebelum berakhir, sistem akan memberi tahu host widget aplikasi bahwa konfigurasi dibatalkan dan host tidak menambahkan widget:

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

3. Konfigurasi widget sesuai dengan preferensi pengguna, misalnya menulis pilihan ke Datastore persisten atau database lokal.

4. Setelah konfigurasi selesai, ambil GlanceId yang sesuai dengan ID widget platform:

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

5. Perbarui konten widget dengan memanggil fungsi penangguhan update pada instance GlanceAppWidget Anda:

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

6. Buat intent hasil, setel dengan hasil aktivitas, dan selesaikan aktivitas:

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

Opsi konfigurasi widget

Secara default, host widget aplikasi hanya meluncurkan aktivitas konfigurasi satu kali, segera setelah pengguna menambahkan widget ke layar utama. Namun, Anda dapat menentukan opsi yang memungkinkan pengguna mengonfigurasi ulang widget yang ada atau melewati konfigurasi widget awal dengan memberikan konfigurasi widget default.

Mengaktifkan pengguna untuk mengonfigurasi ulang widget yang ditempatkan

Untuk mengizinkan pengguna mengonfigurasi ulang widget yang ada, tentukan tanda reconfigurable dalam atribut widgetFeatures dari appwidget-provider. Contoh:

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

Pengguna dapat mengonfigurasi ulang widget dengan menyentuh & menahan widget dan mengetuk tombol Konfigurasi ulang, yang diberi label 1 pada gambar 1.

Menggunakan konfigurasi default widget

Anda dapat memberikan pengalaman widget yang lebih lancar dengan mengizinkan pengguna melewati langkah konfigurasi awal. Untuk melakukannya, tentukan flag configuration_optional dan reconfigurable di kolom widgetFeatures. Tindakan ini akan mengabaikan peluncuran aktivitas konfigurasi setelah pengguna menambahkan widget. Seperti yang disebutkan sebelumnya, pengguna masih dapat mengonfigurasi ulang widget setelahnya. Misalnya, widget jam dapat mengabaikan konfigurasi awal dan menampilkan zona waktu perangkat secara default.

Berikut adalah contoh cara menandai aktivitas konfigurasi Anda sebagai dapat dikonfigurasi ulang dan opsional:

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