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'ı ana makinesi, 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 bildirilir.

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

Yapılandırma etkinliğini uygulama

Etkinliği uygularken unutulmaması 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ç, etkinliği başlatan amaç tarafından iletilen ve amaç ekstralarında EXTRA_APPWIDGET_ID olarak kaydedilen 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 öğesinden 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 özetini aşağıda bulabilirsiniz:

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 sayede, kullanıcı etkinliği tamamlamadan çıkarsa sistem, uygulama widget'ı barındırıcıya yapılandırmanın iptal edildiğini bildirir ve barındırıcı widget'ı eklemez:

   val resultValue = 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. Ö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 öğesini 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 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 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>