Koleksiyon widget'larını kullanma

Koleksiyon widget'ları, galeri uygulamasındaki resim koleksiyonları, haber uygulamasındaki makaleler veya iletişim uygulamasındaki mesajlar gibi aynı türden birçok öğeyi görüntüleme konusunda uzmandır. Koleksiyon widget'ları genellikle iki kullanım alanına odaklanır: koleksiyona göz atma ve koleksiyondaki bir öğeyi ayrıntı görünümünde açma. Koleksiyon widget'ları dikey olarak kaydırılabilir.

Bu widget'lar, içerik sağlayıcı gibi uzak verilerle desteklenen koleksiyonları görüntülemek için RemoteViewsService öğesini kullanır. Widget, verileri koleksiyon görünümleri olarak bilinen aşağıdaki görünüm türlerinden birini kullanarak sunar:

ListView

Öğeleri dikey olarak kaydırılan bir listede gösteren görünüm.

GridView

Öğeleri iki boyutlu kaydırılabilir bir ızgarada gösteren görünüm.

StackView

Kullanıcının sırasıyla önceki veya sonraki kartı görmek için ön kartı yukarı veya aşağı kaydırabileceği, kartların yığın halinde gösterildiği bir görünüm (kartvizit rulosu gibi).

AdapterViewFlipper

İki veya daha fazla görünüm arasında animasyonlu geçiş yapan, adaptör destekli basit bir ViewAnimator. Aynı anda yalnızca bir çocuk gösterilir.

Bu koleksiyon görünümleri, uzak verilerle desteklenen koleksiyonları görüntülediğinden kullanıcı arayüzlerini verilerine bağlamak için bir Adapter kullanırlar. Adapter, bir veri grubundaki bağımsız öğeleri bağımsız View nesnelerine bağlar.

Bu koleksiyon görünümleri bağdaştırıcılar tarafından desteklendiğinden, Android çerçevesi, widget'larda kullanılmalarını desteklemek için ek mimari içermelidir. Widget bağlamında Adapter, Adapter arayüzünün etrafını saran ince bir sarmalayıcı olan RemoteViewsFactory ile değiştirilir. Koleksiyondaki belirli bir öğe istendiğinde RemoteViewsFactory, koleksiyon için öğeyi oluşturur ve RemoteViews nesnesi olarak döndürür. Widget'ınıza koleksiyon görünümü eklemek için RemoteViewsService ve RemoteViewsFactory öğelerini uygulayın.

RemoteViewsService, uzak bir bağdaştırıcının RemoteViews nesneleri istemesine olanak tanıyan bir hizmettir. RemoteViewsFactory, bir koleksiyon görünümü (ör. ListView, GridView ve StackView) ile bu görünümün temel verileri arasındaki adaptör arayüzüdür. StackWidget örnek için bu hizmeti ve arayüzü uygulamak üzere şablon kod örneği aşağıda verilmiştir:

Kotlin

class StackWidgetService : RemoteViewsService() {

    override fun onGetViewFactory(intent: Intent): RemoteViewsFactory {
        return StackRemoteViewsFactory(this.applicationContext, intent)
    }
}

class StackRemoteViewsFactory(
        private val context: Context,
        intent: Intent
) : RemoteViewsService.RemoteViewsFactory {

// See the RemoteViewsFactory API reference for the full list of methods to
// implement.

}

Java

