ArrayDataModel

Since: BlackBerry 10.0.0

#include <bb/cascades/ArrayDataModel>

Contains a list of QVariant values, typically for a ListView.

The ArrayDataModel is useful when you want to create a simple list of items and manipulate the order manually.

Items can be inserted or appended by passing a single QVariant item or a list of QVariant items. Values can be removed, replaced and swapped within bounds of the data model. When inserting a QVariant that contains a QObject* that does not have any parent, the data model will claim ownership of the QObject.

Example of how to use ArrayDataModel on a ListView in QML:

ListView {
    dataModel: ArrayDataModel {
        id: theDataModel
    }
    onCreationCompleted: {
        for ( var a = 0; a < 20; a++ ) {
            theDataModel.append("Item" + a);
        }
        theDataModel.append(["Appended 1", "Appended 2"]);
        theDataModel.removeAt(0);
        theDataModel.insert(0,["Prepended 1", "Prepended 2"]);
    }
}

Using an ArrayDataModel with a custom ListItemComponent

If you use an ArrayDataModel and want to use a custom ListItemComponent in your list, you need to keep in mind that ArrayDataModel::itemType() returns an empty string (""). To use a custom ListItemComponent in your list, you can implement your own itemType function (either on your custom ArrayDataModel or on the ListView itself), or set item="" in your &ListItemComponent. For more information about how to use a custom ListItemComponent with an ArrayDataModel, see "The default list visuals" section in ListView.


Overview

Inheritance

bb::cascades::DataModel
bb::cascades::ArrayDataModel

Public Functions Index

ArrayDataModel (QObject *parent=0)
ArrayDataModel (const QList< QVariant > &other, QObject *parent=0)
virtual ~ArrayDataModel ()
Q_SLOT voidappend (const QVariantList &values)
Q_SLOT voidappend (const QVariant &value)
virtual Q_INVOKABLE intchildCount (const QVariantList &indexPath)
Q_SLOT voidclear ()
virtual Q_INVOKABLE QVariantdata (const QVariantList &indexPath)
virtual Q_INVOKABLE boolhasChildren (const QVariantList &indexPath)
Q_INVOKABLE intindexOf (const QVariant &value, int from=0) const
Q_SLOT voidinsert (int i, const QVariantList &values)
Q_SLOT voidinsert (int i, const QVariant &value)
Q_INVOKABLE boolisEmpty () const
virtual Q_INVOKABLE QStringitemType (const QVariantList &indexPath)
Q_SLOT voidmove (int from, int to)
Q_SLOT voidremoveAt (int i)
Q_SLOT voidreplace (int i, const QVariant &value)
Q_INVOKABLE intsize () const
Q_SLOT voidswap (int i, int j)
Q_INVOKABLE QVariantvalue (int i) const
Q_INVOKABLE QVariantvalue (int i, const QVariant &defaultValue) const
DataModel (QObject *parent=0)Inherited

Signals Index

Only has inherited signals

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

Public Functions

