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

Kullanıcıların belirli özellikleri yapılandırabileceği şekilde widget'ınızı tasarlayın. Örneğin, 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, belirttiğiniz yapılandırma seçeneklerine bağlı olarak, uygulama widget'ı ana makinesi tarafından widget oluşturulduğunda veya daha sonra otomatik olarak başlatılır.

Yapılandırma etkinliğini bildirme

Yapılandırma etkinliğini Android manifest dosyasında normal bir etkinlik olarak bildirin. Uygulama widget'ını barındıran uygulama, ACTION_APPWIDGET_CONFIGURE işlemiyle başlatır. Bu nedenle etkinliğin bu amaçlı işlemi kabul etmesi gerekir. Örneğin:

<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 bildirin. Bu dosyayı bildirme hakkında daha fazla bilgi edinin. Yapılandırma etkinliğinin nasıl beyan edileceğine dair bir örneği aşağıda bulabilirsiniz:

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

Başlatıcı, paketin kapsamı dışından başvurduğu için etkinlik tam nitelikli bir ad alanıyla tanımlanır.

Yapılandırma etkinliği başlatmak için ihtiyacınız olan tek şey budur. Ardından, gerçek etkinliği uygulamanız gerekir.

Yapılandırma etkinliğini uygulama

Etkinliği uygularken hatırlamanız gereken iki önemli nokta vardır:

• Uygulama widget'ı ana makinesi, yapılandırma etkinliğini çağırır ve yapılandırma etkinliği her zaman bir sonuç döndürmelidir. Sonuç, intent'te kaydedilen etkinliği başlatan intent tarafından EXTRA_APPWIDGET_ID olarak intent ekstralarına iletilen uygulama widget'ı kimliğini içermelidir.
  • Sistem, bir yapılandırma etkinliği başlatıldığında ACTION_APPWIDGET_UPDATE yayını göndermez. Bu nedenle, widget oluşturulduğunda widget güncellemelerinizi başlangıçta çağırmaz. Widget ilk kez oluşturulurken GlanceAppWidget'dan güncelleme istemek yapılandırma etkinliğinin sorumluluğundadır. Ancak sonraki döngülerde güncellemeler otomatik olarak tetiklenir.

Yapılandırmadan nasıl sonuç döndürüleceği ve Glance widget'ının nasıl güncelleneceğiyle ilgili bir örnek 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 GlanceAppWidget örneğinden manuel bir güncellemeyi tetikleyerek yapabilirsiniz.

Widget'ı düzgün şekilde güncelleme ve yapılandırma etkinliğini kapatma prosedürünün özeti aşağıda verilmiştir:

1. Etkinliği başlatan amaçtan uygulama widget'ı kimliğini alın:

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. Etkinlik sonucunu RESULT_CANCELED olarak ayarlayın.

   Bu şekilde, kullanıcı etkinliği tamamlamadan önce geri dönerse sistem, yapılandırmanın iptal edildiğini uygulama widget'ı barındırıcıya bildirir ve barındırıcı widget'ı eklemez:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. Kullanıcının tercihlerine göre widget'ı yapılandırın. Örneğin, seçimleri kalıcı DataStore'a veya yerel bir veritabanına yazın.

4. Yapılandırma tamamlandığında platform widget'ı kimliğine karşılık gelen GlanceId değerini alın:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. update suspend işlevini GlanceAppWidget örneğinizde çağırarak widget içeriğini güncelleyin:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. Dönüş amacını oluşturun, etkinlik sonucuyla ayarlayın ve etkinliği tamamlayın:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

Widget yapılandırma seçenekleri

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

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. Örneğin:

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

Kullanıcılar, widget'a dokunup basılı tutarak ve Şekil 1'de 1 numaralı Yeniden yapılandır düğmesine dokunarak widget'larını yeniden yapılandırabilir.

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

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 widgetFeatures alanında hem configuration_optional hem de reconfigurable işaretlerini belirtin. Bu sayede, kullanıcı widget'ı ekledikten sonra yapılandırma etkinliği başlatılmaz. Daha önce de belirtildiği gibi, kullanıcı daha sonra widget'ı yeniden yapılandırabilir. Örneğin, saat widget'ı ilk yapılandırmayı atlayabilir ve cihazın saat dilimini varsayılan olarak gösterebilir.

Yapılandırma etkinliğinizi hem yeniden yapılandırılabilir hem de isteğe bağlı olarak işaretlemeyle ilgili bir örneği aşağıda bulabilirsiniz:

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