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

Uygulama widget'ları yapılandırılabilir olabilir. Örneğin, bir saat widget'ı, kullanıcıların görüntülenecek saat dilimini yapılandırmasına olanak tanır.

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, belirlediğiniz yapılandırma seçeneklerine bağlı olarak widget oluşturulduğunda veya daha sonra uygulama widget'ı ana makinesi tarafından otomatik olarak başlatılır.

Yapılandırma etkinliğini bildirme

Yapılandırma etkinliğini, Android manifest dosyasında normal etkinlik olarak bildirin. Uygulama widget'ı barındırıcısı, widget'ı ACTION_APPWIDGET_CONFIGURE işlemiyle başlatır, dolayısıyla etkinliğin bu amacı kabul etmesi gerekir. Örnek:

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

AppWidgetProviderInfo.xml dosyasındaki etkinliği android:configure özelliğiyle bildirin. Bu dosyayı bildirme hakkında daha fazla bilgi edinin. Aşağıda, yapılandırma etkinliğinin nasıl tanımlanacağına dair bir örnek verilmiştir:

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

Başlatıcı, paketinizin kapsamının dışından bu etkinliğe referans verdiğinden, etkinlik tam nitelikli bir ad alanı ile tanımlanır.

Bir yapılandırma etkinliği başlatmak için tek ihtiyacınız olan bu. Ardından, asıl etkinliği uygulamanız gerekir.

Yapılandırma etkinliğini uygulama

Etkinliği uygularken göz önünde bulundurmanız gereken iki önemli nokta vardır:

• Uygulama widget'ı ana makinesi, yapılandırma etkinliğini çağırır ve yapılandırma etkinliğinin her zaman bir sonuç döndürmesi gerekir. Sonuç, etkinliği başlatan amaç tarafından iletilen Uygulama Widget'ı Kimliğini içermelidir. Amaç ekstralarına EXTRA_APPWIDGET_ID olarak kaydedilmiştir.
• 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 ürününden güncelleme isteğinde bulunmak yapılandırma etkinliğinin sorumluluğundadır. Ancak onUpdate() sonraki güncellemeler için çağrılır; yalnızca ilk seferde atlanır.

Yapılandırmadan bir sonucun nasıl döndürüleceğine ve widget'ın nasıl güncelleneceğine dair bir örnek için aşağıdaki bölümde yer alan kod snippet'lerine bakın.

Yapılandırma etkinliğinden widget'ı güncelleme

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

Widget'ı düzgün bir şekilde güncelleme ve yapılandırma etkinliğini kapatma prosedürünün özetini burada bulabilirsiniz:

1. Etkinliği başlatan niyetten Uygulama 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 şekilde, kullanıcı sona ulaşmadan etkinlikten çekilirse sistem, uygulama widget'ı ana makinesine yapılandırmanın iptal edildiğini ve ana makinenin widget'ı eklemediğini bildirir:

   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) yöntemini çağırarak AppWidgetManager öğesinin bir örneğini alın:

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)
   

   Java

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
   

5. updateAppWidget(int,RemoteViews) yöntemini çağırarak widget'ı bir 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üş amacını 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ını inceleyin.

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 başlatır. Ancak, kullanıcıları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 belirleyebilirsiniz.

Not: Bu seçenekler yalnızca Android 12'den (API düzeyi 31) itibaren kullanılabilir. Bunları Android'in önceki sürümleri için belirtebilirsiniz, ancak sistem bunları yoksayar ve varsayılan davranışı uygular.

Kullanıcıların, yerleştirilmiş widget'ları yeniden yapılandırmasını sağlama

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 edinmek 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'a dokunup basılı tutarak ve Şekil 1'de 1 olarak etiketlenmiş olan Yeniden yapılandır düğmesine dokunarak widget'larını yeniden yapılandırabilir.

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

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

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

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 ayar, kullanıcı widget'ı ekledikten sonra yapılandırma etkinliğinin başlatılmasını atlar. Önceden 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ırma etkinliğinizi hem yeniden yapılandırılabilir hem de isteğe bağlı olarak nasıl işaretleyebileceğinizle ilgili bir örneği aşağıda bulabilirsiniz:

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

Kullanıcıların widget'ı sabitlemesine izin verme

Android 8.0 (API düzeyi 26) ve sonraki sürümleri çalıştıran cihazlarda, kullanıcıların sabitlenmiş kısayollar oluşturmasına olanak tanıyan başlatıcılar, widget'ları ana ekranlarına sabitlemelerine de olanak tanır. Aşağıdaki videoda gösterildiği gibi, sabitlenen kısayollara benzer şekilde, bu sabitlenmiş widget'lar kullanıcıların uygulamanızdaki belirli görevlere erişmesini sağlar ve doğrudan uygulamadan ana ekrana eklenebilir.

Şekil 2. Widget sabitleme örneği.

Uygulamanızda, aşağıdaki adımları tamamlayarak sistemin bir widget'ı desteklenen bir başlatıcıya sabitlemesi için istek oluşturabilirsiniz:

1. Uygulamanızın manifest dosyasında bir widget bildirdiğinizden emin olun.

2. Aşağıdaki kod snippet'inde gösterildiği gibi requestPinAppWidget() yöntemini çağırın:

Kotlin

val appWidgetManager = AppWidgetManager.getInstance(context)
val myProvider = ComponentName(context, ExampleAppWidgetProvider::class.java)

if (appWidgetManager.isRequestPinAppWidgetSupported()) {
    // Create the PendingIntent object only if your app needs to be notified
    // when the user chooses to pin the widget. Note that if the pinning
    // operation fails, your app isn't notified. This callback receives the ID
    // of the newly pinned widget (EXTRA_APPWIDGET_ID).
    val successCallback = PendingIntent.getBroadcast(
            /* context = */ context,
            /* requestCode = */ 0,
            /* intent = */ Intent(...),
            /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT)

    appWidgetManager.requestPinAppWidget(myProvider, null, successCallback)
}

Java

AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
ComponentName myProvider = new ComponentName(context, ExampleAppWidgetProvider.class);

if (appWidgetManager.isRequestPinAppWidgetSupported()) {
    // Create the PendingIntent object only if your app needs to be notified
    // when the user chooses to pin the widget. Note that if the pinning
    // operation fails, your app isn't notified. This callback receives the ID
    // of the newly pinned widget (EXTRA_APPWIDGET_ID).
    PendingIntent successCallback = PendingIntent.getBroadcast(
            /* context = */ context,
            /* requestCode = */ 0,
            /* intent = */ new Intent(...),
            /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT);

    appWidgetManager.requestPinAppWidget(myProvider, null, successCallback);
}

Not: Sistemin desteklenen bir başlatıcıya widget'ı başarılı bir şekilde sabitleyip sabitlemeyeceği konusunda uygulamanızın bilgilendirilmesi gerekmiyorsa null öğesini requestPinAppWidget() öğesine üçüncü bağımsız değişken olarak ekleyebilirsiniz.