QListDataModel

Since: BlackBerry 10.0.0

#include <bb/cascades/QListDataModel>

Contains a list of <Item> values, typically for a ListView.

The templated QListDataModel Model class implements the abstract DataModel class.

Template class <Item> must be convertible to QVariant in order for the data() function to work. To accomplish that, use the Q_DECLARE_METATYPE macro. For example:

namespace mynamespace {
class Contact {
...
}
} // mynamespace
Q_DECLARE_METATYPE( mynamespace::Contact *);

Then the custom object (pointer to Contact) would become convertible to and from QVariant:

Contact *pCnt1 = new Contact();
QVariant q = QVariant::fromValue(pCnt1);
Contact *pCnt2 = q.value<Contact*>();

And usable in the model: QListDataModel<Contact *> contactsModel;

Similarly, Contacts objects (not pointers) can be declared and stored in the model.

As a convenience, QListDataModel includes the following typedefs: QVariantListDataModel, QStringListDataModel, and QMapListDataModel. For more information about these typedefs, see bb::cascades.

Overview

Inheritance

bb::cascades::DataModel
	bb::cascades::QListDataModel

Public Functions Index

	QListDataModel ()
	QListDataModel (const QList< Item > &other)
virtual	~QListDataModel ()
void	append (const Item &value)
void	append (const QList< Item > &values)
virtual int	childCount (const QVariantList &indexPath)
void	clear ()
virtual QVariant	data (const QVariantList &indexPath)
virtual bool	hasChildren (const QVariantList &indexPath)
int	indexOf (const Item &value, int from=0) const
void	insert (int i, const Item &value)
void	insert (int i, const QList< Item > &values)
bool	isEmpty () const
virtual QString	itemType (const QVariantList &indexPath)
void	move (int from, int to)
QListDataModel &	operator<< (const Item &value)
void	removeAt (int i)
void	replace (int i, const Item &value)
int	size () const
void	swap (int i, int j)
Item	value (int i) const
Item	value (int i, const Item &defaultValue) const
	DataModel (QObject *parent=0)

Signals Index

Only has inherited signals

void	itemAdded (QVariantList indexPath)
void	itemRemoved (QVariantList indexPath)
void	itemsChanged (bb::cascades::DataModelChangeType::Type eChangeType=bb::cascades::DataModelChangeType::Init, QSharedPointer< bb::cascades::DataModel::IndexMapper > indexMapper=QSharedPointer< bb::cascades::DataModel::IndexMapper >(0))
void	itemUpdated (QVariantList indexPath)

Public Functions

QListDataModel ()

Constructs an empty QListDataModel.

Since:

BlackBerry 10.0.0

QListDataModel (
const QList< Item > &other)

Constructs a QListDataModel holding the provided QVariantList.

Ownership of the specified QVariantList is transferred to this QListDataModel.

Parameters
other	The initial data to be used by this QListDataModel.

Since:

BlackBerry 10.0.0

virtual~QListDataModel ()

Destructor.

void append (
const Item &value)

Inserts the specified value at the end of this model.

The value must be convertible to a QVariant.

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

Since:

BlackBerry 10.0.0

void append (
const QList< Item > &values)

Inserts the specified list of values at the end of this QListDataModel.

Each Item in the list must be convertible to a QVariant.

Parameters
values	The list of QVariant items to be appended. Ownership of QObject items that don't have parents is transferred to this QListDataModel.

Since:

BlackBerry 10.0.0

virtual int childCount (
const QVariantList &indexPath)

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

void clear ()

Removes all values from this model.

QObjects owned by this model are deleted.

Since:

BlackBerry 10.0.0

virtualQVariant data (
const QVariantList &indexPath)

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.

virtual bool hasChildren (
const QVariantList &indexPath)

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

int indexOf (
const Item &value,
intfrom )

Searches this QListDataModel 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

void insert (
inti,
const Item &value )

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

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 QListDataModel to add the value.
value	The QVariant value to be inserted. Ownership of QObject items that don't have parents is transferred to this QListDataModel.

Since:

BlackBerry 10.0.0

void insert (
inti,
const QList< Item > &values )

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

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

Since:

BlackBerry 10.0.0

bool isEmpty ()

Indicates whether this QListDataModel is empty.

Return:

true if the model holds no values, false otherwise.

Since:

BlackBerry 10.0.0

virtualQString itemType (
const QVariantList &indexPath)

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

void move (
intfrom,
intto )

Moves the value at index position from to index position to.

This assumes that both from and to are at least 0 and less than size().

Parameters
from	Index position to move from.
to	Index position to move to.

Since:

BlackBerry 10.0.0

QListDataModel & operator<< (
const Item &value)

Appends the specified value to the QListDataModel and returns a reference to the QListDataModel.

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

Return:

A reference to the QListDataModel.

Since:

BlackBerry 10.0.0

void removeAt (
inti)

Removes the value at index position i.

i must be at least 0 and less than size(). QObjects owned by the model are deleted.

Parameters
i	Index of value to be removed.

Since:

BlackBerry 10.0.0

void replace (
inti,
const Item &value )

Replaces the value at index position i with value.

If the old value is owned by QListDataModel, it will be deleted.

i must be at least 0 and less than size().

Parameters
i	Index of value to be replaced.
value	Replacement value. Ownership of parentless QObjects is transferred to QListDataModel.

Since:

BlackBerry 10.0.0

int size ()

Returns the number of values in the QListDataModel.

Return:

