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 merely 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 we want to reinterpret the data before it is used by ListView. For example, the itemType() method can return custom types depending on the contents of the data. Or custom data columns can be added based on existing data when the data() method is called.

DataModelDecorator can be used to insert data too. 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 - 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

onModelChanged: {}
onItemAddedInherited: {}
onItemRemovedInherited: {}
onItemsChangedInherited: {}
onItemUpdatedInherited: {}

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

If the model has no parent, the 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().

Since:

BlackBerry 10.2.0

Public Functions

DataModelDecorator (

Constructor.

Parameters
parent

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

Since:

BlackBerry 10.2.0

virtual~DataModelDecorator ()

Destructor.

Since:

BlackBerry 10.2.0

virtual Q_INVOKABLE int childCount (

Call the method childCount of the DataModel being decorated.

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 (

Call the method data 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 (

Call the method hasChildren 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 (

Call the method itemType 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.

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.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 model has no parent, the 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.

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

Signals

void modelChanged ()

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 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-03-13

comments powered by Disqus