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şlattığı için etkinliğin bu niyeti 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. 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ı, etkinliğe paket kapsamınızın dışından referans verdiği için etkinlik tam nitelikli bir ad alanıyla tanımlanır.

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 dikkat etmeniz 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'den 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.

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. Bunu doğrudan AppWidgetManager üzerinden güncelleme isteğinde bulunarak yapabilirsiniz.

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

  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 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) çağrısını yaparak AppWidgetManager örneği alın:

    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ş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. Daha fazla bilgi için AppWidgetProviderInfo.xml dosyasını bildirme kılavuzuna bakın. Örnek:

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

Kullanıcılar, widget'a dokunup basılı tutarak ve 1. resimde 1 olarak etiketlenen Yeniden yapılandır düğmesine dokunarak widget'larını yeniden yapılandırabilir.

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ı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 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 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>