DataQueryDecorator

Since: BlackBerry 10.2.0

#include <bb/cascades/datamanager/DataQueryDecorator>

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

A DataQuery wrapper that extends the behavior of existing queries.

To use this wrapper, override the processResults() or processHeaderResults() method(s) and modify the data prior to it being returned by the underlying query.

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

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

// ActionItem that deals with the Data Quality decorator,
// which decorates the list data with quality icons based
// on the quality field value.
ActionItem {
    ActionBar.placement: ActionBarPlacement.InOverflow
    onTriggered: {
        dm.load()
        listView.dataModel = dm
    }

    attachedObjects: [
        // An example to demonstrate how to use a DataQueryDecorator.
        // Notes:
        //  There are no DataQueryDecorator implementations in the library.
        //  This DataQualityDataQueryDecorator adds a reference to one of a set of images
        //  based on the quality field returned in the query data. See the list decorator
        //  sample app for the source code for this and other decorator classes.
        AsyncDataModel {
            id: dm
            query: DataQualityDataQueryDecorator {
                query: SqlDataQuery {
                    source: "sql/discogs_medium.db"
                    query: "select name, data_quality,primary_image from artist"
                    countQuery: "select count(*) from artist"
                    onDataChanged: console.log("data changed: revision=" + revision)
                    onError: console.log("SQL query error: " + code + ", " + message)
                }
            }
            onLoaded: console.log("initial model data is loaded")
        }
    ]
}


Overview

Inheritance

QML properties

query: bb::cascades::datamanager::DataQuery

QML signals

onDataChanged: {}
onQueryChanged: {}
onErrorInherited: {}

Public Functions Index

DataQueryDecorator (DataQuery *query, QObject *parent=0)
DataQueryDecorator (QObject *parent=0)
virtual ~DataQueryDecorator ()
virtual boolgetData (int offset, int limit, DataRevision *revision, int *totalCount, QList< DataItem > *results)
virtual boolgetDataForRevision (int offset, int limit, const DataRevision &requestedRevision, QList< DataItem > *results)
virtual boolgetHeaderData (int offset, int limit, DataRevision *revision, int *totalCount, QList< DataItem > *results, QList< HeaderDataItem > *headerResults)
bb::cascades::datamanager::DataQuery *query () const
voidsetQuery (bb::cascades::datamanager::DataQuery *query)
virtual QStringtoString () const
DataQuery (QObject *parent=0)Inherited
HeaderDataQuery (QObject *parent=0)Inherited

Protected Functions Index

virtual voidprocessHeaderResults (QList< HeaderDataItem > *headerResults)
virtual voidprocessResults (QList< DataItem > *results)

Signals Index

voiddataChanged (DataRevision revision)
voidqueryChanged ()
voiderror (int code, const QString &message)Inherited

Properties

bb::cascades::datamanager::DataQuery query

The query to be decorated.

Since:

BlackBerry 10.2.0

Public Functions

DataQueryDecorator (

Constructs a DataQueryDecorator given a DataQuery to decorate.

Parameters
query

The query to be decorated. This decorator takes ownership of the query.

parent

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

Since:

BlackBerry 10.2.0

DataQueryDecorator (

Constructs a DataQueryDecorator.

Parameters
parent

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

Since:

BlackBerry 10.2.0

virtual~DataQueryDecorator ()

Destructor.

Since:

BlackBerry 10.2.0

virtual bool getData (

Fetch the overall revision, total count, and a range of data items from the data source.

This is a synchronous call, but it must be possible to safely call this method from any thread. This method emits an error() signal if the data could not be successfully retrieved due to a query error, source not found, or other unexpected condition.

Parameters
offset

The index offset within the view.

limit

The number of items to retrieve.

revision

The current revision of the data source. The revision value must match the state of the data items that are returned. This pointer must not be null.

totalCount

The total number of items in the view. This pointer must not be null.

results

The list of data items which is the return data. This pointer must not be null.

Return:

True if the data is successfully retrieved, false otherwise.

Since:

BlackBerry 10.2.0

virtual bool getDataForRevision (

Fetch the data items from the data source if the data source is at the requested revision.

This is a synchronous call, but it must be possible to safely call this method from any thread. The error() signal is emitted for any database and query related errors only. The error() signal is not emitted if the data source doesn't match the requested revision; instead this method returns false.

Parameters
offset

The index offset within the view.

limit

The number of items to retrieve.

requestedRevision

The requested revision ID for the data source. If the data source doesn't match this revision, this method returns false.

results

The list of data items which is the return data. This pointer must not be null.

Return:

True if the data is successfully retrieved at the requested revision, false otherwise.

Since:

BlackBerry 10.2.0

virtual bool getHeaderData (

Fetch the overall revision, total count, all header items, and a range of data items from the data source.

This is a synchronous call, but it must be possible to safely call this method from any thread. This method emits an error() signal if the data could not be successfully retrieved.

Parameters
offset

The index offset within the view.

limit

The number of items to retrieve.

revision

The current revision of the data source. This pointer must not be null.

totalCount

The total number of items in the view. This pointer must not be null.

results

The requested items. This pointer must not be null.

headerResults

The header items of the query. This pointer must not be null.

Return:

True if the data is successfully retrieved, false otherwise.

Since:

BlackBerry 10.2.0

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

Get the delegate query.

Note that the query is owned by the decorator and is destroyed when the decorator is destroyed.

Return:

The query.

Since:

BlackBerry 10.2.0

void setQuery (

Set the query to be decorated.

Note that this decorator takes ownership of the query.

Parameters
query

The query to be decorated. This pointer must not be null.

Since:

BlackBerry 10.2.0

virtualQString toString ()

Get a string representation of the query, for debugging purposes.

Return:

The string.

Since:

BlackBerry 10.2.0

DataQuery (Inherited

Constructs a DataQuery.

Parameters
parent

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

Since:

BlackBerry 10.2.0

HeaderDataQuery (Inherited

Constructs a HeaderDataQuery.

Parameters
parent

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

Since:

BlackBerry 10.2.0

Protected Functions

virtual void processHeaderResults (

Override this function to modify the header data before its returned to the model.

Parameters
headerResults

The header items fetched by the query.

Since:

BlackBerry 10.2.0

virtual void processResults (

Override this function to modify the detail data before its returned to the model.

Parameters
results

The data items fetched by the query.

Since:

BlackBerry 10.2.0

Signals

void dataChanged (

This signal is emitted when the data changes.

Parameters
revision

The revision of the latest source data.

Since:

BlackBerry 10.2.0

void queryChanged ()

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

Since:

BlackBerry 10.2.0

void error (Inherited

Emitted when an error occurs when executing the query.

Parameters
code

The error code.

message

The error message.

Since:

BlackBerry 10.2.0

Last modified: 2014-09-30



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

comments powered by Disqus