13 files changed, 243 insertions, 164 deletions
diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc
index 5c025e5..99f7777 100644
--- a/doc/src/declarative/anchor-layout.qdoc
+++ b/doc/src/declarative/anchor-layout.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-\page anchor-layout.html
+\page qml-anchor-layout.html
 \target anchor-layout
 \title Anchor-based Layout in QML
 
diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc
index 9403920..aa4feef 100644
--- a/doc/src/declarative/codingconventions.qdoc
+++ b/doc/src/declarative/codingconventions.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-\page codingconventions.html
+\page qml-coding-conventions.html
 \title QML Coding Conventions
 
 This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.
diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc
index e1c9473..2f43682 100644
--- a/doc/src/declarative/declarativeui.qdoc
+++ b/doc/src/declarative/declarativeui.qdoc
@@ -34,28 +34,36 @@
 \brief Qt Quick provides a declarative framework for building highly
 dynamic, custom user interfaces.
 
-Qt Quick provides a declarative framework for building highly dynamic,
-custom user interfaces from a rich set of \l{QML Elements}{QML elements}.
-Qt Quick helps programmers and designers collaborate to
-build the fluid user interfaces that are becoming common in portable
-consumer devices, such as mobile phones, media players, set-top boxes
-and netbooks. Qt Quick consists of the QtDeclarative C++ module, QML, and
-the integration of both of these into the Qt Creator IDE. Using the QtDeclarative
-C++ module, you can load and interact with QML files from your Qt application.
-
-QML is an extension to \l{About JavaScript}{JavaScript}, that provides
-a mechanism to declaratively build an object tree of
-\l{QML Elements}{QML elements}.  QML improves the integration between
-JavaScript and Qt's existing QObject-based type system, adds support for
-automatic \l{Property Binding}{property bindings} and provides
+\section1 Introduction
+
+Qt Quick is a collection of technologies that are designed to help
+developers create the kind of intuitive, modern-looking, fluid user
+interfaces that are increasingly used on mobile phones, media players,
+set-top boxes and other portable devices.
+
+Qt Quick consists of a rich set of user interface elements, a declarative
+language for describing user interfaces and a language runtime. A collection
+of C++ APIs is used to integrate these high level features with classic
+Qt applications.
+
+\section2 QML, Elements and the QtDeclarative Module
+
+User interfaces and their behavior are described using QML, an extension to
+\l{About JavaScript}{JavaScript} that lets developers and designers
+use a declarative syntax to specify each user interface in terms of
+\l{QML Elements}{QML elements}. These elements are a sophisticated set of
+graphical and behavioral building blocks that can be combined together in
+\l{QML Documents}{QML documents} to build components ranging in complexity
+from simple buttons and sliders, to complete Internet-enabled applications.
+
+QML improves the integration between JavaScript and Qt's existing
+QObject-based type system, adds support for automatic
+\l{Property Binding}{property bindings} and provides
 \l{Network Transparency}{network transparency} at the language level.
 
