docs - quote code with snippets, other improvements

9 files changed, 116 insertions, 109 deletions

diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc
index 7671eb3..0d25da5 100644
--- a/doc/src/declarative/qdeclarativemodels.qdoc
+++ b/doc/src/declarative/qdeclarativemodels.qdoc
@@ -30,18 +30,46 @@
 \target qmlmodels
 \title Data Models
 
-Some QML Items use Data Models to provide the data to be displayed.
+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 the \e color role of the model and
-the \e color property of the Rectangle.  The clash is avoided by referencing
+delegate may bind to. Here is a ListModel with two roles, \e type and \e age,
+and a ListView with a delegate that binds to these roles to display their 
+values:
+
+\qml
+import Qt 4.7
+
+Item {
+    width: 200; height: 250
+
+    ListModel {
+        id: myModel
+        ListElement { type: "Dog"; age: 8 }
+        ListElement { type: "Cat"; age: 5 }
+    }
+
+    Component {
+        id: myDelegate
+        Text { text: type + ", " + age }
+    }
+
+    ListView {
+        anchors.fill: parent
+        model: myModel
+        delegate: myDelegate
+    }
+}
+\endqml
+
+If there is a naming clash between the model's properties and the delegate's
+properties (e.g. if the \l Text delegate above had \e type or \e age properties)
+the roles can be accessed with the qualified \e model name instead.
+For example, the following model has a \e color role which clashes with the 
+delegate \l Rectangle's \e color property. The clash is avoided by referencing
 the \e color property of the model by its full name: \e model.color.
 
 \code
@@ -61,7 +89,7 @@ Component {
 \endcode
 
 A special \e index role containing the index of the item in the model
-is also available.
+is also available to the delegate.
 
 \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
@@ -148,9 +176,9 @@ Item {
 }
 \endcode
 
-When the MouseArea is clicked fruitModel will have two roles, "cost" and "name".
+When the MouseArea is clicked, \c fruitModel will have two roles, "cost" and "name".
 Even if subsequent roles are added, only the first two will be handled by views
-using the model.
+using the model. To reset the roles available in the model, call ListModel::clear().
 
 
 \section2 XmlListModel
@@ -170,6 +198,9 @@ XmlListModel {
 }
 \endcode
 
+The \l{declarative/demos/rssnews}{RSS News demo} shows how XmlListModel can
+be used to display an RSS feed.
+
 
 \section2 VisualItemModel
 
@@ -230,9 +261,9 @@ ctxt->setContextProperty("myModel", model);
 or by registering the subclass as a new QML type in 
 a \l{QDeclarativeExtensionPlugin}{QML C++ plugin}.
 
-QAbstractItemModel presents a heirachy of tables, but views currently provided by QML
+QAbstractItemModel presents a hierarchy of tables, but views currently provided by QML
 can only display list data.  
-In order to display child lists of a heirachical model
+In order to display child lists of a hierarchical model
 the VisualDataModel element provides several properties and functions for use
 with models of type QAbstractItemModel:
 \list
@@ -245,101 +276,60 @@ with models of type QAbstractItemModel:
 
 \section2 QStringList
 
-A model may be a simple QStringList, which provides the contents of the list via the \e modelData role:
+A model may be a simple QStringList, which provides the contents of the list via the \e modelData role.
 
-\table
-\row
-\o
-\code
-// main.cpp
-QStringList dataList;
-dataList.append("Fred");
-dataList.append("Ginger");
-dataList.append("Skipper");
+Here is a ListView with a delegate that references its model item's 
+value using the \c modelData role:
 
-QDeclarativeContext *ctxt = view.rootContext();
-ctxt->setContextProperty("myModel", QVariant::fromValue(dataList));
-\endcode
+\snippet examples/declarative/modelviews/stringlistmodel/view.qml 0
 
-\o
-\code
-// main.qml
-ListView {
-   width: 100
-   height: 100
-   anchors.fill: parent
-   model: myModel
-   delegate: Component {
-       Rectangle {
-            height: 25
-            Text { text: modelData }
-       }
-   }
-}
-\endcode
-\endtable
+A Qt application can load this QML document and set the value of \c myModel
+to a QStringList:
+
+\snippet examples/declarative/modelviews/stringlistmodel/main.cpp 0
 
-The complete example is available in \l {declarative/modelviews/stringlistmodel}.
+The complete example is available in Qt's \l {declarative/modelviews/stringlistmodel}{examples/declarative/modelviews/stringlistmodel} directory.
 
 \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
+have changed.  If the QStringList changes, 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)
-...
-};
+A list of QObject* values can also be used as a model. A QList<QObject*> provides 
+the properties of the objects in the list as roles.
 