public class StackWidgetService extends RemoteViewsService {
    @Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {

// See the RemoteViewsFactory API reference for the full list of methods to
// implement.

}

Örnek uygulama

Bu bölümdeki kod alıntıları da StackWidgetörneğinden alınmıştır:

Şekil 1. A StackWidget.

Bu örnek, sıfır ile dokuz arasındaki değerleri gösteren on görüntüden oluşan bir yığından oluşur. Örnek widget'ın temel davranışları şunlardır:

• Kullanıcı, bir sonraki veya önceki görünümü görüntülemek için widget'taki üst görünümü dikey olarak kaydırabilir. Bu, yerleşik bir StackView davranışıdır.

• Widget, kullanıcı etkileşimi olmadan bir slayt gösterisi gibi görüntülemelerini sırayla otomatik olarak ilerletir. Bunun nedeni, res/xml/stackwidgetinfo.xml dosyasında android:autoAdvanceViewId="@id/stack_view" ayarıdır. Bu ayar, görünüm kimliği için geçerlidir. Bu durumda, yığın görünümünün görünüm kimliğidir.

• Kullanıcı üst görünüme dokunursa widget'ta "Dokunulan görünüm n" Toast mesajı gösterilir. Burada n, dokunulan görünümün dizinidir (konumudur). Davranışları uygulama hakkında daha fazla bilgi için Tek tek öğelere davranış ekleme bölümüne bakın.

Koleksiyonlarla widget'ları uygulama

Koleksiyon içeren bir widget uygulamak için herhangi bir widget'ı uygulama işlemini ve ardından birkaç ek adımı uygulayın: manifest dosyasını değiştirin, widget düzenine koleksiyon görünümü ekleyin ve AppWidgetProvider alt sınıfınızı değiştirin.

Koleksiyon içeren widget'lar için manifest

Manifest dosyasında widget beyan etme bölümünde listelenen koşulların yanı sıra, koleksiyon içeren widget'ların RemoteViewsService'nize bağlanmasını mümkün kılmanız gerekir. Bunu, manifest dosyanızda hizmeti BIND_REMOTEVIEWS izniyle beyan ederek yapabilirsiniz. Bu, diğer uygulamaların widget'ınızın verilerine serbestçe erişmesini engeller.

Örneğin, bir koleksiyon görünümünü doldurmak için RemoteViewsService kullanan bir widget oluştururken manifest girişi aşağıdaki gibi görünebilir:

<service android:name="MyWidgetService"
    android:permission="android.permission.BIND_REMOTEVIEWS" />

Bu örnekte android:name="MyWidgetService", RemoteViewsService alt sınıfınızı ifade eder.

Koleksiyon içeren widget'lar için düzen

Widget düzeni XML dosyanız için temel şart, ListView, GridView, StackView veya AdapterViewFlipper koleksiyon görünümlerinden birini içermesidir. StackWidget örnek için widget_layout.xml dosyası aşağıda verilmiştir:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <StackView
        android:id="@+id/stack_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:loopViews="true" />
    <TextView
        android:id="@+id/empty_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:background="@drawable/widget_item_background"
        android:textColor="#ffffff"
        android:textStyle="bold"
        android:text="@string/empty_view_text"
        android:textSize="20sp" />
</FrameLayout>

Boş görünümlerin, boş görünümün boş durumu temsil ettiği koleksiyon görünümünün kardeşleri olması gerektiğini unutmayın.

Widget'ınızın tamamı için bir düzen dosyasına ek olarak, koleksiyondaki her öğenin düzenini tanımlayan başka bir düzen dosyası oluşturun (ör. bir kitap koleksiyonundaki her kitap için bir düzen). Tüm öğeler aynı düzeni kullandığından StackWidget örneğinde yalnızca bir öğe düzeni dosyası (widget_item.xml) vardır.

Koleksiyon içeren widget'lar için AppWidgetProvider sınıfı

Normal widget'larda olduğu gibi, AppWidgetProvider alt sınıfınızdaki kodun büyük kısmı genellikle onUpdate() içine yerleştirilir. Koleksiyon içeren bir widget oluştururken onUpdate() için uygulamanızdaki en büyük fark, setRemoteAdapter() çağrısı yapmanız gerektiğidir. Bu, koleksiyon görünümüne verilerini nereden alacağını söyler. Ardından RemoteViewsService, RemoteViewsFactory uygulamanızı döndürebilir ve widget uygun verileri sunabilir. Bu yöntemi çağırırken, RemoteViewsService uygulamanızı işaret eden bir intent ve güncellenecek widget'ı belirten widget kimliğini iletin.

Örneğin, StackWidget örneğinde onUpdate() geri çağırma yöntemi, RemoteViewsService öğesini widget koleksiyonunun uzak bağdaştırıcısı olarak ayarlamak için nasıl uygulanır?

Kotlin

override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray
) {
    // Update each of the widgets with the remote adapter.
    appWidgetIds.forEach { appWidgetId ->

        // Set up the intent that starts the StackViewService, which
        // provides the views for this collection.
        val intent = Intent(context, StackWidgetService::class.java).apply {
            // Add the widget ID to the intent extras.
            putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
            data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))
        }
        // Instantiate the RemoteViews object for the widget layout.
        val views = RemoteViews(context.packageName, R.layout.widget_layout).apply {
            // Set up the RemoteViews object to use a RemoteViews adapter.
            // This adapter connects to a RemoteViewsService through the
            // specified intent.
            // This is how you populate the data.
            setRemoteAdapter(R.id.stack_view, intent)

            // The empty view is displayed when the collection has no items.
            // It must be in the same layout used to instantiate the
            // RemoteViews object.
            setEmptyView(R.id.stack_view, R.id.empty_view)
        }

        // Do additional processing specific to this widget.

        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
    super.onUpdate(context, appWidgetManager, appWidgetIds)
}

