DataModel

Since: BlackBerry 10.0.0

#include <bb/cascades/DataModel>

An abstract class that can be used to provide a ListView with data.

Any data that can be contained in a QVariant can be provided to the ListView. Typical examples of QVariant content are QString, QVariantMap and QObject*. The data can also be an empty QVariant for each item, if the ListView has a ListItemProvider with access to all relevant data.

When a DataModel implementation is attached to a ListView, the ListView will call the DataModel implementation when model data is needed and will listen to the various signals emitted from the DataModel implementation. ListView takes ownership of any QObject* (wrapped in QVariant) returned by data(), if the returned object doesn't already have a parent.

A single DataModel can be connected to any number of ListView objects. ListView has a property ListView::rootIndexPath that allows it to choose which node in the DataModel to use as the root node.

Index paths

Index paths are used for identifying items in ListView, DataModel and all related classes. In C++ an index path is a QVariantList object containing a number of QVariant integers, one for each ancestor (including the root item) of the specified item. The reason for index paths being QVariantList objects in C++ is that QVariantList objects are the C++ equivalent of QML JavaScript arrays. So in QML an index path is simply an array containing integers. For an item that is a direct child of the root item, the index path contains a single integer. A child of that item would instead have an index path consisting of two integers, and so on.

Examples of index paths:

  • [3] - index path for the fourth child of the root item

  • [3,0] - index path for the first child of the fourth child of the root item

  • [] - index path for the root item (an empty array)

Example of accessing indexes from index paths in C++:

  • indexPath[0].toInt() - gets the top level index from this index path

  • indexPath[1].toInt() - gets the second level index from this index path (if the index path contains that many levels)

See [Index paths](http://developer.blackberry.com/native/documentation/cascades/ui/lists/list_view_selection.html#indexpaths) for more information.


Overview

Classes

IndexMapper

Indicates whether a ListView can translate cached items to new indexes.

Public Functions Index

DataModel (QObject *parent=0)
virtual ~DataModel ()
Q_INVOKABLE intchildCount (const QVariantList &indexPath)=0
Q_INVOKABLE QVariantdata (const QVariantList &indexPath)=0
Q_INVOKABLE boolhasChildren (const QVariantList &indexPath)=0
virtual Q_INVOKABLE QStringitemType (const QVariantList &indexPath)

Signals Index

voiditemAdded (QVariantList indexPath)
voiditemMoved (QVariantList fromIndexPath, QVariantList toIndexPath)
voiditemRemoved (QVariantList indexPath)
voiditemsChanged (bb::cascades::DataModelChangeType::Type eChangeType=bb::cascades::DataModelChangeType::Init, QSharedPointer< bb::cascades::DataModel::IndexMapper > indexMapper=QSharedPointer< bb::cascades::DataModel::IndexMapper >(0))
voiditemUpdated (QVariantList indexPath)

Public Functions

DataModel (

Constructs a DataModel instance with the specified parent.

Parameters
parent

The data model owner, or 0. Optional and will default to 0 if not specified.

Since:

BlackBerry 10.0.0

virtual~DataModel ()

Destructor.

Since:

BlackBerry 10.0.0

Q_INVOKABLE int childCount (

Returns the number of children to the data item specified by indexPath.

Parameters
indexPath

The index path to the data item to get child count for.

Return:

The number of children.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariant data (

Returns the data item that is associated with indexPath.

This function transfers ownership for QObject objects, if the returned object doesn't have any parent.

The ListView will pass the data item as a parameter to ListItemProvider::updateItem(). If item visuals are created by using ListItemComponent in QML, ListView makes the data returned from this function available in the item visuals as the context property ListItemData, and also as the property ListItem.data attached to the item visual root node.

Parameters
indexPath

The index path to the data item.

Return:

The data item associated with the indexPath. The caller must take ownership of any returned QObject objects, if the returned object doesn't already have a parent.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool hasChildren (

Indicates whether the data item specified by indexPath has children.

ListView never calls this function for its root node (but does call childCount(QVariantList) for the root node), so if this DataModel only contains one level of items (no child items), this function can always return false.

Here's an example of how to override hasChildren().

 bool SmartViewModel::hasChildren(const QVariantList &indexPath)
 {
     // Checks whether the indexPath is an empty array.
     // An empty array indicates the the index path is for the
     // root element.
     if(indexPath.empty())
         return true; // The root node always has children

     // ...Check for other index paths...
 }
Parameters
indexPath

The index path to the data item to query for children.

Return:

true if the data item has one or more children, false otherwise.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString itemType (

Returns the item type for the data item at indexPath.

The item type will then be used when the ListView requests items from its ListItemProvider. It will also be used when the DataModel has indicated that items have been updated using the signals DataModel::itemUpdated or DataModel::itemsChanged with DataModelChangeType::Update.

If a ListItemTypeMapper has been provided to a ListView, the ListView calls ListItemTypeMapper::itemType() instead of DataModel::itemType().

Parameters
indexPath

The index path to the data item.

Return:

A string representing the user-defined type of the item. The default implementation returns an empty string.

Since:

BlackBerry 10.0.0

Signals

void itemAdded (

Emitted when a data item has been added to this DataModel.

Parameters
indexPath

The index path to the new item.

Since:

BlackBerry 10.0.0

void itemMoved (

Emitted when a data item has been moved within the DataModel.

A moved item will retain its visual appearance and data on the server.

Parameters
fromIndexPath

The original index path of the moved item.

toIndexPath

The new index path of the moved item.

Since:

BlackBerry 10.3.0

void itemRemoved (

Emitted when a data item has been removed from this DataModel.

Parameters
indexPath

The index path to the removed item.

Since:

BlackBerry 10.0.0

void itemsChanged (

Emitted when the model has changed in a way that would be inefficient to describe with single instances of the other signals.

No other signals (DataModel::itemAdded, DataModel::itemUpdated, or DataModel::itemRemoved) are emitted if this signal is emitted when a change occurs in this DataModel.

Typical examples of when this signal is emitted: data has been sorted (so that many items have changed places), the DataModel has been cleared (all items have been removed), or a batch of items has been added.

If eChangeType is DataModelChangeType::Init, or if eChangeType is DataModelChangeType::AddRemove and indexMapper is 0, a ListView reacts to this signal by releasing all of the items in its cache.

If eChangeType is AddRemove and an IndexMapper is provided, the ListView instead calls IndexMapper::newIndexPath() for each item in its cache.

If eChangeType is DataModelChangeType::Update, a ListView reacts to this signal by calling DataModel::data() again for every item in its cache.

Parameters
eChangeType

The type of change.

indexMapper

An index mapper that contains update information.

Since:

BlackBerry 10.0.0

void itemUpdated (

Emitted when a data item in this DataModel has been updated.

Parameters
indexPath

IndexPath to the updated item.

Since:

BlackBerry 10.0.0

Last modified: 2014-09-30



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

comments powered by Disqus