GroupDataModel

Since: BlackBerry 10.0.0

#include <bb/cascades/GroupDataModel>

A data model to be used with a ListView.

A GroupDataModel represents an ordered map of QVariantMap objects and/or QObject* pointers, to be used as data for ListView.

Each item in this model is a QVariantMap or a QObject*. The items are ordered by comparing the values of a specified list of keys (property names) in all of the items. The keys are specified on the property sortingKeys. Values are compared in the same order as the keys appear in the sortingKeys list (for example in a contacts list: compare contact last names if first names are equal). If an item in a GroupDataModel lacks the key found first in sortingKeys, or if the value for that key is an empty string, the remaining keys are shifted up in priority until a usable key is found. Example: if sortingKeys = [firstName, lastName, date], and item A and B are compared where A has both firstName and lastName but B only has lastName, the lastName of B would be compared to firstName of A when sorting them. If the lastName of B is equal to the firstName of A the dates would then be compared, since the next property comparison always starts with an equal number of keys skipped for both items. Values of different types are never compared.

The key in a QVariantMap is always of the type QString. For QObject property names, QString::toLatin1() is called for the sorting keys. The value used for sorting must be of the same type in all items in GroupDataModel (for that specific key, different keys can have different value types). The GroupDataModel can sort items, using all of these QVariant types:

Char, Date, DateTime, Double, Int, LongLong, String, Time, UInt, ULongLong, Url.

Items can be automatically grouped, with a header for each group. When grouping is active (when grouping is set to ItemGrouping::ByFirstChar or ItemGrouping::ByFullValue), only headers are found on the first level of items in the GroupDataModel (first level = items for which the index path is a single index). The non-header items are then children to headers, which means that the non-header items are second level items (have index paths containing two indexes).

Normally grouping is done by exact comparison of values. But if the values are QString, grouping can be done by only comparing (case insensitive) the first QChar in every QString. This behavior is controlled by the grouping property.

For the headers, GroupDataModel::data() returns a QVariant containing the value that all children of that header have in common. In the illustration below, GroupDataModel::data() has returned a QVariant containing the QString "A" for the first header, "B" for the second header, and so on.

A list of names sorted by the first letter

