Widget aplikasi dapat dikonfigurasi. Misalnya, widget jam memungkinkan pengguna mengonfigurasi zona waktu yang akan ditampilkan.
Jika Anda ingin mengizinkan pengguna mengonfigurasi setelan widget Anda, buat widget
konfigurasi Activity
. Aktivitas ini adalah
diluncurkan secara otomatis oleh host widget aplikasi, baik saat widget dibuat
atau lebih baru, tergantung opsi konfigurasi yang Anda
tentukan.
Mendeklarasikan aktivitas konfigurasi
Mendeklarasikan aktivitas konfigurasi sebagai aktivitas normal dalam manifes Android
. Host widget aplikasi meluncurkannya dengan
ACTION_APPWIDGET_CONFIGURE
, sehingga aktivitas harus 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 ruang lingkup paket Anda.
Hanya ini yang Anda perlukan untuk memulai aktivitas konfigurasi. Selanjutnya, Anda perlu menerapkan aktivitas yang sebenarnya.
Mengimplementasikan aktivitas konfigurasi
Ada dua hal penting yang harus diingat saat Anda menerapkan aktivitas ini:
- Host widget aplikasi memanggil aktivitas konfigurasi, dan konfigurasi
aktivitas harus selalu mengembalikan hasil. Hasilnya harus menyertakan Widget Aplikasi
ID yang diteruskan oleh intent yang meluncurkan aktivitas—disimpan dalam intent
tambahan sebagai
EXTRA_APPWIDGET_ID
- Sistem tidak mengirimkan
ACTION_APPWIDGET_UPDATE
{i>broadcast<i} saat aktivitas konfigurasi diluncurkan, yang berarti ini tidak panggil metodeonUpdate()
saat widget dibuat. Aktivitas konfigurasi bertanggung jawab untuk meminta pembaruan dariAppWidgetManager
saat membuat widget untuk pertama kalinya. Namun,onUpdate()
dipanggil untuk update berikutnya—hanya melewatkan pertama kalinya.
Lihat cuplikan kode di bagian berikut untuk contoh cara mengembalikan hasil dari konfigurasi dan memperbarui widget.
Mengupdate widget dari aktivitas konfigurasi
Ketika widget menggunakan aktivitas konfigurasi, itu tanggung jawab
aktivitas untuk mengupdate widget setelah konfigurasi selesai. Anda bisa melakukannya
dengan meminta pembaruan
langsung dari
AppWidgetManager
Berikut adalah ringkasan prosedur untuk mengupdate widget dengan benar dan menutup aktivitas konfigurasi:
Dapatkan ID Widget Aplikasi dari intent yang meluncurkan aktivitas:
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); }
Tetapkan hasil aktivitas ke
RESULT_CANCELED
.Dengan cara ini, jika pengguna keluar dari aktivitas sebelum mencapai akhir, memberi tahu {i>host<i} widget aplikasi bahwa konfigurasi telah dibatalkan dan host tidak menambahkan 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);
Konfigurasi widget sesuai dengan preferensi pengguna.
Setelah konfigurasi selesai, dapatkan instance
AppWidgetManager
dengan memanggilgetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
Update widget dengan tata letak
RemoteViews
dengan memanggilupdateAppWidget(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);
Buat intent yang ditampilkan, tetapkan dengan hasil aktivitas, dan menyelesaikan aktivitas:
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();
Lihat
ListWidgetConfigureActivity.kt
di GitHub sebagai contoh.
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 menyediakan konfigurasi widget default.
Mengaktifkan pengguna untuk mengonfigurasi ulang widget yang ditempatkan
Agar pengguna dapat mengonfigurasi ulang widget yang ada, tentukan
reconfigurable
tanda di
widgetFeatures
dari appwidget-provider
. Lihat panduan untuk mendeklarasikan
AppWidgetProviderInfo.xml
file untuk lainnya
tidak akurat atau tidak sesuai. Contoh:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
Pengguna dapat mengonfigurasi ulang widget mereka dengan menyentuh & tahan 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 kedua
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
memotong konfigurasi awal dan
menampilkan zona waktu perangkat secara default.
Berikut adalah contoh cara menandai aktivitas konfigurasi Anda sebagai keduanya dapat dikonfigurasi ulang dan opsional:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>