Kullanıcıların uygulama widget'larını yapılandırmasını sağlama

Uygulama widget'ları yapılandırılabilir. Örneğin, bir saat widget'ı kullanıcıların hangi saat diliminin gösterileceğini yapılandırmasına olanak tanıyabilir.

Kullanıcıların widget'ınızın ayarlarını yapılandırmasına izin vermek istiyorsanız bir widget yapılandırması Activity oluşturun. Bu etkinlik, uygulama widget'ı ana makinesi tarafından widget oluşturulduğunda veya daha sonra, belirttiğiniz yapılandırma seçeneklerine bağlı olarak otomatik olarak başlatılır.

Yapılandırma etkinliğini beyan etme

Yapılandırma etkinliğini Android manifest dosyasında normal bir etkinlik olarak tanımlayın. Uygulama widget'ı, ACTION_APPWIDGET_CONFIGURE işlemiyle başlatır. Bu nedenle, etkinliğin bu intent'i kabul etmesi gerekir. Örnek:

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

Etkinliği AppWidgetProviderInfo.xml dosyasında android:configure özelliğiyle tanımlayın. Daha fazla bilgi için: bu dosyayı beyan etmeniz gerekir. Elektronik tablo kullanarak yapılmış yapılandırma etkinliğini bildirme:

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

Başlatıcı, bu dosyaya paket kapsamınızın dışından referans verir.

Yapılandırma etkinliği başlatmak için tüm yapmanız gereken bu. Daha sonra ve gerçek etkinliği uygulamaya başlayabilirsiniz.

Yapılandırma etkinliğini uygulama

Etkinliği uygularken dikkate almanız gereken iki önemli nokta vardır:

  • Uygulama widget'ı ana makine, yapılandırma etkinliğini çağırır ve yapılandırma etkinliği her zaman bir sonuç döndürmelidir. Sonuç, etkinliği başlatan intent tarafından iletilen uygulama widget'ı kimliğini içermelidir. Bu kimlik, intent ekstralarına EXTRA_APPWIDGET_ID olarak kaydedilir.
  • Sistem, ACTION_APPWIDGET_UPDATE bir yapılandırma etkinliği başlatıldığında yalnızca Widget oluşturulduğunda onUpdate() yöntemini çağırın. AppWidgetManager simgesini tıklayın. Ancak onUpdate(), sonraki güncellemeler için çağrılır. Yalnızca ilk kez atlanır.

Bir widget'ı güncelleyin.

Widget'ı yapılandırma etkinliğinden güncelleme

Widget'lar bir yapılandırma etkinliği kullandığında widget'ı güncelleme etkinliği. Bunu doğrudan AppWidgetManager üzerinden güncelleme isteğinde bulunarak yapabilirsiniz.

Aşağıda, widget'ı doğru bir şekilde güncelleme ve yapılandırma etkinliği:

  1. Etkinliği başlatan intent'ten uygulama widget'ı kimliğini alın:

    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. Etkinlik sonucunu RESULT_CANCELED olarak ayarlayın.

    Bu şekilde, kullanıcı sona ulaşmadan etkinlikten ayrılırsa sistem, yapılandırmanın iptal edildiğini uygulama widget'ı ana makinesine bildirir ve düzenleyen kullanıcı widget'ı eklemez:

    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. Widget'ı kullanıcının tercihlerine göre yapılandırın.

  4. Yapılandırma tamamlandığında getInstance(Context) numaralı telefonu arayarak AppWidgetManager:

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. updateAppWidget(int,RemoteViews) çağrısını yaparak widget'ı RemoteViews düzeniyle güncelleyin:

    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. Dönüş niyetini oluşturun, etkinlik sonucuyla ayarlayın ve etkinliği tamamlayın:

    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();

Örnek için GitHub'daki ListWidgetConfigureActivity.kt örnek sınıfına bakın.

Widget yapılandırma seçenekleri

Varsayılan olarak uygulama widget'ı ana makinesi, yapılandırma etkinliğini yalnızca kullanıcı widget'ı ana ekranına ekledikten hemen sonra bir kez başlatır. Ancak kullanıcıların mevcut widget'ları yeniden yapılandırmasına olanak tanıyan veya varsayılan bir widget yapılandırması sağlayarak ilk widget yapılandırmasını atlamanıza olanak tanıyan seçenekler belirleyebilirsiniz.

Kullanıcıların yerleştirilmiş widget'ları yeniden yapılandırmasını etkinleştir

Kullanıcıların mevcut widget'ları yeniden yapılandırmasına izin vermek için appwidget-provider öğesinin widgetFeatures özelliğinde reconfigurable işaretini belirtin. Daha fazla bilgi için AppWidgetProviderInfo.xml dosyasını bildirme kılavuzunu inceleyin. Örnek:

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

Kullanıcılar & widget'ı basılı tutup Şu etikete sahip Yeniden yapılandır düğmesi 1'dir.

Düğme sağ alt köşede görünür
Şekil 1. Widget Yeniden yapılandır düğmesi.

Widget'ın varsayılan yapılandırmasını kullan

Kullanıcıların adımını attım. Bunu yapmak için hem configuration_optional ve reconfigurable işaretlerini widgetFeatures alanına ekleyin. Bu, Kullanıcı widget'ı ekledikten sonra yapılandırma etkinliğini başlatmak. Bahsedildiği gibi Kullanıcı önceden Widget'ı yeniden yapılandırabilir daha fazla bilgi edineceksiniz. Örneğin, bir saat widget'ı ilk yapılandırmayı atlayabilir ve varsayılan olarak cihazın saat dilimini gösterir.

Yapılandırma etkinliğinizi hem yapılandırılabilir ve isteğe bağlı:

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