Some docs on data models.

9 files changed, 79 insertions, 4 deletions

diff --git a/doc/src/declarative/binding.qdoc b/doc/src/declarative/binding.qdoc
index 37b4c97..e6835ee 100644
--- a/doc/src/declarative/binding.qdoc
+++ b/doc/src/declarative/binding.qdoc
@@ -38,7 +38,8 @@ The QML mechanisms of data binding can also be used to bind Qt C++ objects.
 
 The data binding framework is based on Qt's property system (see the Qt documentation for more details on this system). If a binding is meant to be dynamic (where changes in one object are reflected in another object), \c NOTIFY must be specified for the property being tracked. If \c NOTIFY is not specified, any binding to that property will be an 'intialization' binding (the tracking object will be updated only once with the initial value of the tracked object).
 
-Relevant items can also be bound to the contents of a Qt model. For example, ListView can make use of data from a QListModelInterface-derived model. (QListModelInterface is part of the next generation Model/View architecture being developed for Qt.)
+Relevant items can also be bound to the contents of a Qt model.
+For example, ListView can make use of data from a QAbstractItemModel-derived model.
 
 
 \section1 Passing Data Between C++ and QML
@@ -107,4 +108,6 @@ Binding { target: screen; property: "brightness"; value: slider.value }
 
 The \l QBindableMap class provides a convenient way to make data visible to the bind engine.
 
+C++ \l {qmlmodels}{Data Models} may also be provided to QML.
+
 */
diff --git a/doc/src/declarative/qmlmodels.qdoc b/doc/src/declarative/qmlmodels.qdoc
new file mode 100644
index 0000000..4712de1
--- /dev/null
+++ b/doc/src/declarative/qmlmodels.qdoc
@@ -0,0 +1,61 @@
+/*! 
+\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.  A special \e index role containing the
+index of the item in the model is also available.  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 {qml-repeater}{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
+
+\list
+\o ListModel is a simple hierarchy of elements specified in QML.  The
+available roles are specified by the \l ListElement properties.
+\o XmlListModel allows construction of a model from an XML data source. The roles
+are specified via the \l XmlRole element.
+\o 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.
+\endlist
+
+
+\section1 C++ Data Models
+
+\list
+\o QAbstractItemModel provides the roles set via the QAbstractItemModel::setRoleNames() method.
+\o QStringList provides the contents of the list via the \e modelData role.
+\o QList<QObject*> provides the properties of the objects in the list as roles.
+\endlist
+
+
+\section1 Other Data Models
+
+\list
+\o An Integer specifies a model containing the integer number of elements.
+There are no data roles.
+\o An Object Instance specifies a model with a single Object element.  The
+properties of the object are provided as roles.
+\endlist
+
+*/
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index 460819a..06cba15 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -71,6 +71,7 @@
     Core QML Features:
     \list
     \o \l {binding}{Data Binding}
+    \o \l {qmlmodels}{Data Models}
     \o \l {anchor-layout}{Layout Anchors}
     \o \l {qmlanimation}{Animation}
     \o \l {qmlmodules}{Modules}
diff --git a/src/declarative/fx/qfxgridview.cpp b/src/declarative/fx/qfxgridview.cpp
index 3bfc799..9aa1198 100644
--- a/src/declarative/fx/qfxgridview.cpp
+++ b/src/declarative/fx/qfxgridview.cpp
@@ -710,6 +710,8 @@ QFxGridView::~QFxGridView()
   for the view.  For large or dynamic datasets the model is usually
   provided by a C++ model object.  The C++ model object must be a \l
   {QAbstractItemModel} subclass, a VisualModel, or a simple list.
+
+  \sa {qmlmodels}{Data Models}
 */
 QVariant QFxGridView::model() const
 {
diff --git a/src/declarative/fx/qfxlistview.cpp b/src/declarative/fx/qfxlistview.cpp
index 71fa2ea..501b4df 100644
--- a/src/declarative/fx/qfxlistview.cpp
+++ b/src/declarative/fx/qfxlistview.cpp
@@ -876,6 +876,8 @@ QFxListView::~QFxListView()
 
     Models can also be created directly in QML, using a \l{ListModel},
     \l{XmlListModel} or \l{VisualItemModel}.
+
+    \sa {qmlmodels}{Data Models}
 */
 QVariant QFxListView::model() const
 {
diff --git a/src/declarative/fx/qfxpathview.cpp b/src/declarative/fx/qfxpathview.cpp
index 86bc9a2..b127f39 100644
--- a/src/declarative/fx/qfxpathview.cpp
+++ b/src/declarative/fx/qfxpathview.cpp
@@ -140,6 +140,8 @@ QFxPathView::~QFxPathView()
     The model provides a set of data that is used to create the items for the view.
     For large or dynamic datasets the model is usually provided by a C++ model object.
     Models can also be created directly in XML, using the ListModel element.
+
+    \sa {qmlmodels}{Data Models}
 */
 QVariant QFxPathView::model() const
 {
diff --git a/src/declarative/fx/qfxrepeater.cpp b/src/declarative/fx/qfxrepeater.cpp
index 063bd1f..182dcc7 100644
--- a/src/declarative/fx/qfxrepeater.cpp
+++ b/src/declarative/fx/qfxrepeater.cpp
@@ -143,6 +143,8 @@ QFxRepeater::~QFxRepeater()
     based on the order they are created.
 
     Models can also be created directly in QML, using a \l{ListModel} or \l{XmlListModel}.
+
+    \sa {qmlmodels}{Data Models}
 */
 QVariant QFxRepeater::model() const
 {
diff --git a/src/declarative/fx/qfxvisualitemmodel.cpp b/src/declarative/fx/qfxvisualitemmodel.cpp
index 45166de..fb1cfcf 100644
--- a/src/declarative/fx/qfxvisualitemmodel.cpp
+++ b/src/declarative/fx/qfxvisualitemmodel.cpp
@@ -132,7 +132,11 @@ public:
     \brief The VisualItemModel allows items to be provided to a view.
 
     The children of the VisualItemModel are provided in a model which
-    can be used in a view.  An item can determine its index within the
+    can be used in a view.  Note that no delegate should be
+    provided to a view since the VisualItemModel contains the
+    visual delegate (items).
+
+    An item can determine its index within the
     model via the VisualItemModel.index attached property.
 
     The example below places three colored rectangles in a ListView.
diff --git a/src/declarative/util/qmllistaccessor.cpp b/src/declarative/util/qmllistaccessor.cpp
index ef21ebf..578646b 100644
--- a/src/declarative/util/qmllistaccessor.cpp
+++ b/src/declarative/util/qmllistaccessor.cpp
@@ -76,7 +76,6 @@ void QmlListAccessor::setList(const QVariant &v, QmlEngine *engine)
     } else if (d.type() == QMetaType::QVariantList) {
         m_type = VariantList;
     } else if (d.canConvert(QVariant::Int)) {
-        qDebug() << "integer";
         m_type = Integer;
     } else if (d.type() != QVariant::UserType) {
         m_type = Instance;
@@ -90,7 +89,6 @@ void QmlListAccessor::setList(const QVariant &v, QmlEngine *engine)
                (enginePrivate && enginePrivate->isQmlList(d.userType()))) {
         m_type = QmlList;
     } else if (QmlMetaType::isList(d.userType())) {
-        qDebug() << "list";
         m_type = QList;
     } else {
         m_type = Invalid;