DataModelDecorator

Since: BlackBerry 10.2.0

#include <bb/cascades/datamanager/DataModelDecorator>

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

DataModelDecorator is used to decorate the DataModel before it is used by ListView.

This base class delegates all DataModel method calls to the model being decorated. It also connects the corresponding DataModel Q_SIGNALS to the model being decorated.

This class can be useful when reinterpreting data before being used by ListView. For example, the itemType() method can return custom types depending on the contents of the data or the data() method can be used to add custom data columns based on existing data.

DataModelDecorator is also used to insert data. The inserted data can be generated from the existing data being decorated, or anything that does not have to be related to the model being decorated.

This class can serve the role of a View Model in the MVVM design pattern. See a description of MVVM here: [Model View ViewModel](http://en.wikipedia.org/wiki/Model_View_ViewModel).

Here is a QML example showing the usage of a DataModelDecorator:

import bb.cascades 1.2
import bb.cascades.datamanager 1.2
import bb.cascades.decorators 1.2

Page {
    content: Container {
        layout: StackLayout {
        }
        ListView {
            id: lv
            dataModel: dmLogger
            listItemComponents: [
                ListItemComponent {
                    StandardListItem {
                        title: ListItemData.firstname + " " + ListItemData.lastname
                        imageSource: ListItemData.image
                        description: ListItemData.title
                    }
                }
            ]
        }
        attachedObjects: [
            // An example to demonstrate how to use a DataModelDecorator.
            // Notes:
            //  There are no DataModelDecorator implementations in the library.
            //  This DataModelLoggerDecorator logs calls and signals in the underlying model for debugging.
            //  See the list decorator sample app for the source code for this and other decorator classes.
            DataModelLoggerDecorator {
                id: dmLogger
                model: AsyncDataModel {
                    id: dm
                    cacheSize: 200
                    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

Inheritance

bb::cascades::DataModel
bb::cascades::datamanager::DataModelDecorator

QML properties

model: bb::cascades::DataModel

QML signals

Public Functions Index

DataModelDecorator (QObject *parent=0)
virtual ~DataModelDecorator ()
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)
bb::cascades::DataModel *model ()
virtual Q_SLOT voidonItemAdded (QVariantList indexPath)
virtual Q_SLOT voidonItemRemoved (QVariantList indexPath)
virtual Q_SLOT voidonItemsChanged (bb::cascades::DataModelChangeType::Type eChangeType=bb::cascades::DataModelChangeType::Init, QSharedPointer< bb::cascades::DataModel::IndexMapper > indexMapper=QSharedPointer< bb::cascades::DataModel::IndexMapper >(0))
virtual Q_SLOT voidonItemUpdated (QVariantList indexPath)
voidsetModel (bb::cascades::DataModel *model)
DataModel (QObject *parent=0)Inherited

Signals Index

voidmodelChanged ()
voiditemAdded (QVariantList indexPath)Inherited
voiditemMoved (QVariantList fromIndexPath, QVariantList toIndexPath)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

Properties

bb::cascades::DataModel model

The model to be decorated.

Since:

BlackBerry 10.2.0

Public Functions

DataModelDecorator (

Constructs a DataModelDecorator.

Parameters
parent

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

Since:

BlackBerry 10.2.0

virtual~DataModelDecorator ()

Destructor.

Since:

BlackBerry 10.2.0

virtual Q_INVOKABLE int childCount (

Calls the childCount() method of the DataModel being decorated.

Parameters
indexPath

The path to the data item to get the 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 (

Calls the data() method of the DataModel being decorated.

Parameters
indexPath

The path to the item in the model.

Return:

The data for this item.

Since:

BlackBerry 10.2.0

virtual Q_INVOKABLE bool hasChildren (

Calls the hasChildren() method of the DataModel being decorated.

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.

Since:

BlackBerry 10.2.0

virtual Q_INVOKABLE QString itemType (

Calls the itemType() method of the DataModel being decorated.

Parameters
indexPath

The path to the item in the model.

Return:

A string identifying the type for this item.

Since:

BlackBerry 10.2.0

bb::cascades::DataModel * model ()

Get the DataModel being decorated.

Return:

The DataModel being decorated.

Since:

BlackBerry 10.2.0

virtual Q_SLOT void onItemAdded (

Connect to the decorated model's itemAdded() signal and forward the signal.

Parameters
indexPath

The path to the item in the model.

Since:

BlackBerry 10.2.0

virtual Q_SLOT void onItemRemoved (

Connect to the decorated model's itemRemoved() signal and forward the signal.

Parameters
indexPath

The path to the item in the model.

Since:

BlackBerry 10.2.0

virtual Q_SLOT void onItemsChanged (

Connect to the decorated model's itemsChanged() signal and forward the signal.

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.

Here are some typical examples of when this signal is emitted:
  • the data has been sorted (so that many items have changed places)

  • the DataModel has been cleared (all items have been removed)

  • 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 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.2.0

virtual Q_SLOT void onItemUpdated (

Connect to the decorated model's itemUpdated() signal and forward the signal.

Parameters
indexPath

The path to the item in the model.

Since:

BlackBerry 10.2.0

void setModel (

Set the DataModel being decorated.

If the model has no parent, DataModelDecorator takes ownership of it and sets itself as parent to it. Any previously set DataModel is unaffected by this call, its parent won't change, and it won't be deleted as a result of calling setModel().

Parameters
model

The DataModel being decorated. Pointer must not be null.

Since:

BlackBerry 10.2.0

DataModel (Inherited

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

Signals

void modelChanged ()

This signal is emitted when the DataModel being decorated has changed.

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

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

Last modified: 2014-09-30



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

comments powered by Disqus