-The \l{QML Elements}{QML elements} are a sophisticated set of
-graphical and behavioral building blocks.  These different elements
-are combined together in \l{QML Documents}{QML documents} to build
-components ranging in complexity from simple buttons and sliders, to
-complete Internet-enabled applications like a photo browser for the
-popular \l{http://www.flickr.com}{Flickr} photo-sharing site.
+The QtDeclarative module implements the interface between the QML language
+and the elements available to it. It also provides a C++ API that can be
+used to load and interact with QML files from within Qt applications.
 
 Qt Quick builds on \l{QML for Qt programmers}{Qt's existing strengths}.
 QML can be be used to incrementally extend an existing application or
@@ -67,32 +75,55 @@ Module.
 
 \list
 \o \l{Introduction to the QML language}
-\o \l{QML Tutorial}{Tutorial: 'Hello World'}
-\o \l{QML Advanced Tutorial}{Tutorial: 'Same Game'}
-\o \l{QML Examples and Demos}
 \o \l{QML for Qt Programmers}
 \o \l{Getting Started Programming with QML}
 \o \l{Beginning Qt Quick}
 \endlist
 
-\section1 Core QML Features
+\list
+\o \l{QML Tutorial}{Tutorial: "Hello World"}
+\o \l{QML Advanced Tutorial}{Tutorial: "Same Game"}
+\o \l{QML Examples and Demos}
+\endlist
+
+\section1 QML Concepts
+
 \list
 \o \l{QML Documents}
 \o \l{Property Binding}
-\o \l{Network Transparency}
 \o \l{QML Scope}
-\o \l{Integrating JavaScript}
-\o \l{Data Models}
+\o \l{QML Modules}
 \o \l{Anchor-based Layout in QML}
+\endlist
+
+\section1 User Interaction
+
+\list
+\o \l{Keyboard Focus in QML}
 \o \l{QML States}
 \o \l{QML Animation}
-\o \l{Keyboard Focus in QML}
-\o \l{QML Modules}
+\endlist
+
+\section1 Handling Data
+
+\list
+\o \l{Using QML Positioner and Repeater Items}
+\o \l{QML Data Models}
+\o \l{Presenting Data with QML}
+\o \l{Network Transparency}
+\endlist
+
+\section1 Architecture
+
+\list
+\o \l{Qt Declarative UI Runtime}
+\o \l{Integrating JavaScript}
 \o \l{Extending types from QML}
 \o \l{Dynamic Object Management in QML}
 \endlist
 
 \section1 Using QML with C++
+
 \list
 \o \l{Qt Declarative UI Runtime}
 \o \l{Using QML in C++ Applications}
@@ -102,6 +133,7 @@ Module.
 \endlist
 
 \section1 Reference
+
 \list
 \o \l{QML Elements}
 \o \l{QML Global Object}
@@ -113,4 +145,12 @@ Module.
 \o \l{QML Performance}
 \o \l{QML Coding Conventions}
 \endlist
+
+\section1 Online Examples
+
+\list
+\o Forum Nokia:
+\l{http://wiki.forum.nokia.com/index.php/Qt_Quick_examples_for_porting}{Qt Quick
+examples for porting}
+\endlist
 */
diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc
index 94abe10..252b964 100644
--- a/doc/src/declarative/elements.qdoc
+++ b/doc/src/declarative/elements.qdoc
@@ -29,12 +29,13 @@
   \page qdeclarativeelements.html
   \target elements
   \title QML Elements
+  \brief A dictionary of standard QML elements.
 
-  This is a dictionary of all the QML elements available in the \l
-  {QtDeclarative} {Qt Declarative} module. 
+  This is a dictionary of all standard QML elements made available
+  in the QtDeclarative module.
 
-  To see the QML elements listed by
-  functional area, \l{Groups Of Related QML Elements} {look here}.
+  To see the QML elements listed by functional area, see the
+  \l{Groups Of Related QML Elements} page.
 
   \generatelist qmlclasses
 
diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc
index d128d0f..349ac30 100644
--- a/doc/src/declarative/extending-tutorial.qdoc
+++ b/doc/src/declarative/extending-tutorial.qdoc
@@ -26,7 +26,6 @@
 ****************************************************************************/
 
 /*!
-
 \page qml-extending-tutorial-index.html
 \title Tutorial: Writing QML extensions with C++
 
diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc
index 18da3d2..d290690 100644
--- a/doc/src/declarative/javascriptblocks.qdoc
+++ b/doc/src/declarative/javascriptblocks.qdoc
@@ -173,6 +173,40 @@ handler to execute at startup, they are run sequentially in an undefined order.
 Likewise, the \l {Component::onDestruction} attached property is triggered on
 component destruction.
 
+
+\section1 Property Assignment vs Property Binding
+
+When working with both QML and JavaScript, it is important to differentiate between
+QML \l {Property Binding} and JavaScript value assignment. In QML, a property 
+binding is created using the \e {property: value} syntax:
+
+\code
+Rectangle {
+    width: otherItem.width
+}
+\endcode
+
+The \c width of the above \l Rectangle is updated whenever \c otherItem.width changes. On the other
+hand, take the following JavaScript code snippet, that runs when the \l Rectangle is created:
+
+\code
+Rectangle {
+
+    Component.onCompleted: {
+        width = otherItem.width;
+    }
+}
+\endcode
+
+The \c width of this \l Rectangle is \e assigned the value of \c otherItem.width using the
+\e {property = value} syntax in JavaScript. Unlike the QML \e {property: value} syntax, this
+does not invoke QML property binding; the \c rectangle.width property is set to the value
+of \c otherItem.width at the time of the assignment and will not be updated if that value
+changes.
+
+See \l {Property Binding} for more information.
+
+
 \section1 QML JavaScript Restrictions
 
 QML executes standard JavaScript code, with the following restrictions:
diff --git a/doc/src/declarative/pics/flipable.gif b/doc/src/declarative/pics/flipable.gif
index 6386f06..da37b2b 100644
--- a/doc/src/declarative/pics/flipable.gif
+++ b/doc/src/declarative/pics/flipable.gif
diff --git a/doc/src/declarative/pics/spacing_a.png b/doc/src/declarative/pics/spacing_a.png
deleted file mode 100644
index c0fe895..0000000
--- a/doc/src/declarative/pics/spacing_a.png
+++ /dev/null
diff --git a/doc/src/declarative/pics/spacing_b.png b/doc/src/declarative/pics/spacing_b.png
deleted file mode 100644
index 24cf640..0000000
--- a/doc/src/declarative/pics/spacing_b.png
+++ /dev/null
diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc
index 552b9e4..314bf67 100644
--- a/doc/src/declarative/propertybinding.qdoc
+++ b/doc/src/declarative/propertybinding.qdoc
@@ -94,10 +94,29 @@ Rectangle {
 }
 \endcode
 
-Imperatively assigning a value directly to a property will also implicitly remove a binding
-on a property.  A property can only have one value at a time, and if code explicitly sets
-this value the binding must be removed.  The \l Rectangle in the example below will have
-a width of 13, regardless of the otherItem's width.
+
+\section1 Effects of Property Assignment in JavaScript
+
+Assigning a property value from JavaScript does \e not create a property binding.
+For example:
+
+\code
+Rectangle {
+
+    Component.onCompleted: {
+        width = otherItem.width;
+    }
+}
+\endcode
+
+Instead of creating a property binding, this simply sets the \c width of the \l Rectangle
+to the value of \c other.width at the time the JavaScript code is invoked.  See 
+\l {Property Assignment vs Property Binding} for more details.
+
+Also note that assigning a value to a property that is currently bound will remove the binding.
+A property can only have one value at a time, and if any code explicitly sets
+this value, the binding is removed.  The \l Rectangle in the example below will have
+a width of 13, regardless of the \c otherItem's width.
 
 \code
 Rectangle {
@@ -109,7 +128,9 @@ Rectangle {
 }
 \endcode
 
-There is no way to create a property binding directly from imperative JavaScript code.
+There is no way to create a property binding directly from imperative JavaScript code,
+although it is possible to set up a \l Binding object (shown below).
+
 
 \section1 Binding Element
 
@@ -126,5 +147,7 @@ Binding {
     value: slider.value
 }
 \endqml
+
+
 */
 
diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc
index 068297a..8ca6c11 100644
--- a/doc/src/declarative/qdeclarativedocument.qdoc
+++ b/doc/src/declarative/qdeclarativedocument.qdoc
@@ -28,34 +28,17 @@
 /*!
 \page qdeclarativedocuments.html
 \title QML Documents
+\brief A description of QML documents and the kind of content they contain.
 
-A QML document is a block of QML source code.  QML documents generally correspond to files 
-stored on a disk or network resource, but can also be constructed directly from text data.
+\section1 Introduction
 
-Here is a simple QML document:
+A QML document is a block of QML source code.  QML documents generally correspond to files
+stored on a disk or at a location on a network, but they can also be constructed directly
+from text data.
 
-\code
-import Qt 4.7
+Here is a simple QML document:
 
-Rectangle {
-    width: 240; height: 320; 
-
-    resources: [
-        Component {
-            id: contactDelegate
-            Text {
-                text: modelData.firstName + " " + modelData.lastName
-            }
-        }
-    ]
-
-    ListView {
-        anchors.fill: parent
-        model: contactModel
-        delegate: contactDelegate
-    } 
-}
-\endcode
+\snippet doc/src/snippets/declarative/qml-documents/non-trivial.qml document
 
 QML documents are always encoded in UTF-8 format.
 
@@ -96,7 +79,7 @@ Each instance is created with a different value for its \c text property:
 \o application.qml
 
 \row
-\o \snippet doc/src/snippets/declarative/qmldocuments.qml 0
+\o \snippet doc/src/snippets/declarative/qml-documents/qmldocuments.qml document
 \o 
 \qml
 import Qt 4.7
@@ -153,39 +136,9 @@ These final two examples are behaviorally identical to the original document.
 \table
 \row
 \o
-\code
-import Qt 4.7
-
-Rectangle {
-    width: 240; height: 320; 
-
-    ListView {
-        anchors.fill: parent
-        model: contactModel
-        delegate: Component {
-            Text {
-                text: modelData.firstName + " " + modelData.lastName
-            }
-        }
-    } 
-}
-\endcode
+\snippet doc/src/snippets/declarative/qml-documents/inline-component.qml document
 \o
-\code
-import Qt 4.7
-
-Rectangle {
-    width: 240; height: 320; 
-
-    ListView {
-        anchors.fill: parent
-        model: contactModel
-        delegate: Text {
-            text: modelData.firstName + " " + modelData.lastName
-        }
-    } 
-}
-\endcode
+\snippet doc/src/snippets/declarative/qml-documents/inline-text-component.qml document
 \endtable
 
 \sa QDeclarativeComponent
diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc
index 173002a..7548c96 100644
--- a/doc/src/declarative/qdeclarativemodels.qdoc
+++ b/doc/src/declarative/qdeclarativemodels.qdoc
@@ -28,7 +28,7 @@
 /*!
 \page qdeclarativemodels.html
 \target qmlmodels
-\title Data Models
+\title QML Data Models
 
 QML items such as ListView, GridView and \l Repeater require Data Models 
 that provide the data to be displayed.
@@ -41,30 +41,7 @@ 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
+\snippet doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml document
 
 If there is a naming clash between the model's properties and the delegate's
 properties, the roles can be accessed with the qualified \e model name instead.
@@ -91,6 +68,10 @@ QML provides several types of data models among the built-in set of
 QML elements. In addition, models can be created with C++ and then
 made available to QML components.
 
+The views used to access data models are described in \l{Presenting Data with QML}.
+The use of positioner items to arrange items from a model is covered in
+\l{Using QML Positioner and Repeater Items}.
+
 
 \section1 QML Data Models
 
@@ -99,38 +80,12 @@ made available to QML components.
 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
+\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml model
 
 The above model has two roles, \e name and \e cost.  These can be bound
 to by a ListView delegate, for example:
 
-\code
-ListView {
-    width: 200; height: 250
-    model: fruitModel
-    delegate: Row {
-        Text { text: "Fruit: " + name }
-        Text { text: "Cost: $" + cost }
-    }
-}
-\endcode
+\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml view
 
 ListModel provides methods to manipulate the ListModel directly via JavaScript.
 In this case, the first item inserted determines the roles available
@@ -138,16 +93,9 @@ to any views that are using the model. For example, if an empty ListModel is
 created and populated via JavaScript, the roles provided by the first
 insertion are the only roles that will be shown in the view:
 
-\code
-Item {
-    ListModel { id: fruitModel }
-
-    MouseArea {
-        anchors.fill: parent
-        onClicked: fruitModel.append({"cost": 5.95, "name":"Pizza"})
-    }
-}
-\endcode
+\snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml model
+\dots
+\snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml mouse area
 
 When the MouseArea is clicked, \c fruitModel will have two roles, \e cost and \e name.
 Even if subsequent roles are added, only the first two will be handled by views
@@ -515,3 +463,84 @@ a function in the model, e.g.:
 updated, and that \e{value} holds the new value.
 
 */
+
+/*!
+\page qml-presenting-data.html
+\title Presenting Data with QML
+
+\section1 Introduction
+
+Qt Quick contains a set of standard items that can be used to present data in a
+number of different ways. For simple user interfaces,
+\l{Using QML Positioner and Repeater Items#Repeaters}{Repeaters} can be used
+in combination with
+\l{Using QML Positioner and Repeater Items#Positioners}{Positioners}
+to obtain pieces of data and arrange them in a user interface. However, when
+large quantities of data are involved, it is often better to use models with
+the standard views since these contain many built-in display and navigation
+features.
+
+\section1 Views
+
+Views are scrolling containers for collections of items. They are feature-rich,
+supporting many of the use cases found in typical applications, and can be
+customized to meet requirements on style and behavior.
+
+A set of standard views are provided in the basic set of Qt Quick
+graphical elements:
+
+\list
+\o \l{#ListView}{ListView} arranges items in a horizontal or vertical list
+\o \l{#GridView}{GridView} arranges items in a grid within the available space
+\o \l{#PathView}{PathView} arranges items on a path
+\endlist
+
+Unlike these items, \l WebView is not a fully-featured view item, and needs
+to be combined with a \l Flickable item to create a view that performs like
+a Web browser.
+
+\section2 ListView
+
+\l ListView shows a classic list of items with horizontal or vertical placing
+of items.
+
+\beginfloatright
+\inlineimage qml-listview-snippet.png
+\endfloat
+
+The following example shows a minimal ListView displaying a sequence of
+numbers (using an \l{QML Data Models#An Integer}{integer as a model}).
+A simple delegate is used to define an items for each piece of data in the
+model.
+
+\clearfloat
+\snippet doc/src/snippets/declarative/listview/listview-snippet.qml document
+
+
+
+\section2 GridView
+
+\l GridView displays items in a grid like an file manager's icon view.
+
+\section2 PathView
+
+\l PathView displays items on a path, where the selection remains in
+the same place and the items move around it.
+
+\section1 Decorating Views
+
+\section2 Headers and Footers
+
+\section2 Sections
+
+\section2 Navigation
+
+In traditional user interfaces, views can be scrolled using standard
+controls, such as scroll bars and arrow buttons. In some situations, it
+is also possible to drag the view directly by pressing and holding a
+mouse button while moving the cursor. In touch-based user interfaces,
+this dragging action is often complemented with a flicking action, where
+scrolling continues after the user has stopped touching the view.
+
+\section1 Further Reading
+*/
diff --git a/doc/src/declarative/qml-intro.qdoc b/doc/src/declarative/qml-intro.qdoc
index 9130be0..b77611c 100644
--- a/doc/src/declarative/qml-intro.qdoc
+++ b/doc/src/declarative/qml-intro.qdoc
@@ -58,12 +58,12 @@ would be a property.
 
 The basic syntax of an \l{QML Elements}{element} is
 
-\code
+\qml
 SomeElement {
     id: myObject
     ... some other things here ...
 }
-\endcode
+\endqml
 
 Here we are defining a new object. We specify its 'type' first as SomeElement.
 Then within matching braces { ... } we specify the various parts of our 
@@ -583,7 +583,7 @@ rectangle. The \c value attribute of 'dial' is set to a value based on the
 the rotation of the needle image. Notice this piece of code in Dial where
 the change in \c value modifies the position of the needle.
 
-\snippet examples/declarative/ui-components/dialcontrol/Dial.qml  needle angle
+\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml  needle angle
 
 This is part of the \c needleRotation that rotates the needle and causes the
 rotation of its shadow. \l SpringAnimation is an element that modifies the value