ArrayDataModel (

Constructs an empty ArrayDataModel.

Parameters
parent

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

Since:

BlackBerry 10.0.0

ArrayDataModel (

Constructs an ArrayDataModel using the specified QVariantList.

Ownership of the QVariantList is transferred to the ArrayDataModel.

Parameters
other

The initial data to be used by the ArrayDataModel.

parent

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

Since:

BlackBerry 10.0.0

virtual~ArrayDataModel ()

Destructor.

Q_SLOT void append (

Inserts a list of values at the end of this model.

Parameters
values

The values to be appended. Ownership of QObject items that don't have parents is transferred to this ArrayDataModel.

Since:

BlackBerry 10.0.0

Q_SLOT void append (

Inserts a single value at the end of this model.

Parameters
value

The value to be appended. Ownership of QObject items that don't have parents is transferred to this ArrayDataModel.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE int childCount (

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

Parameters
indexPath

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

Return:

The number of children.

Since:

BlackBerry 10.0.0

Since:

BlackBerry 10.0.0

Q_SLOT void clear ()

Removes all values from this model.

QObjects owned by this model are deleted.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QVariant data (

Returns the data item that is associated with indexPath.

This function transfers ownership for QObject objects, if the returned object doesn't have any parent.

The ListView will pass the data item as a parameter to ListItemProvider::updateItem(). If item visuals are created by using ListItemComponent in QML, ListView makes the data returned from this function available in the item visuals as the context property ListItemData, and also as the property ListItem.data attached to the item visual root node.

Parameters
indexPath

The index path to the data item.

Return:

The data item associated with the indexPath. The caller must take ownership of any returned QObject objects, if the returned object doesn't already have a parent.

Since:

BlackBerry 10.0.0

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE bool hasChildren (

Indicates whether the data item specified by indexPath has children.

ListView never calls this function for its root node (but does call childCount(QVariantList) for the root node), so if this DataModel only contains one level of items (no child items), this function can always return false.

Here's an example of how to override hasChildren().

bool SmartViewModel::hasChildren(const QVariantList &indexPath)
{
    // Checks whether the indexPath is an empty array.
    // An empty array indicates the the index path is for the
    // root element.
    if(indexPath.empty())
        return true; // The root node always has children

    // ...Check for other index paths...
}
Parameters
indexPath

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

Since:

BlackBerry 10.0.0

Q_INVOKABLE int indexOf (

Searches this ArrayDataModel from the specified index position from until the specified item is found.

If no such item is found, -1 is returned.

Parameters
value

The QVariant to search for.

from

The index position to search from.

Return:

The index position if a matching item was found, -1 otherwise.

Since:

BlackBerry 10.0.0

Q_SLOT void insert (

Inserts a list of QVariant values at the specified index position i in this ArrayDataModel.

If i is 0, the values are prepended to the list. If i is size(), the values are appended to the list.

Parameters
i

The position in this ArrayDataModel to add the list of values.

values

The list of QVariant items to be inserted. Ownership of QObject items that don't have parents is transferred to this ArrayDataModel.

Since:

BlackBerry 10.0.0

Q_SLOT void insert (

Inserts a single QVariant value at the specified index position i in this ArrayDataModel.

If i is 0, the value is prepended to the list. If i is size(), the value is appended to the list.

Parameters
i

The position in this ArrayDataModel to add the value.

value

The QVariant value to be inserted. Ownership of QObject items that don't have parents is transferred to this ArrayDataModel.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool isEmpty ()

Indicates whether this ArrayDataModel is empty.

Return:

true if the model holds no values, false otherwise.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString itemType (

Returns the item type for the data item at indexPath.

The item type will then be used when the ListView requests items from its ListItemProvider. It will also be used when the DataModel has indicated that items have been updated using the signals DataModel::itemUpdated or DataModel::itemsChanged with DataModelChangeType::Update.

If a ListItemTypeMapper has been provided to a ListView, the ListView calls ListItemTypeMapper::itemType() instead of DataModel::itemType().

Parameters
indexPath

The index path to the data item.

Return:

A string representing the user-defined type of the item. The default implementation returns an empty string.

Since:

BlackBerry 10.0.0

Since:

BlackBerry 10.0.0

Q_SLOT void move (
  • intfrom,
  • intto )

Moves the value at one index position to another index position.

This function assumes that both the original position, from, and the destination position, to, are at least 0 and less than size(). If any of the positions are out of range, calling this function has no effect.

Parameters
from

The index position to move from.

to

The index position to move to.

Since:

BlackBerry 10.0.0

Q_SLOT void removeAt (
  • inti)

Removes the value at the specified index position i.

The index i must be at least 0 and less than size(). If the QObject at index position i is owned by this ArrayDataModel, the object is deleted. If the index is out of range, calling this function has no effect.

Parameters
i

The index of the value to be removed.

Since:

BlackBerry 10.0.0

Q_SLOT void replace (

Replaces the value at the specified index position i with the specified value.

If the previous value at this position is owned by this ArrayDataModel, the object is deleted.

The index i must be at least 0 and less than size(). If the index is out of range, this function has no effect.

Parameters
i

The index of the value to be replaced.

value

The replacement value. Ownership of QObject items that don't have parents is transferred to this ArrayDataModel.

Since:

BlackBerry 10.0.0

Q_INVOKABLE int size ()

Returns the number of values in this ArrayDataModel.

Return:

The number of values in this ArrayDataModel.

Since:

BlackBerry 10.0.0

Q_SLOT void swap (
  • inti,
  • intj )

Exchanges the value at index position i with the value at index position j.

This function assumes that both i and j are at least 0 and less than size(). If any of the indices are out of range, calling this function has no effect.

Parameters
i

The index of the first value.

j

The index of the second value.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariant value (
  • inti)

Returns the value at the specified index position i in this ArrayDataModel.

If index i is out of bounds (that is, if i is less than 0 or greater than size()), this function returns an invalid QVariant.

Parameters
i

The index of the value to be returned.

Return:

The value at index position i.

Since:

BlackBerry 10.0.0

Q_INVOKABLE QVariant value (

Returns the value at the specified index position i in this ArrayDataModel.

If index is out of bounds (that is, if i is less than 0 or greater than size()), this function returns defaultValue.

Parameters
i

The index of the value to be returned.

defaultValue

The value to be returned if i is out of bounds.

Return:

The value at index position i.

Since:

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

(Only has inherited signals)

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