Java

public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
    // Update each of the widgets with the remote adapter.
    for (int i = 0; i < appWidgetIds.length; ++i) {

        // Set up the intent that starts the StackViewService, which
        // provides the views for this collection.
        Intent intent = new Intent(context, StackWidgetService.class);
        // Add the widget ID to the intent extras.
        intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
        intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
        // Instantiate the RemoteViews object for the widget layout.
        RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
        // Set up the RemoteViews object to use a RemoteViews adapter.
        // This adapter connects to a RemoteViewsService through the specified
        // intent.
        // This is how you populate the data.
        views.setRemoteAdapter(R.id.stack_view, intent);

        // The empty view is displayed when the collection has no items.
        // It must be in the same layout used to instantiate the RemoteViews
        // object.
        views.setEmptyView(R.id.stack_view, R.id.empty_view);

        // Do additional processing specific to this widget.

        appWidgetManager.updateAppWidget(appWidgetIds[i], views);
    }
    super.onUpdate(context, appWidgetManager, appWidgetIds);
}

Verileri kalıcı hale getirme

Bu sayfada açıklandığı gibi, RemoteViewsService alt sınıfı uzak koleksiyon görünümünü doldurmak için kullanılan RemoteViewsFactory değerini sağlar.

Özellikle şu adımları uygulayın:

1. RemoteViewsService alt sınıfı. RemoteViewsService, uzaktan adaptörün RemoteViews isteyebileceği hizmettir.

2. RemoteViewsService alt sınıfınıza RemoteViewsFactory arayüzünü uygulayan bir sınıf ekleyin. RemoteViewsFactory, uzak koleksiyon görünümü (ör. ListView, GridView, StackView) ile bu görünümün temel verileri arasındaki adaptör arayüzüdür. Veri kümesindeki her öğe için bir RemoteViews nesnesi oluşturmaktan uygulamanız sorumludur. Bu arayüz, Adapter etrafında ince bir sarmalayıcıdır.

Hizmetinizin tek bir örneğinin veya içerdiği verilerin kalıcı olmasını bekleyemezsiniz. Statik olmadığı sürece RemoteViewsService öğenize veri depolamayın. Widget'ınızın verilerinin kalıcı olmasını istiyorsanız en iyi yaklaşım, verileri işlem yaşam döngüsünün ötesinde kalan bir ContentProvider kullanmaktır. Örneğin, bir market widget'ı, her market listesi öğesinin durumunu SQL veritabanı gibi kalıcı bir konumda saklayabilir.

Not: ContentProvider kullanılarak bir widget'ın temel verilerinin nasıl kalıcılaştırılacağını gösteren bir kod örneği için WeatherDataProvider.java bölümüne bakın.

RemoteViewsService uygulamasının birincil içeriği, aşağıdaki bölümde açıklanan RemoteViewsFactory'dur.

RemoteViewsFactory arayüzü