Number of values in the QListDataModel.

Since:

BlackBerry 10.0.0

void swap (
inti,
intj )

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

The function assumes that both i and j are at least 0 and less than size().

Parameters
i	Index of first value.
j	Index of second value.

Since:

BlackBerry 10.0.0

Item value (
inti)

Returns the value at index position i in the QListIndexModel.

If index i is out of bounds, the function returns a default-constructed value.

Parameters
i	Index of value to be returned.

Return:

Value at index position i.

Since:

BlackBerry 10.0.0

Item value (
inti,
const Item &defaultValue )

Returns the value at index position i in the QListIndexModel.

If index i is not at least 0 and less than size(), the function returns defaultValue.

Parameters
i	Index of value to be returned.
defaultValue	Value to be returned if i is out of bounds.

Return:

Value at index position i.

Since:

BlackBerry 10.0.0

DataModel (
QObject *parent)

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

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

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 (
bb::cascades::DataModelChangeType::TypeeChangeType,
QSharedPointer< bb::cascades::DataModel::IndexMapper >indexMapper )

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

Emitted when a data item in this DataModel has been updated.

Parameters
indexPath	IndexPath to the updated item.

Since:

BlackBerry 10.0.0

QListDataModel

Overview

Inheritance

Public Functions Index

Signals Index

Public Functions

QListDataModel ()

QListDataModel (
const QList< Item > &other)

virtual~QListDataModel ()

void append (
const Item &value)

void append (
const QList< Item > &values)

virtual int childCount (
const QVariantList &indexPath)

void clear ()

virtualQVariant data (
const QVariantList &indexPath)

virtual bool hasChildren (
const QVariantList &indexPath)

int indexOf (
const Item &value,
intfrom )

void insert (
inti,
const Item &value )

void insert (
inti,
const QList< Item > &values )

bool isEmpty ()

virtualQString itemType (
const QVariantList &indexPath)

void move (
intfrom,
intto )

QListDataModel & operator<< (
const Item &value)

void removeAt (
inti)

void replace (
inti,
const Item &value )

int size ()

void swap (
inti,
intj )

Item value (
inti)

Item value (
inti,
const Item &defaultValue )

DataModel (
QObject *parent)

Signals

void itemAdded (
QVariantListindexPath)

void itemRemoved (
QVariantListindexPath)

void itemsChanged (
bb::cascades::DataModelChangeType::TypeeChangeType,
QSharedPointer< bb::cascades::DataModel::IndexMapper >indexMapper )

void itemUpdated (
QVariantListindexPath)

1. Choose your focus

2. Download the tools

3. Try the sample apps

4. Educate yourself

5. Start developing

QListDataModel< QVariantMap >	QMapListDataModel
QListDataModel< QString >	QStringListDataModel
QListDataModel< QVariant >	QVariantListDataModel

QListDataModel

Overview

Inheritance

Public Functions Index

Signals Index

Related Members Index

Public Functions

QListDataModel ()

QListDataModel (const QList< Item > &other)

virtual~QListDataModel ()

void append (const Item &value)

void append (const QList< Item > &values)

virtual int childCount (const QVariantList &indexPath)

void clear ()

virtualQVariant data (const QVariantList &indexPath)

virtual bool hasChildren (const QVariantList &indexPath)

int indexOf (const Item &value, intfrom )

void insert (inti, const Item &value )

void insert (inti, const QList< Item > &values )

bool isEmpty ()

virtualQString itemType (const QVariantList &indexPath)

void move (intfrom, intto )

QListDataModel & operator<< (const Item &value)

void removeAt (inti)

void replace (inti, const Item &value )

int size ()

void swap (inti, intj )

Item value (inti)

Item value (inti, const Item &defaultValue )

DataModel (QObject *parent)

Signals

void itemAdded (QVariantListindexPath)

void itemRemoved (QVariantListindexPath)

void itemsChanged (bb::cascades::DataModelChangeType::TypeeChangeType, QSharedPointer< bb::cascades::DataModel::IndexMapper >indexMapper )

void itemUpdated (QVariantListindexPath)

Related Members

typedef QListDataModel< QVariantMap > QMapListDataModel

typedef QListDataModel< QString > QStringListDataModel

typedef QListDataModel< QVariant > QVariantListDataModel

1. Choose your focus

2. Download the tools

3. Try the sample apps

4. Educate yourself

5. Start developing

QListDataModel (
const QList< Item > &other)

void append (
const Item &value)

void append (
const QList< Item > &values)

virtual int childCount (
const QVariantList &indexPath)

virtualQVariant data (
const QVariantList &indexPath)

virtual bool hasChildren (
const QVariantList &indexPath)

int indexOf (
const Item &value,
intfrom )

void insert (
inti,
const Item &value )

void insert (
inti,
const QList< Item > &values )

virtualQString itemType (
const QVariantList &indexPath)

void move (
intfrom,
intto )

QListDataModel & operator<< (
const Item &value)

void removeAt (
inti)

void replace (
inti,
const Item &value )

void swap (
inti,
intj )

Item value (
inti)

Item value (
inti,
const Item &defaultValue )

DataModel (
QObject *parent)

void itemAdded (
QVariantListindexPath)

void itemRemoved (
QVariantListindexPath)

void itemsChanged (
bb::cascades::DataModelChangeType::TypeeChangeType,
QSharedPointer< bb::cascades::DataModel::IndexMapper >indexMapper )

void itemUpdated (
QVariantListindexPath)