Since: BlackBerry 10.0.0

#include <bb/cascades/ListItemProvider>

An interface for providing VisualNode objects as items in a ListView.

Using ListItemProvider is the C++ approach for customizing list item visuals. In QML, list item visuals are customized by declaring one or several ListItemComponent objects on the ListView::listItemComponents property.

By default, if no ListItemProvider is attached to a ListView, the ListView uses Header for items of type "header" and StandardListItem for all other items.

When you implement ListItemProvider, these two functions are required:

A single ListItemProvider can be used by any number of ListView objects.

Here's an example of how to extend ListItemProvider and override its createItem() and updateItem() functions. The class is called MyItemClassFactory and it's used to create list items for each object in the list.

 class MyItemClassFactory: public bb::cascades::ListItemProvider

     VisualNode * createItem(ListView* list, const QString &type);

     void updateItem(ListView* list, VisualNode *listItem, const QString &type,
                     const QVariantList &indexPath, const QVariant &data);

Within the definition for createItem(), a MyItemClass object is created. MyItemClass is a custom class that implements ListItemListener, and its constructor returns a VisualNode object representing the list item. Within the definition for updateItem(), MyItemClass::updateItem() is called to update the visual control with new data.


 VisualNode * MyItemClassFactory::createItem(ListView* list, const QString &type)
     //We only have one item type so we do not need to check the type variable.
     MyItemClass *myItem = new MyItemClass();
     return myItem;

 void MyItemClassFactory::updateItem(ListView* list, bb::cascades::VisualNode *listItem,
         const QString &type, const QVariantList &indexPath, const QVariant &data)
     // Update the control with correct data.
     QVariantMap map = data.value<QVariantMap>();
     MyItemClass *myItem = static_cast<MyItemClass *>(listItem);
     // Call  the instance of our CustomContrlol MyItemClass and provide the data we want it to layout
     myItem->updateItem(map["title"].toString(), map["image"].toString());

Here is how the ListItemProvider is attached to the ListView.

 ListView *listView = new ListView();
 MyItemClassFactory *myItemProvider = new MyItemClassFactory();

To see how the MyItemClass class is created, see the ListItemListener API documentation.

For a complete example, download the Cascades Cookbook C++ sample app.


Public Functions Index

ListItemProvider (QObject *parent=0)
virtual ~ListItemProvider ()
VisualNode *createItem (ListView *list, const QString &type)=0
voidupdateItem (ListView *list, VisualNode *listItem, const QString &type, const QVariantList &indexPath, const QVariant &data)=0

Signals Index

Public Functions

ListItemProvider (

Constructs a ListItemProvider instance with the specified parent.


The parent QObject, or 0. Optional and will default to 0 if not specified.


BlackBerry 10.0.0

virtual~ListItemProvider ()



BlackBerry 10.0.0

VisualNode * createItem (

Creates a VisualNode for the specified ListView, to be used as a list item.

The type of list item is determined based on the type parameter, which corresponds to the type returned by the DataModel (through DataModel::itemType). The ListView takes ownership of the returned VisualNode.


The ListView for which the item should be created.


The list item type, corresponding to the type provided by the DataModel that is used by list.


The newly created VisualNode.


BlackBerry 10.0.0

void updateItem (

Updates the specified list item based on the provided type, index path, and data.

This function is called whenever an item is about to be shown, and also when the data representation of the item (in the DataModel) has changed.


The ListView that contains the item to be updated.


The list item to be updated.


The list item type, corresponding to the type provided by the DataModel that is used by list.


The index path to the item that is to be updated.


The data from the DataModel that corresponds to listItem.


BlackBerry 10.0.0


void itemUpdatesNeeded ()

Emitted when the ListView that uses this ListItemProvider should call updateItem() for all of its cached items.

The ListItemProvider implementation should typically emit this signal when an application wants to change the visual appearance of all items in a ListView.


BlackBerry 10.0.0

Last modified: 2015-03-26

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus