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, widget oluşturulduğunda veya daha sonra, belirttiğiniz yapılandırma seçeneklerine bağlı olarak 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 bir etkinlik olarak bildirin. Uygulama widget'ı ana makinesi, widget'ı ACTION_APPWIDGET_CONFIGURE işlemiyle başlattığı için etkinliğin bu amacı 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 bildirileceğ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ı, paket kapsamınızın 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 gereken 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ç, etkinliği başlatan amaç tarafından iletilen uygulama widget'ı kimliğini içermelidir. Bu kimlik, amaç ekstralarında EXTRA_APPWIDGET_ID olarak kaydedilir.
  • Sistem, yapılandırma etkinliği başlatıldığında ACTION_APPWIDGET_UPDATE yayını göndermez. Bu nedenle, widget oluşturulduğunda onUpdate() yöntemi çağrılmaz. Widget ilk kez oluşturulurken AppWidgetManager öğesinden güncelleme istemek, yapılandırma etkinliğinin sorumluluğundadır. Ancak, sonraki güncellemeler için onUpdate() çağrılır. Yalnızca ilk sefer 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'dan güncelleme isteğinde bulunarak yapabilirsiniz.

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

  1. Etkinliği başlatan amaçtan 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ği tamamlamadan 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:

    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 AppWidgetManager örneğini getInstance(Context)'ı çağırarak alın:

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. updateAppWidget(int,RemoteViews) işlevini çağırarak 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. İade 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ına bakın.

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ılara mevcut widget'ları yeniden yapılandırma veya varsayılan bir widget yapılandırması sağlayarak ilk widget yapılandırmasını atlama olanağı veren 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. Ö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 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.
1. şekil Widget Yeniden Yapılandır düğmesi.

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