The function GroupDataModel::itemType() returns GroupDataModel::Header ("header") for header items and GroupDataModel::Item ("item") for all other items. The example code below shows how a list like the one in the illustration above can be declared in QML, by having one ListItemComponent for "header" and one for "item". Also note that ListItemData is a QString (there's no properties on it) for headers, but a QVariantMap (with QString properties "firstName" and "lastName") for other items. In this example, the GroupDataModel is assumed to be filled with QVariantMap items from C++.

ListView {
    dataModel: GroupDataModel {
        id: theModel
        sortingKeys: ["firstName", "lastName"]
    }
    listItemComponents: [
        ListItemComponent {
            type: "header"
            
            Header {
                title: ListItemData
            }
        },

        ListItemComponent {
            type: "item"

            StandardListItem {
                title: ListItemData.firstName + ' ' + ListItemData.lastName
            }
        }
    ]
}

When specifying a certain item in the model (for example as argument to the function GroupDataModel::data(), or the returned value from functions like GroupDataModel::find()), index paths are used. 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. 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, etc.

See Index paths for more information.

Here's an example of how to create a GroupDataModel with a QVariantMap, and use it in a ListView:

GroupDataModel *model = new GroupDataModel(QStringList() << "country" << "continent");

QVariantMap map;
map["country"] = "Italy"; map["continent"] = "Europe"; model->insert(map);
map["country"] = "Japan"; map["continent"] = "Asia"; model->insert(map);
map["country"] = "Egypt"; map["continent"] = "Africa"; model->insert(map);

ListView *listView = new ListView();
listView->setDataModel(model);

And here's an implementation of a ListItemProvider that could use the GroupDataModel defined in the example above:

class GroupListItemManager : public ListItemProvider
{
public:
    VisualNode * createItem(ListView* list, QString type)
    {
        Q_UNUSED(list);

        if (type.compare(GroupDataModel::Header) == 0) {
            return new Header();
        } else {
            return new StandardListItem();
        }
    }

    void updateItem(ListView* list, VisualNode *control, QString type,
        QVariantList indexPath, QVariant data)
    {
        Q_UNUSED(list);
        Q_UNUSED(indexPath);

        if (type.compare(GroupDataModel::Header) == 0) {
            QString caption = data.value<QString>();
            static_cast<Header*>(control)->setTitle(caption);
        } else {
            QVariantMap map = data.value<QVariantMap>();
            static_cast<StandardListItem*>(control)->setTitle(QString("%1, %2").arg(
                map["country"].toString(), map["continent"].toString()));
        }
    }
};

GroupDataModel also supports the use of QObject* pointers. Here's an example of a QObject subclass called Person. It contains first name and last name properties, both of which could be displayed in a list item.

class Person : public QObject {
    Q_OBJECT

    Q_PROPERTY(QString firstName READ firstName WRITE setFirstName NOTIFY firstNameChanged FINAL)
    Q_PROPERTY(QString lastName READ lastName WRITE setLastName NOTIFY lastNameChanged FINAL)

public:
    Person(QObject *parent = 0) : QObject(parent) {}

    Person(QString firstname, QString lastname)
        : QObject(), m_firstName(firstname), m_lastName(lastname)
    {
    }

    QString firstName() const {
        return m_firstName;
    }

    QString lastName() const{
        return m_lastName;
    }

    void setFirstName(QString newName) {
        if ( newName != m_firstName ) {
            m_firstName = newName;
            emit firstNameChanged(newName);
        }
    }

    void setLastName(QString newName) {
        if ( newName != m_lastName ) {
            m_lastName = newName;
            emit lastNameChanged(newName);
        }
    }

Q_SIGNALS:
    void firstNameChanged(QString firstName);
    void lastNameChanged(QString lastName);

private:
    QString m_firstName;
    QString m_lastName;

    Q_DISABLE_COPY(Person)
};

This is how Person objects can be created and added to the GroupDataModel.

GroupDataModel *model = new GroupDataModel(QStringList() << "firstName" << "lastName");

model->insert(new Person ("Wes", "Barichak"));
model->insert(new Person ("Mike", "Chepesky"));


Overview

Inheritance

bb::cascades::DataModel
bb::cascades::GroupDataModel

QML properties

grouping: bb::cascades::ItemGrouping::Type
sortedAscending: bool
sortingKeys: QStringList

Public Static Attributes Index

Public Functions Index

GroupDataModel (QObject *parent=0)
GroupDataModel (const QStringList &keys, QObject *parent=0)
GroupDataModel (const QList< QVariantMap > &initialItems, const QStringList &keys, QObject *parent=0)
virtual ~GroupDataModel ()
Q_INVOKABLE QVariantListafter (const QVariantList &indexPath) const
Q_INVOKABLE QVariantListbefore (const QVariantList &indexPath) const
virtual intchildCount (const QVariantList &indexPath)
Q_SLOT voidclear ()
virtual QVariantdata (const QVariantList &indexPath)
Q_INVOKABLE QVariantListfind (const QVariantList &values) const
Q_INVOKABLE QVariantListfind (QObject *object) const
Q_INVOKABLE QVariantListfind (const QVariantMap &matchMap) const
Q_INVOKABLE QVariantListfindExact (QObject *object) const
Q_INVOKABLE QVariantListfindExact (const QVariantMap &matchMap) const
Q_INVOKABLE QVariantListfirst () const
bb::cascades::ItemGrouping::Typegrouping () const
virtual boolhasChildren (const QVariantList &indexPath)
Q_SLOT voidinsert (QObject *object)
Q_SLOT voidinsert (const QVariantMap &item)
Q_SLOT voidinsertList (const QVariantList &items)
Q_INVOKABLE voidinsertList (const QList< QVariantMap > &items)
voidinsertList (const QList< QObject * > &items)
Q_INVOKABLE boolisEmpty () const
boolisSortedAscending () const
virtual QStringitemType (const QVariantList &indexPath)
Q_INVOKABLE QVariantListlast () const
Q_INVOKABLE QVariantListlowerBound (const QVariantList &values) const
Q_INVOKABLE QVariantListlowerBound (QObject *object) const
Q_INVOKABLE QVariantListlowerBound (const QVariantMap &matchMap) const
Q_SLOT boolremove (QObject *object)
Q_SLOT boolremove (const QVariantMap &item)
Q_SLOT boolremoveAt (const QVariantList &indexPath)
Q_SLOT voidsetGrouping (bb::cascades::ItemGrouping::Type itemGrouping)
Q_SLOT voidsetSortedAscending (bool ascending)
Q_SLOT voidsetSortingKeys (const QStringList &keys)
Q_INVOKABLE intsize () const
QStringListsortingKeys () const
QList< QVariantMap >toListOfMaps () const
QList< QObject * >toListOfObjects () const
Q_SLOT boolupdateItem (const QVariantList &indexPath, QObject *object)
Q_SLOT boolupdateItem (const QVariantList &indexPath, const QVariantMap &item)
Q_INVOKABLE QVariantListupperBound (const QVariantList &values) const
Q_INVOKABLE QVariantListupperBound (QObject *object) const
Q_INVOKABLE QVariantListupperBound (const QVariantMap &matchMap) const
DataModel (QObject *parent=0)Inherited

Signals Index

voidgroupingChanged (bb::cascades::ItemGrouping::Type newGrouping)
voidsortedAscendingChanged (bool sortedAscending)
voidsortingKeysChanged (QStringList sortingKeys)
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::ItemGrouping::Type grouping

Determines if and how items are grouped together.

Since:

BlackBerry 10.0.0

bool sortedAscending

Determines the order in which items are sorted in this GroupDataModel.

If true, items are sorted in ascending order. If false, items are sorted in descending order. The default value is true.

Since:

BlackBerry 10.0.0

QStringList sortingKeys

The sorting keys that are used for this GroupDataModel.

Item QVariantMap objects and QObject* pointers in this GroupDataModel are sorted by their values for these keys, in the order they appear on this property. Values for the second key are only compared if values for the first key are equal, etc. If an item in this GroupDataModel lacks the key found first in sortingKeys, or if the value for that key is an empty string, the remaining keys are shifted up in priority until a usable key is found.

Since:

BlackBerry 10.0.0

Public Static Attributes

const QString Header ()

The string "header", which is returned by itemType() for header items.

Since:

BlackBerry 10.0.0

const QString Item ()

The string "item", which is returned by itemType() for non-header items.

Since:

BlackBerry 10.0.0

Public Functions

GroupDataModel (

Constructs an empty GroupDataModel.

Parameters
parent

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

Since:

BlackBerry 10.0.0

GroupDataModel (

Constructs an empty GroupDataModel with the specified sorting keys.

GroupDataModel *model = new GroupDataModel(QStringList() << "firstName" << "lastName");
Parameters
keys

A QStringList of sorting keys.

parent

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

Since:

BlackBerry 10.0.0

GroupDataModel (

Constructs a GroupDataModel containing the provided QVariantMap items.

Also specifies which keys to sort the items by.

GroupDataModel *model = new GroupDataModel(items, keys);
Parameters
initialItems

A list of items that the GroupDataModel should contain. GroupDataModel does not take ownership of any content.

keys

A QStringList of sorting keys.

parent

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

Since:

BlackBerry 10.0.0

virtual~GroupDataModel ()

Destructor.

Q_INVOKABLE QVariantList after (

Returns an index path to the item placed after the specified one.

Headers are ignored. The order is decided by current sorting settings.

Useful when iterating through the items in this GroupDataModel.

Example:

for ( QVariantList indexPath = model->first(); !indexPath.isEmpty();
    indexPath = model->after(indexPath) )
{
    QVariant item = model->data(indexPath);
    // Do something with the item here.
}
Parameters
indexPath

An index path specifying the item right before the requested one (ignoring headers). See Index paths for more information.

Return:

An index path to the item placed after the one specified by indexPath, ignoring headers. Or an empty QVariantList if no such item exists.

See also:

first(), last(), before()

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList before (

Returns an index path to the item placed before the specified one.

Headers are ignored. The order is decided by current sorting settings.

Useful when iterating through the items in this GroupDataModel.

Example:

for ( QVariantList indexPath = model->last(); !indexPath.isEmpty();
    indexPath = model->before(indexPath) )
{
    QVariant item = model->data(indexPath);
    // Do something with the item here.
}
Parameters
indexPath

An index path specifying the item right after the requested one (ignoring headers). See Index paths for more information.

Return:

An index path to the item placed before the one specified by indexPath, ignoring headers. Or an empty QVariantList if no such item exists.

See also:

first(), last(), after()

Since:

BlackBerry 10.0.0

virtual 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) in a GroupDataModel:

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

The path to the data item to get child count for. See Index paths for more information.

Return:

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

Since:

BlackBerry 10.0.0

Q_SLOT void clear ()

Removes all items from this GroupDataModel.

Destroys all items of type QObject* that this GroupDataModel owns (is parent of).

Emits DataModel::itemsChanged().

Since:

BlackBerry 10.0.0

virtualQVariant 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. See Index paths for more information.

Return:

A QVariantMap or QObject* (one of those inserted into this model) wrapped in a QVariant, or QVariant::Invalid if the argument indexPath is invalid.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList find (

Finds the index path for the first item in this GroupDataModel with property values matching the supplied ones.

If the number of values supplied to this function is less than the number of keys in GroupDataModel::sortingKeys, items that have values for all sortingKeys won't be found by this function. For example, if sortingKeys = ["firstName", "lastName"], no item that has values for both "firstName" and "lastName" can be found by calling this function with a single value as argument. For use cases like that, lowerBound() should be called instead.

Parameters
values

The search aims to find an item for which the values of the properties specified by GroupDataModel::sortingKeys equals these values. If an item in this GroupDataModel lacks one of the keys, or if the value for that key is an empty string, any remaining keys are shifted up in priority until a usable key is found.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList find (

Finds the index path for the first item in this GroupDataModel that matches the supplied QObject*.

Parameters
object

The search aims to find an item that according to current sorting settings (the property GroupDataModel::sortingKeys) is equal to object.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList find (

Finds the index path for the first item in this GroupDataModel* that matches the supplied QVariantMap.

Parameters
matchMap

The search aims to find an item that according to current sorting settings (the property GroupDataModel::sortingKeys) is equal to matchMap.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList findExact (

Finds the index path for the first occurrence of the supplied object in this GroupDataModel.

Parameters
object

The object to find. The search aims to find this exact object instance, and not just an object with the same property values.

Return:

If no item containing object is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList findExact (

Finds the index path for the first item in this GroupDataModel that is == matchMap.

Parameters
matchMap

The search aims to find an item that returns true when doing a == comparison to matchMap. Which means that all properties must have exactly the same values on the two maps, not only the properties defined by GroupDataModel::sortingKeys.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList first ()

Returns an index path to the first item.

Useful when iterating through the items in this GroupDataModel.

Example:

for ( QVariantList indexPath = model->first(); !indexPath.isEmpty();
    indexPath = model->after(indexPath) )
{
    QVariant item = model->data(indexPath);
    // Do something with the item here.
}
Return:

An index path to the item placed first according to current sorting settings (ignoring header items). Possible values are [0] (if headers are disabled), [0, 0] (if headers are enabled) or an empty QVariantList if this GroupDataModel is empty. See Index paths for more information.

See also:

last(), before(), after()

Since:

BlackBerry 10.0.0

bb::cascades::ItemGrouping::Type grouping ()

Gets the current value of GroupDataModel::grouping.

Return:

The current value of the property grouping.

See also:

setGrouping()

Since:

BlackBerry 10.0.0

virtual 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. See Index paths for more information.

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

Q_SLOT void insert (

Inserts a QObject* into the GroupDataModel.

GroupDataModel listens to changes in the object properties defined by GroupDataModel::sortingKeys, if the object emits notification-signals for them. GroupDataModel emits the DataModel::itemUpdated() signal when needed, and moves items if changes in their property values affect the sorting order.

Parameters
object

QObject* to be inserted. If object has no parent, this GroupDataModel takes ownership of it. Otherwise the caller must ensure that object stays alive for as long as this GroupDataModel is alive. Must not be 0, but the same object can be inserted more than once.

Since:

BlackBerry 10.0.0

Q_SLOT void insert (

Inserts a QVariantMap into the GroupDataModel.

Parameters
item

QVariantMap to be inserted. Ownership of the content in item is not transferred to GroupDataModel.

Since:

BlackBerry 10.0.0

Q_SLOT void insertList (

Inserts a QVariantList into the GroupDataModel.

The items of the list are QVariants which contain either a QVariantMap or QObject*. The two types cannot be mixed in the same list.

Parameters
items

Either a list of QVariantMap or list of QObject* to be inserted. Ownership of the content of QVariantMaps is not transferred to GroupDataModel. If QObject* items have no parent, this GroupDataModel takes ownership of those items.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void insertList (

Inserts a list of QVariantMap into the GroupDataModel.

Parameters
items

List of QVariantMap to be inserted. Ownership of the content in each item is not transferred to GroupDataModel.

Since:

BlackBerry 10.0.0

void insertList (

Inserts a list of QObject* into the GroupDataModel.

Parameters
items

List of QObject* to be inserted. If an object has no parent, this GroupDataModel takes ownership of it. Otherwise the caller must ensure that object stays alive for as long as this GroupDataModel is alive. Must not be 0, but the same object can be inserted more than once.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool isEmpty ()

Checks if the GroupDataModel is empty.

Return:

true if the model doesn't contain any items, false otherwise.

Since:

BlackBerry 10.0.0

bool isSortedAscending ()

Gets the current value of GroupDataModel::sortedAscending.

Return:

true if items are sorted in ascending order, false if items are sorted in descending order.

Since:

BlackBerry 10.0.0

virtualQString itemType (

Returns the type for the specified item.

Parameters
indexPath

The path to the item in the model. See Index paths for more information.

Return:

GroupDataModel::Header for any headers and GroupDataModel::Item for the actual items.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList last ()

Returns an index path to the last item.

Useful when iterating through the items in this GroupDataModel.

Example:

for ( QVariantList indexPath = model->last(); !indexPath.isEmpty();
    indexPath = model->before(indexPath) )
{
    QVariant item = model->data(indexPath);
    // Do something with the item here.
}
Return:

An index path to the item placed last according to current sorting settings (ignoring header items). Returns an empty QVariantList if this GroupDataModel is empty. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList lowerBound (

Finds the index path for the first item in this GroupDataModel that would not have been placed before an item having the supplied property values (which means that the found item might have property values identical to the supplied ones).

Example showing how to in a ListView using a GroupDataModel scroll to the first item that has a value starting with the letter "M", or any letter after "M" if no such item is found in the GroupDataModel.

listView->scrollToItem(model->lowerBound(QVariantList() << "M");
Parameters
values

The search aims to find the first item for which the values of the properties specified by GroupDataModel::sortingKeys would cause it to be placed after an item having these values on the same properties. If an item in this GroupDataModel lacks the specified key, or if the value for that key is an empty string, any remaining keys are shifted up in priority until a usable key is found.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList lowerBound (

Finds the first item in this GroupDataModel that would not have been placed before the supplied one (which means that the found item might be identical to the supplied one).

Example showing how to get the index path for the first item in the GroupDataModel "model" that will be pushed down in the list if the QObject* "newItem" is inserted into the model.

QVariantList() firstPushedDown = model->lowerBound(newItem);
Parameters
object

The search aims to find the first item in this GroupDataModel that would not have been placed before object, using the current sorting settings on this GroupDataModel.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList lowerBound (

Finds the first item in this GroupDataModel that would not have been placed before the supplied one (which means that the found item might be identical to the supplied one).

Example showing how to get the index path for the first item in the GroupDataModel "model" that will be pushed down in the list if the QVariantMap "newItem" is inserted into the model.

QVariantList() firstPushedDown = model->lowerBound(newItem);
Parameters
matchMap

The search aims to find the first item in this GroupDataModel that would not have been placed before matchMap, using the current sorting settings on this GroupDataModel.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_SLOT bool remove (

Removes the first item found in this GroupDataModel that is identical (as described in findExact()) to the supplied item.

Emits the signal DataModel::itemRemoved() if an item is successfully removed.

Parameters
object

Item to remove. If this GroupDataModel owns (is parent of) object and there is only one item in this GroupDataModel containing object, then object is destroyed.

Return:

true if an item was removed, false otherwise.

Since:

BlackBerry 10.0.0

Q_SLOT bool remove (

Removes the first item found in this GroupDataModel that is identical (as described in findExact()) to the supplied item.

Emits the signal DataModel::itemRemoved() if an item is successfully removed.

Parameters
item

Item to remove.

Return:

true if an item was removed.

Since:

BlackBerry 10.0.0

Q_SLOT bool removeAt (

Removes the item specified by the index path.

Trying to remove a header has no effect.

Emits the signal DataModel::itemRemoved() if an item is successfully removed.

If the item to remove contains a QObject* that GroupDataModel owns (is parent of) and there is only one item in this GroupDataModel containing that object, then that object is destroyed.

Parameters
indexPath

The index path for the item to remove. See Index paths for more information.

Return:

true if an item was removed, false otherwise

Since:

BlackBerry 10.0.0

Q_SLOT void setGrouping (

Sets the value of GroupDataModel::grouping.

Emits the signal groupingChanged() if the new property value differs from the old one.

Parameters
itemGrouping

The new value for the property grouping.

See also:

grouping()

Since:

BlackBerry 10.0.0

Q_SLOT void setSortedAscending (
  • boolascending)

Sets the value of GroupDataModel::sortedAscending.

Emits the signal sortedAscendingChanged() if the new property value differs from the old one.

Parameters
ascending

true if items should be sorted in ascending order, false if items should be sorted in descending order.

Since:

BlackBerry 10.0.0

Q_SLOT void setSortingKeys (

Sets the value of GroupDataModel::sortingKeys.

Emits the signal sortingKeysChanged() if the new property value differs from the old one.

If an item in this GroupDataModel lacks the specified key, or if the value for that key is an empty string, any remaining keys are shifted up in priority until a usable key is found. This behavior happens in all internal item comparison in GroupDataModel.

Parameters
keys

Items (QVariantMap and/or QObject*) in this GroupDataModel are sorted by their values for these keys.

See also:

sortingKeys()

Since:

BlackBerry 10.0.0

Q_INVOKABLE int size ()

Returns the number of items in this GroupDataModel.

In case headers are enabled, the number of headers are excluded from the result.

Return:

Number of (non-header) items in this GroupDataModel.

Since:

BlackBerry 10.0.0

QStringList sortingKeys ()

Gets the value of GroupDataModel::sortingKeys.

Return:

A list of the keys specified for sorting, in the order they are used.

Since:

BlackBerry 10.0.0

QList< QVariantMap > toListOfMaps ()

Returns a list of all QVariantMap objects contained by this GroupDataModel, in current sorting order.

The QObject* items are returned as QVariantMap objects containing property values for the keys specified by GroupDataModel::sortingKeys.

Return:

A list containing all items (except headers).

Since:

BlackBerry 10.0.0

QList< QObject * > toListOfObjects ()

Returns a list of all QObject* pointers contained by this GroupDataModel, in current sorting order.

The value for QVariantMap items is 0. The ownership of item objects is not changed by this function (any objects owned by this GroupDataModel remain owned by this GroupDataModel even if the objects are included in the list returned by this function).

Return:

A list containing all items (except headers).

Since:

BlackBerry 10.0.0

Q_SLOT bool updateItem (

Replaces the item on the specified index path with the supplied QObject*.

Causes the GroupDataModel to either emit the signal DataModel::itemUpdated() (if the item wasn't updated in a way that caused it to change position) or to first emit DataModel::itemRemoved() and then DataModel::itemAdded().

If the existing item contains a QObject* that GroupDataModel owns (is parent of) and there is only one item in this GroupDataModel containing that object, then that object is destroyed.

Parameters
indexPath

Index path for the item that is to be updated. See Index paths for more information.

object

A QObject* that is to replace the existing one on indexPath. If the supplied object doesn't have a parent, then this GroupDataModel takes ownership of it. Which means that the object is destroyed when no longer needed by this GroupDataModel.

Return:

true if the item was successfully updated, false if indexPath is invalid.

Since:

BlackBerry 10.0.0

Q_SLOT bool updateItem (

Replaces the item on the specified index path with the supplied QVariantMap.

Causes the GroupDataModel to either emit the signal DataModel::itemUpdated() (if the item wasn't updated in a way that caused it to change position) or to first emit DataModel::itemRemoved() and then DataModel::itemAdded().

If the existing item contains a QObject* that GroupDataModel owns (is parent of) and there is only one item in this GroupDataModel containing that object, then that object is destroyed.

Parameters
indexPath

Index path for the item that is to be updated. See Index paths for more information.

item

A QVariantMap that is to replace the existing one on indexPath.

Return:

true if the item was successfully updated, false if indexPath is invalid.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList upperBound (

Finds the first item in this GroupDataModel that would not have been placed before an item having the supplied property values, and also doesn't have property values identical to the supplied ones.

Example showing how to iterate through all items in the GroupDataModel "model" having the values "Tom" and "Hanks" for the keys specified by GroupDataModel::sortingKeys:

QVariantList endIndexPath = model->upperBound(QVariantList() << "Tom" << "Hanks");

for ( QVariantList indexPath = model->lowerBound(QVariantList() << "Tom" << "Hanks");
    indexPath != endIndexPath; indexPath = model->after(indexPath) )
{
    QVariant item = model->data(indexPath);
    // Do something with the item here.
}
Parameters
values

The search aims to find the first item for which the values of the properties specified by GroupDataModel::sortingKeys are not identical to the supplied ones and would cause the item to be placed after an item having these values on the same properties. If an item in this GroupDataModel lacks the specified key, or if the value for that key is an empty string, any remaining keys are shifted up in priority until a usable key is found.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList upperBound (

Finds the first item in this GroupDataModel that would not have been placed before the supplied one, and also doesn't have identical property values for the sorting keys.

Example showing how to iterate through all items in the GroupDataModel "model" having the same values as the QObject* "myItem" for the keys specified by GroupDataModel::sortingKeys:

QVariantList endIndexPath = model->upperBound(myItem);

for ( QVariantList indexPath = model->lowerBound(myItem);
    indexPath != endIndexPath; indexPath = model->after(indexPath) )
{
    QVariant item = model->data(indexPath);
    // Do something with the item here.
}
Parameters
object

The search aims to find the first item in this GroupDataModel that would not have been placed before object (and also is not considered equal), using the current sorting settings on this GroupDataModel.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariantList upperBound (

Finds the first item in this GroupDataModel that would not have been placed before the supplied one, and also doesn't have identical property values for the sorting keys.

Example showing how to iterate through all items in the GroupDataModel "model" having the same values as the QVariantMap "myItem" for the keys specified by GroupDataModel::sortingKeys:

QVariantList endIndexPath = model->upperBound(myItem);

for ( QVariantList indexPath = model->lowerBound(myItem);
    indexPath != endIndexPath; indexPath = model->after(indexPath) )
{
    QVariant item = model->data(indexPath);
    // Do something with the item here.
}
Parameters
matchMap

The search aims to find the first item in this GroupDataModel that would not have been placed before matchMap (and also is not considered equal), using the current sorting settings on this GroupDataModel.

Return:

If no item matching the arguments is found, an empty QVariantList is returned. Otherwise an index path for a valid item (not a header) is returned. See Index paths for more information.

Since:

BlackBerry 10.0.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 groupingChanged (

Emitted when GroupDataModel::grouping is changed.

Parameters
newGrouping

The new value for GroupDataModel::grouping.

Since:

BlackBerry 10.0.0

void sortedAscendingChanged (
  • boolsortedAscending)

Emitted when GroupDataModel::sortedAscending is changed.

Parameters
sortedAscending

true if items now will be sorted in ascending order, false if items now will be sorted in descending order.

Since:

BlackBerry 10.0.0

void sortingKeysChanged (

Emitted when GroupDataModel::sortingKeys is changed.

Parameters
sortingKeys

The new keys to sort items by.

Since:

BlackBerry 10.0.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.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-06-24



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

comments powered by Disqus