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

Uygulama widget'ları yapılandırılabilir. Ö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 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 tanımlayın. Uygulama widget'ı ana makinesi, widget'ı ACTION_APPWIDGET_CONFIGURE işlemiyle başlatır. Bu nedenle, 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>

AppWidgetProviderInfo.xml dosyasındaki etkinliği android:configure özelliğiyle tanımlayın. Bu dosyayı bildirme hakkında daha fazla bilgi edinin. Yapılandırma etkinliğinin nasıl bildirileceğine dair bir örnek:

<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 etkinliğe referans verdiği için etkinlik, tam nitelikli ad alanıyla tanımlanır.

Yapılandırma etkinliği başlatmak için tüm yapmanız gereken bu. Daha sonra, gerçekleşen etkinliği uygulamanız gerekir.

Yapılandırma etkinliğini uygulama

Etkinliği uygularken unutmamanı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 intent tarafından iletilen ve intent ekstralarına EXTRA_APPWIDGET_ID olarak kaydedilen App Widget kimliğini içermelidir.
  • Bir yapılandırma etkinliği başlatıldığında sistem ACTION_APPWIDGET_UPDATE yayını göndermez. Diğer bir deyişle, widget oluşturulduğunda onUpdate() yöntemini çağırmazsınız. Widget'ı ilk kez oluştururken AppWidgetManager uygulamasından güncelleme istemek yapılandırma etkinliğinin sorumluluğundadır. Bununla birlikte, onUpdate() sonraki güncellemeler için çağrılır; yalnızca ilk seferde atlanır.

Yapılandırmadan bir sonuç döndürme ve widget'ı güncelleme hakkında örnek için aşağıdaki bölümde yer alan kod snippet'lerini inceleyin.

Widget'ı yapılandırma etkinliğinden güncelleme

Bir widget, yapılandırma etkinliği kullandığında, yapılandırma tamamlandığında widget'ın güncellenmesi bu etkinliğin sorumluluğundadır. Doğrudan AppWidgetManager üzerinden güncelleme isteğinde bulunarak bu işlemi yapabilirsiniz.

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

  1. Etkinliği başlatan intent'den App 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 ayrılırsa sistem, yapılandırmanın iptal edildiğini ve ana makinenin widget'ı eklemediğini uygulama widget'ı ana makinesine 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) çağrısı yaparak AppWidgetManager öğesinin bir örneğini alın:

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. updateAppWidget(int,RemoteViews) numaralı telefonu arayarak 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ı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 bir kez başlatır. Bununla birlikte, varsayılan widget yapılandırması sağlayarak kullanıcıların mevcut widget'ları yeniden yapılandırmasına veya ilk widget yapılandırmasını atlamasına olanak tanıyan seçenekler belirleyebilirsiniz.

Kullanıcıların yerleştirilmiş widget'ları yeniden yapılandırmasını etkinleştir

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ı tanımlama 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ı tuttuktan sonra Şekil 1'de 1 olarak etiketlenmiş 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

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şaretini belirtin. Bu, bir 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ırma etkinliğinizi hem yeniden yapılandırılabilir hem de isteğe bağlı olarak nasıl işaretleyeceğinize dair bir örneği aşağıda bulabilirsiniz:

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