RemoteViewsFactory arayüzünü uygulayan özel sınıfınız, widget'a koleksiyonundaki öğelerin verilerini sağlar. Bunu yapmak için widget öğesi XML düzen dosyanızı bir veri kaynağıyla birleştirir. Bu veri kaynağı, veritabanından basit bir diziye kadar her şey olabilir. StackWidget Örneğinde, veri kaynağı bir WidgetItems dizisidir. RemoteViewsFactory, verileri uzak koleksiyon görünümüne yapıştıran bir adaptör görevi görür.

RemoteViewsFactory alt sınıfınız için uygulamanız gereken en önemli iki yöntem onCreate() ve getViewAt()'dir.

Sistem, fabrikanızı ilk kez oluştururken onCreate() işlevini çağırır. Veri kaynağınızla ilgili bağlantıları veya imleçleri buradan ayarlarsınız. Örneğin, StackWidget örneği bir WidgetItem nesnesi dizisini başlatmak için onCreate() kullanır. Widget'ınız etkin olduğunda sistem, bu nesnelere dizideki dizin konumlarını kullanarak erişir ve içerdikleri metni gösterir.

StackWidget örneğinin RemoteViewsFactory uygulamasından, onCreate() yönteminin bölümlerini gösteren bir alıntı aşağıda verilmiştir:

Kotlin

private const val REMOTE_VIEW_COUNT: Int = 10

class StackRemoteViewsFactory(
        private val context: Context
) : RemoteViewsService.RemoteViewsFactory {

    private lateinit var widgetItems: List<WidgetItem>

    override fun onCreate() {
        // In onCreate(), set up any connections or cursors to your data
        // source. Heavy lifting, such as downloading or creating content,
        // must be deferred to onDataSetChanged() or getViewAt(). Taking
        // more than 20 seconds on this call results in an ANR.
        widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") }
        ...
    }
    ...
}

Java

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {
    private static final int REMOTE_VIEW_COUNT = 10;
    private List<WidgetItem> widgetItems = new ArrayList<WidgetItem>();

    public void onCreate() {
        // In onCreate(), setup any connections or cursors to your data
        // source. Heavy lifting, such as downloading or creating content,
        // must be deferred to onDataSetChanged() or getViewAt(). Taking
        // more than 20 seconds on this call results in an ANR.
        for (int i = 0; i < REMOTE_VIEW_COUNT; i++) {
            widgetItems.add(new WidgetItem(i + "!"));
        }
        ...
    }
...

RemoteViewsFactory yöntemi getViewAt(), veri kümesinde belirtilen position konumundaki verilere karşılık gelen bir RemoteViews nesnesi döndürür. StackWidget örneğinin RemoteViewsFactory uygulamasından bir alıntı aşağıda verilmiştir:

Kotlin

override fun getViewAt(position: Int): RemoteViews {
    // Construct a remote views item based on the widget item XML file
    // and set the text based on the position.
    return RemoteViews(context.packageName, R.layout.widget_item).apply {
        setTextViewText(R.id.widget_item, widgetItems[position].text)
    }
}

Java

public RemoteViews getViewAt(int position) {
    // Construct a remote views item based on the widget item XML file
    // and set the text based on the position.
    RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_item);
    views.setTextViewText(R.id.widget_item, widgetItems.get(position).text);
    return views;
}

Öğelere tek tek davranış ekleme

Önceki bölümlerde, verilerinizin widget koleksiyonunuza nasıl bağlanacağı gösterilmiştir. Peki koleksiyon görünümünüzdeki öğelere dinamik davranış eklemek isterseniz ne olur?

onUpdate() sınıfıyla etkinlikleri işleme bölümünde açıklandığı gibi, bir nesnenin tıklama davranışını ayarlamak için genellikle setOnClickPendingIntent()'i kullanırsınız (ör. bir düğmenin Activity başlatmasına neden olmak için). Ancak tek bir koleksiyon öğesindeki alt görünümler için bu yaklaşıma izin verilmez. Örneğin, Gmail widget'ında uygulamayı başlatan global bir düğme oluşturmak için setOnClickPendingIntent()'ü kullanabilirsiniz ancak liste öğelerinde bu yöntemi kullanamazsınız.

