Widget aplikasi dapat dikonfigurasi. Misalnya, widget jam dapat memungkinkan pengguna mengonfigurasi zona waktu mana yang akan ditampilkan.
Jika ingin mengizinkan pengguna mengonfigurasi setelan widget Anda, buat konfigurasi widget Activity
. Aktivitas ini
otomatis diluncurkan oleh host widget aplikasi baik saat widget dibuat
maupun setelahnya, 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 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 mereferensikan dari luar cakupan paket Anda.
Hanya ini yang Anda perlukan untuk memulai aktivitas konfigurasi. Selanjutnya, Anda perlu mengimplementasikan aktivitas yang sebenarnya.
Mengimplementasikan aktivitas konfigurasi
Ada dua hal penting yang perlu diingat saat Anda mengimplementasikan aktivitas:
- Host widget aplikasi memanggil aktivitas konfigurasi, dan aktivitas
konfigurasi harus selalu menampilkan hasil. Hasilnya 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 metodeonUpdate()
saat widget dibuat. Aktivitas konfigurasi bertanggung jawab meminta update dariAppWidgetManager
saat membuat widget untuk pertama kalinya. Namun,onUpdate()
dipanggil untuk update berikutnya dan hanya dilewati untuk pertama kalinya.
Lihat cuplikan kode di bagian berikut untuk mengetahui contoh cara menampilkan hasil dari konfigurasi dan mengupdate widget.
Mengupdate widget dari aktivitas konfigurasi
Saat menggunakan aktivitas konfigurasi, aktivitas tersebut bertanggung jawab
untuk mengupdate widget tersebut saat konfigurasi selesai. Anda dapat melakukannya
dengan meminta update 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, sistem akan memberi tahu host widget aplikasi bahwa konfigurasi 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);
Konfigurasikan 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 selesaikan 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 class contoh
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 untuk mengonfigurasi ulang widget yang ada atau melewati konfigurasi widget awal dengan menyediakan konfigurasi widget default.
Mengaktifkan pengguna untuk mengonfigurasi ulang widget yang ditempatkan
Untuk mengizinkan pengguna mengonfigurasi ulang widget yang ada, tentukan
flag reconfigurable
dalam
atribut widgetFeatures
dari appwidget-provider
. Lihat panduan untuk mendeklarasikan
file AppWidgetProviderInfo.xml
untuk informasi
selengkapnya. Contoh:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
Pengguna dapat mengonfigurasi ulang widget mereka dengan menyentuh lama widget dan mengetuk tombol Reconfigure, yang berlabel 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>
Mengizinkan pengguna menyematkan widget
Pada perangkat yang menjalankan Android 8.0 (API level 26) dan yang lebih baru, peluncur yang memungkinkan pengguna membuat pintasan yang disematkan juga memungkinkan mereka menyematkan widget ke layar utama. Serupa dengan pintasan yang disematkan, widget yang disematkan ini memberi pengguna akses ke tugas tertentu di aplikasi Anda dan dapat ditambahkan ke layar utama langsung dari aplikasi, seperti yang ditunjukkan dalam video berikut.
Di aplikasi, Anda dapat membuat permintaan agar sistem menyematkan widget ke peluncur yang didukung dengan menyelesaikan langkah-langkah berikut:
Pastikan Anda mendeklarasikan widget dalam file manifes aplikasi.
Panggil metode
requestPinAppWidget()
, seperti yang ditunjukkan dalam cuplikan kode berikut:
Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context) val myProvider = ComponentName(context, ExampleAppWidgetProvider::class.java) if (appWidgetManager.isRequestPinAppWidgetSupported()) { // Create the PendingIntent object only if your app needs to be notified // when the user chooses to pin the widget. Note that if the pinning // operation fails, your app isn't notified. This callback receives the ID // of the newly pinned widget (EXTRA_APPWIDGET_ID). val successCallback = PendingIntent.getBroadcast( /* context = */ context, /* requestCode = */ 0, /* intent = */ Intent(...), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT) appWidgetManager.requestPinAppWidget(myProvider, null, successCallback) }
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context); ComponentName myProvider = new ComponentName(context, ExampleAppWidgetProvider.class); if (appWidgetManager.isRequestPinAppWidgetSupported()) { // Create the PendingIntent object only if your app needs to be notified // when the user chooses to pin the widget. Note that if the pinning // operation fails, your app isn't notified. This callback receives the ID // of the newly pinned widget (EXTRA_APPWIDGET_ID). PendingIntent successCallback = PendingIntent.getBroadcast( /* context = */ context, /* requestCode = */ 0, /* intent = */ new Intent(...), /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT); appWidgetManager.requestPinAppWidget(myProvider, null, successCallback); }