AsyncDataModel

Since: BlackBerry 10.2.0

#include <bb/cascades/datamanager/AsyncDataModel>

To link against this class, add the following line to your .pro file: LIBS += -lbbcascadesdatamanager

A data model that manages a partial cache of data from the full data set.

The AsyncDataModel class is a DataModel that manages a contiguous cache window over the full result set. The window is moved with asynchronous database operations, based on access to the data using a data query. If items are accessed outside the current cache window, an empty container is returned, and itemUpdated will be called to notify the UI when the data is available.

Here is a QML example showing the usage of an AsyncDataModel:

import bb.cascades 1.2
import bb.cascades.datamanager 1.2
Page {
    content: Container {
        layout: StackLayout {}
        ListView {
            id: myListView
            dataModel: dm
            listItemComponents: [
                ListItemComponent {
                    StandardListItem {
                        title: ListItemData.firstname + " " + ListItemData.lastname
                        imageSource: ListItemData.image
                        description: ListItemData.title
                    }
                }
            ]
        }
        attachedObjects: [
            // an example to demonstrate how to use an AsyncDataModel
            AsyncDataModel {
                id: dm
                cacheSize: 200 // this is the default in-memory capacity
                
                // can use any query that implements the DataQuery interface
                // SqlDataQuery is the default implementation provided with the library
                query: SqlDataQuery {
                    source: "sql/contacts1k.db"
                    query: "select id, firstname, lastname, title, image, active, revision_id " +
                           "from contact order by lastname, firstname"
                    countQuery: "select count(*) from contact"
                    keyColumn:    "id"
                    revisionColumn: "revision_id"
                    revisionQuery:  "select revision_id from revision"
                    onError: console.log("SQL query error: " + code + ", " + message)
                }
                
                onLoaded: console.log("initial model data is loaded")
            }
        ]
    }
    onCreationCompleted: { 
        dm.load();
    }
}


Overview

QML properties

cacheSize: int
query: bb::cascades::datamanager::DataQueryInherited

QML signals

Properties Index

Public Functions Index

AsyncDataModel (QObject *parent=0)
virtual ~AsyncDataModel ()
intcacheSize () const
virtual Q_INVOKABLE intchildCount (const QVariantList &indexPath)
virtual Q_INVOKABLE QVariantdata (const QVariantList &indexPath)
virtual Q_INVOKABLE boolhasChildren (const QVariantList &indexPath)
virtual Q_INVOKABLE QStringitemType (const QVariantList &indexPath)
virtual Q_INVOKABLE voidload ()
virtual bb::cascades::datamanager::DataQuery *query ()
voidsetCacheSize (int cacheSize)
virtual voidsetQuery (bb::cascades::datamanager::DataQuery *query)
DataModel (QObject *parent=0)Inherited
QueryDataModel (QObject *parent=0)Inherited

Signals Index

voidcacheSizeChanged (int cacheSize)
voiditemAdded (QVariantList indexPath)Inherited
voiditemRemoved (QVariantList indexPath)Inherited
voiditemsChanged (bb::cascades::DataModelChangeType::Type eChangeType=bb::cascades::DataModelChangeType::Init, QSharedPointer< bb::cascades::DataModel::IndexMapper > indexMapper=QSharedPointer< bb::cascades::DataModel::IndexMapper >(0))Inherited
voiditemUpdated (QVariantList indexPath)Inherited
voidloaded ()Inherited
voidqueryChanged ()Inherited

Properties

int cacheSize

The maximum count of data items maintained in the cache.

The default capacity is 200 data items.

Since:

BlackBerry 10.2.0

bb::cascades::datamanager::DataQuery queryInherited

The data query to use for obtaining data.

Note: Ownership of the query object will be taken over by this model.

Since:

BlackBerry 10.2.0

Public Functions

AsyncDataModel (

Constructor.

Parameters
parent

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

Since:

BlackBerry 10.2.0

virtual~AsyncDataModel ()

Destructor.

Since:

BlackBerry 10.2.0

int cacheSize ()

Return the current capacity for the data cache for this model.

The default capacity is 200 data items.

Return:

the current data cache capacity.

Since:

BlackBerry 10.2.0

virtual Q_INVOKABLE int childCount (

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

The root item is represented by an empty index path. This example shows how to get the number of top level items (items having the root item as parent).

int numberOfHeaders = model->childCount(QVariantList());
Parameters
indexPath

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

Return:

The number of children. The return value for invalid index paths is undefined.

Since:

BlackBerry 10.2.0

virtual Q_INVOKABLE QVariant data (

Returns the data associated with the specified item.

Does not transfer any ownership, any returned QObject is still owned by its parent. A QObject returned by this function always have a parent. The ListView will pass on the data as a parameter to ListItemProvider::updateItem().

Parameters
indexPath

The path to the item in the model.

Return:

A QVariantMap wrapped in a QVariant.

Since:

BlackBerry 10.2.0

virtual Q_INVOKABLE bool hasChildren (

Indicates whether the data item specified by the indexPath has children.

Parameters
indexPath

The path to the data item to query for children.

Return:

true if the data item has one or more children, false otherwise. ListView never calls this function for its root node (but does call childCount() for the root node), therefore the return-value for an empty index path is undefined.

Since:

BlackBerry 10.2.0

virtual Q_INVOKABLE QString itemType (

Returns the type for the specified item.

Parameters
indexPath

The path to the item in the model.

Return:

a string identifying the type for this item.

Since:

BlackBerry 10.2.0

virtual Q_INVOKABLE void load ()

Load the initial cache of data.

After setting the data query and other properties, call this method to load the data.

Since:

BlackBerry 10.2.0

virtualbb::cascades::datamanager::DataQuery * query ()

Return the data query for this model.

Return:

The data query to use with this data model.

Since:

BlackBerry 10.2.0

void setCacheSize (
  • intcacheSize)

Set the capacity for the data cache for this model.

The default capacity is 200 data items.

Parameters
cacheSize

The new data cache capacity.

Since:

BlackBerry 10.2.0

virtual void setQuery (

Set the data query that this model will use to load data.

Note that ownership of the query is taken over by the model and the query is executed in a secondary thread.

Parameters
query

The data query to use with this data model.

Since:

BlackBerry 10.2.0

DataModel (Inherited

Constructs a DataModel instance with the specified parent.

If the specified parent is not 0, the ownership of the constructed DataModel is transferred to the parent.

Parameters
parent

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

Since:

BlackBerry 10.0.0

QueryDataModel (Inherited

Constructor.

Parameters
parent

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

Since:

BlackBerry 10.2.0

Signals

void cacheSizeChanged (
  • intcacheSize)

Emitted when the cache capacity for this data model has changed.

Parameters
cacheSize

The new cache capacity.

Since:

BlackBerry 10.2.0

void itemAdded (Inherited

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 itemRemoved (Inherited

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

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

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

Parameters
indexPath

IndexPath to the updated item.

Since:

BlackBerry 10.0.0

void loaded ()Inherited

Emitted when the DataModel is first loaded after calling the load method.

The number of loaded signal may not equal to the number of load method call. But it is always guaranteed that a load method call results in a loaded signal being emitted. For example, two consecutive load method calls could results in only one loaded signal.

Since:

BlackBerry 10.2.0

void queryChanged ()Inherited

Emitted when the query has changed.

Since:

BlackBerry 10.2.0

Last modified: 2014-03-13

comments powered by Disqus