Bunun yerine, koleksiyondaki öğelere tek tek tıklama davranışı eklemek için setOnClickFillInIntent() öğesini kullanın. Bu işlem, koleksiyon görünümünüz için bekleyen bir intent şablonu oluşturmayı ve ardından RemoteViewsFactory aracılığıyla koleksiyondaki her öğe için bir doldurma intent'i ayarlamayı içerir.

Bu bölümde, tek tek öğelere nasıl davranış ekleneceği StackWidget örneği kullanılarak açıklanmaktadır. StackWidget örneğinde, kullanıcı üst görünüme dokunursa widget, "Dokunulan görünüm n" Toast mesajını gösterir. Burada n, dokunulan görünümün dizinidir (konumudur). İşleyişi:

• AppWidgetProvider alt sınıfı olan StackWidgetProvider, TOAST_ACTION adlı özel bir işlemle bekleyen bir intent oluşturur.

• Kullanıcı bir görünüme dokunduğunda intent tetiklenir ve TOAST_ACTION yayınlanır.

• Bu yayın, StackWidgetProvider sınıfının onReceive() yöntemi tarafından yakalanır ve widget, dokunulan görünüm için Toast mesajını gösterir. Koleksiyon öğeleriyle ilgili veriler, RemoteViewsFactory tarafından RemoteViewsService üzerinden sağlanır.

Not: StackWidget örneğinde yayın kullanılmaktadır ancak genellikle bu tür bir senaryoda bir widget etkinlik başlatır.

Beklemedeki intent şablonunu ayarlama

StackWidgetProvider (AppWidgetProvider alt sınıfı), bekleyen bir intent oluşturur. Bir koleksiyondaki öğeler kendi bekleyen intent'lerini ayarlayamaz. Bunun yerine, koleksiyon bir bütün olarak bekleyen bir intent şablonu oluşturur ve öğeler tek tek benzersiz davranışlar oluşturmak için bir doldurma intent'i ayarlar.

Bu sınıf, kullanıcı bir görünüme dokunduğunda gönderilen yayını da alır. Bu etkinliği onReceive() yönteminde işler. Intent'in işlemi TOAST_ACTION ise widget, mevcut görünüm için Toast mesajı gösterir.

Kotlin

const val TOAST_ACTION = "com.example.android.stackwidget.TOAST_ACTION"
const val EXTRA_ITEM = "com.example.android.stackwidget.EXTRA_ITEM"

class StackWidgetProvider : AppWidgetProvider() {

    ...

    // Called when the BroadcastReceiver receives an Intent broadcast.
    // Checks whether the intent's action is TOAST_ACTION. If it is, the
    // widget displays a Toast message for the current item.
    override fun onReceive(context: Context, intent: Intent) {
        val mgr: AppWidgetManager = AppWidgetManager.getInstance(context)
        if (intent.action == TOAST_ACTION) {
            val appWidgetId: Int = intent.getIntExtra(
                    AppWidgetManager.EXTRA_APPWIDGET_ID,
                    AppWidgetManager.INVALID_APPWIDGET_ID
            )
            // EXTRA_ITEM represents a custom value provided by the Intent
            // passed to the setOnClickFillInIntent() method to indicate the
            // position of the clicked item. See StackRemoteViewsFactory in
            // Set the fill-in Intent for details.
            val viewIndex: Int = intent.getIntExtra(EXTRA_ITEM, 0)
            Toast.makeText(context, "Touched view $viewIndex", Toast.LENGTH_SHORT).show()
        }
        super.onReceive(context, intent)
    }

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Update each of the widgets with the remote adapter.
        appWidgetIds.forEach { appWidgetId ->

            // Sets up the intent that points to the StackViewService that
            // provides the views for this collection.
            val intent = Intent(context, StackWidgetService::class.java).apply {
                putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
                // When intents are compared, the extras are ignored, so embed
                // the extra sinto the data so that the extras are not ignored.
                data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))
            }
            val rv = RemoteViews(context.packageName, R.layout.widget_layout).apply {
                setRemoteAdapter(R.id.stack_view, intent)

                // The empty view is displayed when the collection has no items.
                // It must be a sibling of the collection view.
                setEmptyView(R.id.stack_view, R.id.empty_view)
            }

            // This section makes it possible for items to have individualized
            // behavior. It does this by setting up a pending intent template.
            // Individuals items of a collection can't set up their own pending
            // intents. Instead, the collection as a whole sets up a pending
            // intent template, and the individual items set a fillInIntent
            // to create unique behavior on an item-by-item basis.
            val toastPendingIntent: PendingIntent = Intent(
                    context,
                    StackWidgetProvider::class.java
            ).run {
                // Set the action for the intent.
                // When the user touches a particular view, it has the effect of
                // broadcasting TOAST_ACTION.
                action = TOAST_ACTION
                putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
                data = Uri.parse(toUri(Intent.URI_INTENT_SCHEME))

                PendingIntent.getBroadcast(context, 0, this, PendingIntent.FLAG_UPDATE_CURRENT)
            }
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent)

            appWidgetManager.updateAppWidget(appWidgetId, rv)
        }
        super.onUpdate(context, appWidgetManager, appWidgetIds)
    }
}

