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 ayarlarınızı yapılandırmasına izin vermek istiyorsanız widget oluşturun Activity yapılandırması. 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 bildirme

Yapılandırma etkinliğini, Android manifest dosyasında normal etkinlik olarak bildir dosyası olarak kaydedebilirsiniz. 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>

AppWidgetProviderInfo.xml dosyasında etkinliği android:configure özelliği için de geçerlidir. Bu dosyayı beyan etme hakkında daha fazla bilgi edinin. Yapılandırma etkinliğinin nasıl tanımlanacağına dair bir örnek aşağıda verilmiştir:

<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. Ardından, gerçek etkinliği uygulamanız gerekir.

Yapılandırma etkinliğini uygulama

Etkinliği uygularken unutmamanı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, bir yapılandırma etkinliği başlatıldığında ACTION_APPWIDGET_UPDATE yayınını göndermez. Yani widget oluşturulduğunda onUpdate() yöntemini çağırmaz. Widget'ı ilk kez oluştururken AppWidgetManager kaynağından güncelleme istemek yapılandırma etkinliğinin sorumluluğundadır. Ancak onUpdate(), sonraki güncellemeler için çağrılır. Yalnızca ilk kez atlanır.

Yapılandırmadan sonuç döndürme ve widget'ı güncelleme örneği için aşağıdaki bölümdeki kod snippet'lerine bakın.

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

Bir widget yapılandırma etkinliği kullandığında, yapılandırma tamamlandığında widget'ı güncellemek etkinliğin sorumluluğundadır. Bunu doğrudan AppWidgetManager üzerinden güncelleme isteğinde bulunarak yapabilirsiniz.

Widget'ı doğru şekilde güncelleme ve yapılandırma etkinliğini kapatma işleminin özetini aşağıda bulabilirsiniz:

1. Etkinliği başlatan intent'den App Widget Kimliği'ni 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 sayede, kullanıcı etkinliğin sonuna ulaşmadan geri çekilirse sistem, uygulama widget'ı ana makinesine yapılandırmanın iptal edildiğini bildirir ve ana makine 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. Widget'ı Çağrı yaparak RemoteViews düzeni 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. İade 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();
   

Bkz. ListWidgetConfigureActivity.kt GitHub'daki sample class'ı inceleyelim.

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ırmalarını veya İlk widget yapılandırmasını atlamak için varsayılan bir widget yapılandırması sağlayın.

Not: Bu seçenekler yalnızca Android 12 (API düzeyi 31) ve sonraki sürümlerde kullanılabilir. Bunları Android'in önceki sürümleri için belirtebilirsiniz ancak sistem bunları yoksayıp varsayılan davranışı izler.

Kullanıcıların yerleştirilen widget'ları yeniden yapılandırmasına izin verme

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. Uygulamanızla ilgili bilgilerin Daha fazlası için AppWidgetProviderInfo.xml dosya ekleyebilirsiniz. Ö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.

Şekil 1. Widget Yeniden yapılandır düğmesi.

ziyaret edin.

Not: reconfigurable işareti Android 9'da (API düzeyi 28) kullanıma sunulmuştur ancak Android 12'ye kadar yaygın olarak desteklenmemektedir.

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

Kullanıcıların ilk yapılandırma adımını atlamasına izin vererek daha sorunsuz bir widget deneyimi sunabilirsiniz. Bunu yapmak için hem configuration_optional ve reconfigurable işaretlerini widgetFeatures alanına ekleyin. Bu işlem, kullanıcı widget'ı ekledikten sonra yapılandırma etkinliğinin başlatılmasını atlar. Daha önce de belirtildiği gibi, kullanıcı daha sonra widget'ı yeniden yapılandırabilir. Örneğin, bir saat widget'ı ilk yapılandırmayı atlayabilir ve varsayılan olarak cihazın saat dilimini gösterebilir.

Yapılandırmanız etkinliğinizi hem yeniden yapılandırılabilir hem de isteğe bağlı olarak işaretleme örneğini aşağıda bulabilirsiniz:

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