1 files changed, 337 insertions, 0 deletions
diff --git a/doc/src/declarative/qmlmodels.qdoc b/doc/src/declarative/qmlmodels.qdoc
new file mode 100644
index 0000000..008ea2a
--- /dev/null
+++ b/doc/src/declarative/qmlmodels.qdoc
@@ -0,0 +1,337 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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
+\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 {
+       Rect {
+            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
+
+*/