Java

public class StackWidgetProvider extends AppWidgetProvider {
    public static final String TOAST_ACTION = "com.example.android.stackwidget.TOAST_ACTION";
    public static final String EXTRA_ITEM = "com.example.android.stackwidget.EXTRA_ITEM";

    ...

    // Called when the BroadcastReceiver receives an Intent broadcast.
    // Checks whether the intent's action is TOAST_ACTION. If it is, the
    // widget displays a Toast message for the current item.
    @Override
    public void onReceive(Context context, Intent intent) {
        AppWidgetManager mgr = AppWidgetManager.getInstance(context);
        if (intent.getAction().equals(TOAST_ACTION)) {
            int appWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
            // EXTRA_ITEM represents a custom value provided by the Intent
            // passed to the setOnClickFillInIntent() method to indicate the
            // position of the clicked item. See StackRemoteViewsFactory in
            // Set the fill-in Intent for details.
            int viewIndex = intent.getIntExtra(EXTRA_ITEM, 0);
            Toast.makeText(context, "Touched view " + viewIndex, Toast.LENGTH_SHORT).show();
        }
        super.onReceive(context, intent);
    }

    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Update each of the widgets with the remote adapter.
        for (int i = 0; i < appWidgetIds.length; ++i) {

            // Sets up the intent that points to the StackViewService that
            // provides the views for this collection.
            Intent intent = new Intent(context, StackWidgetService.class);
            intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            // When intents are compared, the extras are ignored, so embed
            // the extras into the data so that the extras are not
            // ignored.
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
            rv.setRemoteAdapter(appWidgetIds[i], R.id.stack_view, intent);

            // The empty view is displayed when the collection has no items. It
            // must be a sibling of the collection view.
            rv.setEmptyView(R.id.stack_view, R.id.empty_view);

            // This section makes it possible for items to have individualized
            // behavior. It does this by setting up a pending intent template.
            // Individuals items of a collection can't set up their own pending
            // intents. Instead, the collection as a whole sets up a pending
            // intent template, and the individual items set a fillInIntent
            // to create unique behavior on an item-by-item basis.
            Intent toastIntent = new Intent(context, StackWidgetProvider.class);
            // Set the action for the intent.
            // When the user touches a particular view, it has the effect of
            // broadcasting TOAST_ACTION.
            toastIntent.setAction(StackWidgetProvider.TOAST_ACTION);
            toastIntent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            PendingIntent toastPendingIntent = PendingIntent.getBroadcast(context, 0, toastIntent,
                PendingIntent.FLAG_UPDATE_CURRENT);
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent);

            appWidgetManager.updateAppWidget(appWidgetIds[i], rv);
        }
        super.onUpdate(context, appWidgetManager, appWidgetIds);
    }
}

Doldurma niyetini ayarlama

RemoteViewsFactory, koleksiyondaki her öğe için bir doldurma amacı belirlemelidir. Bu sayede, belirli bir öğenin tıklamayla ilgili işlemini ayırt edebilirsiniz. Ardından, öğeye dokunulduğunda yürütülecek nihai amacı belirlemek için doldurma amacı PendingIntent şablonuyla birleştirilir.

Kotlin