-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"));
+The following application creates a \c DataObject class that with
+Q_PROPERTY values that will be accessible as named roles when a
+QList<DataObject*> is exposed to QML:
 
-QDeclarativeContext *ctxt = view.rootContext();
-ctxt->setContextProperty("myModel", QVariant::fromValue(dataList));
-\endcode
+\snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 0
+\dots 4
+\snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 1
+\codeline
+\snippet examples/declarative/modelviews/objectlistmodel/main.cpp 0
+\dots 4
+\snippet examples/declarative/modelviews/objectlistmodel/main.cpp 1
+\dots 4
+\snippet examples/declarative/modelviews/objectlistmodel/main.cpp 2
 
 The QObject* is available as the \c modelData property.  As a convenience,
 the properties of the object are also made available directly in the
-delegate's context:
-
-\code
-ListView {
-   width: 100
-   height: 100
-   anchors.fill: parent
-   model: myModel
-   delegate: Component {
-       Rectangle {
-            height: 25
-            width: 100
-            color: model.modelData.color
-            Text { text: name }
-       }
-   }
-}
-\endcode
+delegate's context. Here, \c view.qml references the \c DataModel properties in
+the ListView delegate:
 
-The complete example is available in \l {declarative/modelviews/objectlistmodel}.
+\snippet examples/declarative/modelviews/objectlistmodel/view.qml 0
 
 Note the use of the fully qualified access to the \c color property.  
 The properties of the object are not replicated in the \c model
 object, since they are easily available via the modelData
 object.
 
+The complete example is available in Qt's \l {declarative/modelviews/objectlistmodel}{examples/declarative/modelviews/objectlistmodel} directory.
+
 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
+have changed.  If the QList changes, it will be necessary to reset
 the model by calling QDeclarativeContext::setContextProperty() again.
 
 
