Memungkinkan pengguna mengonfigurasi widget aplikasi

Widget aplikasi dapat dikonfigurasi. Misalnya, widget jam memungkinkan pengguna mengonfigurasi zona waktu yang akan ditampilkan.

Jika Anda ingin mengizinkan pengguna mengonfigurasi setelan widget, buat konfigurasi widget 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

Deklarasikan aktivitas konfigurasi sebagai aktivitas normal dalam file 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 cakupan paket Anda.

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

Mengimplementasikan 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. Hasilnya harus menyertakan ID Widget Aplikasi yang diteruskan oleh intent yang meluncurkan aktivitas—disimpan dalam tambahan intent sebagai EXTRA_APPWIDGET_ID.
  • Sistem tidak mengirimkan ACTION_APPWIDGET_UPDATE {i>broadcast<i} saat aktivitas konfigurasi diluncurkan, yang berarti ini tidak panggil metode onUpdate() saat widget dibuat. Aktivitas konfigurasi bertanggung jawab untuk meminta update dari AppWidgetManager 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 menampilkan hasil dari konfigurasi dan mengupdate 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:

  1. 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);
}

  2. 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);

  3. Konfigurasi widget sesuai dengan preferensi pengguna.

  4. Setelah konfigurasi selesai, dapatkan instance AppWidgetManager dengan memanggil getInstance(Context):

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. Update widget dengan tata letak RemoteViews dengan memanggil 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. 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 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 Anda mengaktifkan pengguna untuk mengonfigurasi ulang widget yang ada atau melewati konfigurasi widget awal dengan memberikan konfigurasi widget default.

Mengaktifkan pengguna untuk mengonfigurasi ulang widget yang ditempatkan

Agar pengguna dapat mengonfigurasi ulang widget yang ada, tentukan tanda reconfigurable dalam atribut widgetFeatures 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 dengan menyentuh lama widget dan mengetuk tombol Konfigurasi ulang, yang diberi label 1 pada gambar 1.

Tombol muncul di pojok kanan bawah
Gambar 1. Tombol Konfigurasi ulang widget.

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 memotong 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>