XmlDataModel

Since: BlackBerry 10.0.0

#include <bb/cascades/XmlDataModel>

A class that creates a static DataModel for ListView from an XML file.

The XmlDataModel is useful when prototyping a UI, since it allows a complex model to be declared in an XML file without any C++ code being written.

Each element in the XML file (except the mandatory root element) can be shown as an item in the ListView. XmlDataModel::data() returns a QVariantMap (wrapped in a QVariant) containing the properties of the requested element/item. XmlDataModel::itemType() returns the name of the requested element/item. The model tree can be many levels deep, but ListView typically only shows items from the two first levels under its root item.

Text written outside of tags in the XML file is ignored. Any values that are to be used in list item visuals must be written as properties on tags.

Example of an XML model with items on three levels (not counting the mandatory root element):

 <model>
   <header title="A">
     <contact name="Adam">
       <phone number="+4623894299" />
       <phone number="+4623929922" />
     </contact>
     <contact name="Annie">
       <phone number="+4654633667" />
       <email address="annie@rim.com" />
     </contact>
   </header>
   <header title="B">
     <contact name="Bert">
       <phone number="+465256467" />
       <phone number="+464746734" />
       <phone number="+468234892" />
     </contact>
   </header>
 </model>

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

 ListView {
     dataModel: XmlDataModel { source: "model.xml" }
 }


Overview

Inheritance

bb::cascades::DataModel
bb::cascades::XmlDataModel

QML properties

source: QUrl

QML signals

Properties Index

Public Functions Index

XmlDataModel (QObject *parent=0)
virtual ~XmlDataModel ()
virtual intchildCount (const QVariantList &indexPath)
virtual QVariantdata (const QVariantList &indexPath)
virtual boolhasChildren (const QVariantList &indexPath)
virtual QStringitemType (const QVariantList &indexPath)
Q_SLOT voidsetSource (const QUrl &newSource)
QUrlsource () const
DataModel (QObject *parent=0)Inherited

Signals Index

voidsourceChanged (QUrl source)
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

QUrl source

The path to the source XML file.

Since:

BlackBerry 10.0.0

Public Functions

XmlDataModel (

Constructs an empty XmlDataModel with the specified parent.

Parameters
parent

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

Since:

BlackBerry 10.0.0

virtual~XmlDataModel ()

Destructor.

Since:

BlackBerry 10.0.0

virtual int childCount (

Returns the number of children for the data item specified by 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 XmlDataModel:

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

The index path to the data item to get child count for. See [Index paths](http://developer.blackberry.com/native/documentation/cascades/ui/lists/list_view_selection.html#indexpaths) for more information.

Return:

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

Since:

BlackBerry 10.0.0

virtualQVariant data (

Returns a QVariantMap containing the properties of the specified item.

The ListView will pass on the data as a parameter to ListItemProvider::updateItem(). In QML the data is made available as ListItem.data on the root node of the list item visuals, and as ListItemData in the context of the list item visuals.

Parameters
indexPath

The index path to the item in the model. See [Index paths](http://developer.blackberry.com/native/documentation/cascades/ui/lists/list_view_selection.html#indexpaths) 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

virtual bool hasChildren (

Indicates whether the data item specified by indexPath has children.

Parameters
indexPath

The index path to the data item to query for children. See [Index paths](http://developer.blackberry.com/native/documentation/cascades/ui/lists/list_view_selection.html#indexpaths) 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

virtualQString itemType (

Returns the type for the specified item.

The type for each item is determined by the name of the corresponding tag in the XML file.

Parameters
indexPath

The index path to the item in the model. See [Index paths](http://developer.blackberry.com/native/documentation/cascades/ui/lists/list_view_selection.html#indexpaths) for more information.

Return:

The name of the corresponding tag in the XML file.

Since:

BlackBerry 10.0.0

Q_SLOT void setSource (
  • const QUrl &newSource)

Sets a new path to the source XML file.

The path is relative to the application assets folder.

Since:

BlackBerry 10.0.0

QUrl source ()

Gets the current value of the source property.

Return:

The current path to the source XML file.

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 sourceChanged (

Emitted when the source property changes.

Parameters
source

The new path of the source XML file.

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.3.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-09-30



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

comments powered by Disqus