@@ -354,8 +344,7 @@ There are no data roles.
 The following example creates a ListView with five elements:
 \code
 Item {
-    width: 200
-    height: 250
+    width: 200; height: 250
 
     Component {
         id: itemDelegate
@@ -374,7 +363,7 @@ Item {
 
 \section2 An Object Instance
 
-An Object Instance specifies a model with a single Object element.  The
+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
@@ -383,6 +372,8 @@ to avoid clashing with \e color property of the Text element in the delegate.
 
 \code
 Rectangle {
+    width: 200; height: 250
+
     Text {
         id: myText
         text: "Hello"
diff --git a/doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml b/doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml
index 835ca32..9e759f9 100644
--- a/doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml
+++ b/doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml
@@ -55,7 +55,7 @@ ListView {
             MouseArea {
                 anchors.fill: parent
                 onClicked: {
-                    if (hasModelChildren) 
+                    if (model.hasModelChildren) 
                         view.model.rootIndex = view.model.modelIndex(index)
                 }
             }
diff --git a/examples/declarative/modelviews/objectlistmodel/dataobject.h b/examples/declarative/modelviews/objectlistmodel/dataobject.h
index c61e50c..17aa355 100644
--- a/examples/declarative/modelviews/objectlistmodel/dataobject.h
+++ b/examples/declarative/modelviews/objectlistmodel/dataobject.h
@@ -43,12 +43,14 @@
 
 #include <QObject>
 
+//![0]
 class DataObject : public QObject
 {
     Q_OBJECT
 
     Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
     Q_PROPERTY(QString color READ color WRITE setColor NOTIFY colorChanged)
+//![0]
 
 public:
     DataObject(QObject *parent=0);
@@ -67,6 +69,8 @@ signals:
 private:
     QString m_name;
     QString m_color;
+//![1]
 };
+//![1]
 
 #endif // DATAOBJECT_H
diff --git a/examples/declarative/modelviews/objectlistmodel/main.cpp b/examples/declarative/modelviews/objectlistmodel/main.cpp
index 25de8d1..8c921b7 100644
--- a/examples/declarative/modelviews/objectlistmodel/main.cpp
+++ b/examples/declarative/modelviews/objectlistmodel/main.cpp
@@ -53,24 +53,29 @@
    model in QML
 */
 
+//![0]
 int main(int argc, char ** argv)
 {
+//![0]
     QApplication app(argc, argv);
 
-    QDeclarativeView view;
-
+//![1]
     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"));
 
+    QDeclarativeView view;
     QDeclarativeContext *ctxt = view.rootContext();
     ctxt->setContextProperty("myModel", QVariant::fromValue(dataList));
 
     view.setSource(QUrl("qrc:view.qml"));
     view.show();
+//![1]
 
     return app.exec();
+//![2]
 }
+//![2]
 
diff --git a/examples/declarative/modelviews/objectlistmodel/view.qml b/examples/declarative/modelviews/objectlistmodel/view.qml
index 034121c..c3cccdd 100644
--- a/examples/declarative/modelviews/objectlistmodel/view.qml
+++ b/examples/declarative/modelviews/objectlistmodel/view.qml
@@ -40,17 +40,17 @@
 
 import Qt 4.7
 
+//![0]
 ListView {
-    width: 100
-    height: 100
+    width: 100; height: 100
     anchors.fill: parent
+
     model: myModel
-    delegate: Component {
-        Rectangle {
-            height: 25
-            width: 100
-            color: model.modelData.color
-            Text { text: name }
-        }
+    delegate: Rectangle {
+        height: 25
+        width: 100
+        color: model.modelData.color
+        Text { text: name }
     }
 }
+//![0]
diff --git a/examples/declarative/modelviews/stringlistmodel/main.cpp b/examples/declarative/modelviews/stringlistmodel/main.cpp
index b2ebd4b..ea73859 100644
--- a/examples/declarative/modelviews/stringlistmodel/main.cpp
+++ b/examples/declarative/modelviews/stringlistmodel/main.cpp
@@ -56,19 +56,20 @@ int main(int argc, char ** argv)
 {
     QApplication app(argc, argv);
 
-    QDeclarativeView view;
-
+//![0]
     QStringList dataList;
     dataList.append("Item 1");
     dataList.append("Item 2");
     dataList.append("Item 3");
     dataList.append("Item 4");
 
+    QDeclarativeView view;
     QDeclarativeContext *ctxt = view.rootContext();
     ctxt->setContextProperty("myModel", QVariant::fromValue(dataList));
 
     view.setSource(QUrl("qrc:view.qml"));
     view.show();
+//![0]
 
     return app.exec();
 }
diff --git a/examples/declarative/modelviews/stringlistmodel/view.qml b/examples/declarative/modelviews/stringlistmodel/view.qml
index ec5597d..3d789fd 100644
--- a/examples/declarative/modelviews/stringlistmodel/view.qml
+++ b/examples/declarative/modelviews/stringlistmodel/view.qml
@@ -39,17 +39,17 @@
 ****************************************************************************/
 
 import Qt 4.7
+//![0]
 
 ListView {
-    width: 100
-    height: 100
+    width: 100; height: 100
     anchors.fill: parent
+
     model: myModel
-    delegate: Component {
-        Rectangle {
-            height: 25
-            width: 100
-            Text { text: modelData }
-        }
+    delegate: Rectangle {
+        height: 25
+        width: 100
+        Text { text: modelData }
     }
 }
+//![0]
diff --git a/src/declarative/graphicsitems/qdeclarativelistview.cpp b/src/declarative/graphicsitems/qdeclarativelistview.cpp
index 4be8705..e519bd9 100644
--- a/src/declarative/graphicsitems/qdeclarativelistview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativelistview.cpp
@@ -1395,7 +1395,7 @@ void QDeclarativeListViewPrivate::flick(AxisData &data, qreal minExtent, qreal m
     to set \e {clip: true} in order to have the out of view items clipped
     nicely.
 
-    \sa ListModel, GridView, {declarative/modelviews/listview}{ListView examples}
+    \sa {Data Models}, GridView, {declarative/modelviews/listview}{ListView examples}
 */
 
 QDeclarativeListView::QDeclarativeListView(QDeclarativeItem *parent)
diff --git a/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp b/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp
index 8071d7a..786d6f9 100644
--- a/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp
+++ b/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp
@@ -818,6 +818,12 @@ void QDeclarativeVisualDataModel::setDelegate(QDeclarativeComponent *delegate)
     \c view.qml:
     \snippet doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml 0
 
+    If the \l model is a QAbstractItemModel subclass, the delegate can also
+    reference a \c hasModelChildren property (optionally qualified by a
+    \e model. prefix) that indicates whether the delegate's model item has 
+    any child nodes.
+
+
     \sa modelIndex(), parentModelIndex()
 */
 QVariant QDeclarativeVisualDataModel::rootIndex() const