private const val REMOTE_VIEW_COUNT: Int = 10

class StackRemoteViewsFactory(
        private val context: Context,
        intent: Intent
) : RemoteViewsService.RemoteViewsFactory {

    private lateinit var widgetItems: List<WidgetItem>
    private val appWidgetId: Int = intent.getIntExtra(
            AppWidgetManager.EXTRA_APPWIDGET_ID,
            AppWidgetManager.INVALID_APPWIDGET_ID
    )

    override fun onCreate() {
        // In onCreate(), set up any connections or cursors to your data source.
        // Heavy lifting, such as downloading or creating content, must be
        // deferred to onDataSetChanged() or getViewAt(). Taking more than 20
        // seconds on this call results in an ANR.
        widgetItems = List(REMOTE_VIEW_COUNT) { index -> WidgetItem("$index!") }
        ...
    }
    ...

    override fun getViewAt(position: Int): RemoteViews {
        // Construct a remote views item based on the widget item XML file
        // and set the text based on the position.
        return RemoteViews(context.packageName, R.layout.widget_item).apply {
            setTextViewText(R.id.widget_item, widgetItems[position].text)

            // Set a fill-intent to fill in the pending intent template.
            // that is set on the collection view in StackWidgetProvider.
            val fillInIntent = Intent().apply {
                Bundle().also { extras ->
                    extras.putInt(EXTRA_ITEM, position)
                    putExtras(extras)
                }
            }
            // Make it possible to distinguish the individual on-click
            // action of a given item.
            setOnClickFillInIntent(R.id.widget_item, fillInIntent)
            ...
        }
    }
    ...
}

Java

public class StackWidgetService extends RemoteViewsService {
    @Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {
    private static final int count = 10;
    private List<WidgetItem> widgetItems = new ArrayList<WidgetItem>();
    private Context context;
    private int appWidgetId;

    public StackRemoteViewsFactory(Context context, Intent intent) {
        this.context = context;
        appWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
    }

    // Initialize the data set.
    public void onCreate() {
        // In onCreate(), set up any connections or cursors to your data
        // source. Heavy lifting, such as downloading or creating
        // content, must be deferred to onDataSetChanged() or
        // getViewAt(). Taking more than 20 seconds on this call results
        // in an ANR.
        for (int i = 0; i < count; i++) {
            widgetItems.add(new WidgetItem(i + "!"));
        }
        ...
    }

    // Given the position (index) of a WidgetItem in the array, use the
    // item's text value in combination with the widget item XML file to
    // construct a RemoteViews object.
    public RemoteViews getViewAt(int position) {
        // Position always ranges from 0 to getCount() - 1.

        // Construct a RemoteViews item based on the widget item XML
        // file and set the text based on the position.
        RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_item);
        rv.setTextViewText(R.id.widget_item, widgetItems.get(position).text);

        // Set a fill-intent to fill in the pending
        // intent template that is set on the collection view in
        // StackWidgetProvider.
        Bundle extras = new Bundle();
        extras.putInt(StackWidgetProvider.EXTRA_ITEM, position);
        Intent fillInIntent = new Intent();
        fillInIntent.putExtras(extras);
        // Make it possible to distinguish the individual on-click
        // action of a given item.
        rv.setOnClickFillInIntent(R.id.widget_item, fillInIntent);

        // Return the RemoteViews object.
        return rv;
    }
    ...
}

Koleksiyon verilerini güncel tutma

Şekil 2, koleksiyon kullanan bir widget'taki güncelleme akışını göstermektedir. Widget kodunun RemoteViewsFactory ile nasıl etkileşime geçtiğini ve güncellemeleri nasıl tetikleyebileceğinizi gösterir:

Şekil 2. Güncellemeler sırasında RemoteViewsFactory ile etkileşim

Koleksiyon kullanan widget'lar kullanıcılara güncel içerikler sunabilir. Örneğin, Gmail widget'ı kullanıcılara gelen kutularının anlık görüntüsünü sunar. Bunu yapmak için yeni verileri almak ve görüntülemek üzere RemoteViewsFactory ve koleksiyon görünümünüzü tetikleyin.

