diff options
Diffstat (limited to 'doc/src/declarative/qdeclarativemodels.qdoc')
| -rw-r--r-- | doc/src/declarative/qdeclarativemodels.qdoc | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc new file mode 100644 index 0000000..c0e028e --- /dev/null +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -0,0 +1,341 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativemodels.html +\target qmlmodels +\title Data Models + +Some QML Items use Data Models to provide the data to be displayed. +These items typically require a \e delegate component that +creates an instance for each item in the model. Models may be static, or +have items modified, inserted, removed or moved dynamically. + +Data is provided to the delegate via named data roles which the +delegate may bind to. The roles are exposed as properties of the +\e model context property, though this property is set as a default property +of the delegate so, unless there is a naming clash with a +property in the delegate, the roles are usually accessed unqualified. The +example below would have a clash between he \e color role of the model and +the \e color property of the Rectangle. The clash is avoided by referencing +the \e color property of the model by its full name: \e model.color. + +\code +ListModel { + id: myModel + ListElement { color: "red" } + ListElement { color: "green" } +} + +Component { + id: myDelegate + Rectangle { + width: 20; height: 20 + color: model.color + } +} +\endcode + +A special \e index role containing the index of the item in the model +is also available. + +\e Note: the index role will be set to -1 if the item is removed from +the model. If you bind to the index role, be sure that the logic +accounts for the possibility of index being -1, i.e. that the item +is no longer valid. Usually the item will shortly be destroyed, but +it is possible to delay delegate destruction in some views via a delayRemove +attached property. + +Models that do not have named roles will have the data provided via +the \e modelData role. The \e modelData role is also provided for +Models that have only one role. In this case the \e modelData role +contains the same data as the named role. + +There are a number of QML elements that operate using data models: + +\list +\o ListView +\o GridView +\o PathView +\o \l Repeater +\endlist + +QML supports several types of data model, which may be provided by QML +or C++ (via QDeclarativeContext::setContextProperty(), for example). + +\section1 QML Data Models + +\section2 ListModel + +ListModel is a simple hierarchy of elements specified in QML. The +available roles are specified by the \l ListElement properties. + +\code +ListModel { + id: fruitModel + ListElement { + name: "Apple" + cost: 2.45 + } + ListElement { + name: "Orange" + cost: 3.25 + } + ListElement { + name: "Banana" + cost: 1.95 + } +} +\endcode + +The above model has two roles, \e name and \e cost. These can be bound +to by a ListView delegate, for example: + +\code +Component { + id: fruitDelegate + Row { + Text { text: "Fruit: " + name } + Text { text: "Cost: $" + cost } + } +} +ListView { + model: fruitModel + delegate: fruitDelegate +} +\endcode + + +\section2 XmlListModel + +XmlListModel allows construction of a model from an XML data source. The roles +are specified via the \l XmlRole element. + +The following model has three roles, \e title, \e link and \e description: +\code +XmlListModel { + id: feedModel + source: "http://rss.news.yahoo.com/rss/oceania" + query: "/rss/channel/item" + XmlRole { name: "title"; query: "title/string()" } + XmlRole { name: "link"; query: "link/string()" } + XmlRole { name: "description"; query: "description/string()" } +} +\endcode + + +\section2 VisualItemModel + +VisualItemModel allows QML items to be provided as a model. This model contains +both the data and delegate (its child items). This model does not provide any roles. + +\code + VisualItemModel { + id: itemModel + Rectangle { height: 30; width: 80; color: "red" } + Rectangle { height: 30; width: 80; color: "green" } + Rectangle { height: 30; width: 80; color: "blue" } + } + + ListView { + anchors.fill: parent + model: itemModel + } +\endcode + +Note that in the above example there is no delegate required. +The items of the model itself provide the visual elements that +will be positioned by the view. + + +\section1 C++ Data Models + +\section2 QAbstractItemModel + +QAbstractItemModel provides the roles set via the QAbstractItemModel::setRoleNames() method. + + +\section2 QStringList + +QStringList provides the contents of the list via the \e modelData role: + +\table +\header +\o +\o +\row +\o +\code +// main.cpp +QStringList dataList; +dataList.append("Fred"); +dataList.append("Ginger"); +dataList.appenf("Skipper"); + +QDeclarativeContext *ctxt = view.rootContext(); +ctxt->setContextProperty("myModel", QVariant::fromValue(&dataList)); +\endcode + +\o +\code +// main.qml +ListView { + width: 100 + height: 100 + anchors.fill: parent + model: myModel + delegate: Component { + Rectangle { + height: 25 + Text { text: modelData } + } + } +} +\endcode +\endtable + +\note There is no way for the view to know that the contents of a QStringList +have changed. If the QStringList is changed, it will be necessary to reset +the model by calling QDeclarativeContext::setContextProperty() again. + + +\section2 QList<QObject*> + +QList<QObject*> provides the properties of the objects in the list as roles. + +\code +class DataObject : public QObject +{ + Q_OBJECT + + Q_PROPERTY(QString name READ name WRITE setName) + Q_PROPERTY(QString color READ color WRITE setColor) +... +}; + +QList<QObject*> dataList; +dataList.append(new DataObject("Item 1", "red")); +dataList.append(new DataObject("Item 2", "green")); +dataList.append(new DataObject("Item 3", "blue")); +dataList.append(new DataObject("Item 4", "yellow")); + +QDeclarativeContext *ctxt = view.rootContext(); +ctxt->setContextProperty("myModel", QVariant::fromValue(dataList)); +\endcode + +The properties of the object may then be accessed in the delegate: + +\code +ListView { + width: 100 + height: 100 + anchors.fill: parent + model: myModel + delegate: Component { + Rectangle { + height: 25 + width: 100 + color: model.color + Text { text: name } + } + } +} +\endcode + +Note: There is no way for the view to know that the contents of a QList +have changed. If the QList is changed, it will be necessary to reset +the model by calling QDeclarativeContext::setContextProperty() again. + + +\section1 Other Data Models + + +\section2 An Integer + +An Integer specifies a model containing the integer number of elements. +There are no data roles. + +The following example creates a ListView with five elements: +\code +Component { + id: itemDelegate + Text { text: "I am item number: " + index } +} +ListView { + model: 5 + delegate: itemDelegate +} +\endcode + + +\section2 An Object Instance + +An Object Instance specifies a model with a single Object element. The +properties of the object are provided as roles. + +The example below creates a list with one item, showing the color of the +\e myText text. Note the use of the fully qualified \e model.color property +to avoid clashing with \e color property of the Text element in the delegate. + +\code +Rectangle { + Text { + id: myText + text: "Hello" + color: "#dd44ee" + } + + Component { + id: myDelegate + Text { + text: model.color + } + } + ListView { + anchors.fill: parent + anchors.topMargin: 30 + model: myText + delegate: myDelegate + } +} +\endcode + +*/ |