diff options
Diffstat (limited to 'doc/src/declarative/qmlmodels.qdoc')
| -rw-r--r-- | doc/src/declarative/qmlmodels.qdoc | 341 |
1 files changed, 0 insertions, 341 deletions
diff --git a/doc/src/declarative/qmlmodels.qdoc b/doc/src/declarative/qmlmodels.qdoc deleted file mode 100644 index 4843a7b..0000000 --- a/doc/src/declarative/qmlmodels.qdoc +++ /dev/null @@ -1,341 +0,0 @@ -/**************************************************************************** -** -** 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 qmlmodels.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 QmlContext::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"); - -QmlContext *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 QmlContext::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")); - -QmlContext *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 QmlContext::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 - -*/ |