Bunun için notifyAppWidgetViewDataChanged()'i aramak üzere AppWidgetManager simgesini kullanın. Bu çağrı, yeni verileri getirmenize olanak tanıyan RemoteViewsFactory nesnenizin onDataSetChanged() metoduna geri çağrı gönderir.

Yoğun işlem gerektiren işlemleri onDataSetChanged() geri çağırma işlevinde senkronize olarak gerçekleştirebilirsiniz. Bu çağrının, meta veriler veya görüntüleme verileri RemoteViewsFactory'ten getirilmeden önce tamamlanacağı garanti edilir. getViewAt() yönteminde yoğun işlem gerektiren işlemleri de gerçekleştirebilirsiniz. Bu çağrı uzun sürerse RemoteViewsFactory nesnesinin getLoadingView() yöntemi tarafından belirtilen yükleme görünümü, döndürülene kadar koleksiyon görünümünün ilgili konumunda gösterilir.

Koleksiyonu doğrudan iletmek için RemoteCollectionItems'i kullanın

Android 12 (API düzeyi 31), uygulamanızın koleksiyon görünümünü doldururken doğrudan bir koleksiyonu iletmesine olanak tanıyan setRemoteAdapter(int viewId, RemoteViews.RemoteCollectionItems items) yöntemini ekler. Adaptörünüzü bu yöntemi kullanarak ayarlarsanız RemoteViewsFactory uygulamanız ve notifyAppWidgetViewDataChanged() işlevini çağırmanız gerekmez.

Bu yaklaşım, adaptörünüzü doldurmayı kolaylaştırmanın yanı sıra kullanıcılar yeni bir öğe görmek için listede aşağı kaydırdığında yeni öğelerin doldurulmasıyla ilgili gecikmeyi de ortadan kaldırır. Koleksiyon öğeleriniz nispeten küçük olduğu sürece adaptörü ayarlama konusunda bu yaklaşım tercih edilir. Ancak, örneğin, koleksiyonunuzda setImageViewBitmap'a iletilen çok sayıda Bitmaps varsa bu yaklaşım iyi çalışmaz.

Koleksiyonda sabit bir düzen grubu kullanılmıyorsa (yani bazı öğeler yalnızca bazen mevcutsa) koleksiyonun içerebileceği maksimum benzersiz düzen sayısını belirtmek için setViewTypeCount parametresini kullanın. Bu sayede, bağdaştırıcının uygulama widget'ınızdaki güncellemelerde yeniden kullanılmasına olanak tanınmış olur.

Basitleştirilmiş RemoteViews koleksiyonlarının nasıl uygulanacağına dair bir örnek aşağıda verilmiştir.

Kotlin

val itemLayouts = listOf(
        R.layout.item_type_1,
        R.layout.item_type_2,
        ...
)

remoteView.setRemoteAdapter(
        R.id.list_view,
        RemoteViews.RemoteCollectionItems.Builder()
            .addItem(/* id= */ ID_1, RemoteViews(context.packageName, R.layout.item_type_1))
            .addItem(/* id= */ ID_2, RemoteViews(context.packageName, R.layout.item_type_2))
            ...
            .setViewTypeCount(itemLayouts.count())
            .build()
)

Java

List<Integer> itemLayouts = Arrays.asList(
    R.layout.item_type_1,
    R.layout.item_type_2,
    ...
);

remoteView.setRemoteAdapter(
    R.id.list_view,
    new RemoteViews.RemoteCollectionItems.Builder()
        .addItem(/* id= */ ID_1, new RemoteViews(context.getPackageName(), R.layout.item_type_1))
        .addItem(/* id= */ ID_2, new RemoteViews(context.getPackageName(), R.layout.item_type_2))
        ...
        .setViewTypeCount(itemLayouts.size())
        .build()
);

Not: setViewTypeCount() işlevini çağırırken bu koleksiyonda RemoteViews tarafından kullanılan maksimum sayıda farklı düzen kimliğini iletin. Aksi takdirde, görüntüleme türü sayısı sağlanan öğelerden çıkarılır ve ek düzenler kullanan bir güncelleme gönderilirken bağdaştırı yeniden oluşturulur.