Merge branch 'kinetic-declarativeui' of git@scm.dev.nokia.troll.no:qt/kinetic into kinetic-declarativeui

13 files changed, 569 insertions, 975 deletions

diff --git a/doc/src/declarative/anatomy.qdoc b/doc/src/declarative/anatomy.qdoc
new file mode 100644
index 0000000..f816464
--- /dev/null
+++ b/doc/src/declarative/anatomy.qdoc
@@ -0,0 +1,74 @@
+/****************************************************************************
+**
+** 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 qmldocumentanatomy.html
+\title Anatomy of a QML Document
+
+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 be constructed directly from text data.
+
+Syntactically a QML document is self contained; QML does \e not have a preprocessor that 
+modifies the document prior to presentation to the QML runtime.  Type references made within 
+a QML document, including within a \l {ECMAScript Block} contained by the document,  are 
+resolved based exclusively on the import statements present in the document.
+
+A simple QML document looks like this:
+
+\code
+import Qt 4.6
+
+Rectangle {
+    Component {
+        id: contactDelegate
+        Text {
+            text: modelData.firstName + " " + modelData.lastName
+        }
+    }
+
+    ListView {
+        model: contactModel
+        delegate: contactDelegate
+    } 
+}
+\endcode
+
+*/
diff --git a/doc/src/declarative/binding.qdoc b/doc/src/declarative/binding.qdoc
index 4f9bdc8..94465a1 100644
--- a/doc/src/declarative/binding.qdoc
+++ b/doc/src/declarative/binding.qdoc
@@ -40,37 +40,6 @@
 ****************************************************************************/
 
 /*!
-\page binding.html
-\title Data Binding in QML
-\target binding
-
-Data binding provides a declarative way of specifying the data associated with objects, as well as the relationship between data of different objects. For example, you could bind the text of a label to the value of a slider: as the value of the slider changed, the label would be automatically updated with the new value.
-
-Bindings are created in QML when an expression is assigned to a property. For example, the following produces two rectangles of equal size (\c rect2 is bound to the size of \c rect1):
-\code
-Rectangle { id: rect1; width: 100; height: 100 }
-Rectangle { id: rect2; width: rect1.width; height: rect1.height }
-\endcode
-
-There is also a special \l Binding element, which is typically used to bind from the UI to the underlying UI model (see \l {Passing Data Between C++ and QML} for an example of this). The bindings above could be expressed using the \l Binding element as:
-
-\code
-Binding { target: rect2; property: "width";  value: rect1.width }
-Binding { target: rect2; property: "height"; value: rect1.height }
-\endcode
-
-In addition to binding directly to a property, you can also bind to the results of expressions involving properties. For example:
-\code
-Text { text: contact.firstname + ' ' + contact.lastname }
-Image { source: if (contact.gender == "female") {"pics/female.png"} else {"pics/male.png"} }
-\endcode
-
-Relevant items can also be bound to the contents of a model - see \l ListView for an example of this.
-
-Data can be bound to C++ objects - see \l {QML/C++ Data Binding}.
-*/
-
-/*!
 \page qtbinding.html
 \target qtbinding
 \title QML/C++ Data Binding
diff --git a/doc/src/declarative/cppitem.qdoc b/doc/src/declarative/cppitem.qdoc
deleted file mode 100644
index c5ef4c4..0000000
--- a/doc/src/declarative/cppitem.qdoc
+++ /dev/null
@@ -1,170 +0,0 @@
-/****************************************************************************
-**
-** 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 cppitem.html
-\target cppitem
-\title C++ Components for QML
-
-\section1 Making a C++ object available in QML
-
-In QML, the item types and properties correspond to Qt objects and properties. Thus, any Qt object
-can potentially be used as an item in QML. More specifically, to make an object available in QML,
-it should:
-\list
-\o Be a subclass of QObject.
-\o Provide a default constructor.
-\o Declare Q_PROPERTYs.
-\o Be registered via the QML_DECLARE_TYPE and QML_DEFINE_TYPE macros.
-\endlist
-
-\section2 Declaring Q_PROPERTYs
-\target properties
-
-Properties of QObject subclasses are available as properties in QML.
-Like any QObject, these properties are defined by the Q_PROPERTY
-macro in the header file.
-
-Properties should have a NOTIFY function if they can change dynamically and
-if any useful response could be made to them changing in another object. Almost
-all properties will thus need a NOTIFY function.
-
-\code
-    Q_PROPERTY(qreal scale READ scale WRITE setScale NOTIFY scaleChanged);
-    qreal scale() const;
-    void setScale(qreal);
-    ...
-    signals: void scaleChanged();
-\endcode
-
-The property types currently supported by QML are:
-\list
-\o int
-\o qreal
-\o QString
-\o QColor
-\o QDate, QTime, and QDateTime
-\o QSize and QSizeF
-\o QPoint and QPointF
-\o QRect and QRectF
-\o QPixmap
-\o QIcon
-\o enums registered with Q_ENUMS
-\o flags registered with Q_FLAGS
-\o QVariant
-\o QObject* (or subclass)
-\endlist
-
-Custom property types that provide string-to-type conversion can be used as well, by:
-\list
-\o Registering them as a metatype (Q_DECLARE_METATYPE() and qRegisterMetaType())
-\o Registering a string-to-type convertor function (QML::addCustomStringConvertor()).
-\endlist
-
-\section2 Registering your type
-\target register
-
-In order for your type to be usable in QML, you must register it:
-
-\code
-QML_DECLARE_TYPE(TypeName);
-QML_DEFINE_TYPE(ModuleUri,ModuleMajorVersion,ModuleMinorVersionFrom,ModuleMinorVersionTo,QmlName,TypeName);
-\endcode
-
-These macros make the C++ \e TypeName available from the declarative markup language under the name \e QmlName.
-Of course there's nothing stopping you using the same name for both the C++ and the QML name!
-
-For example:
-\code
-QML_DECLARE_TYPE(MyCircle);
-QML_DEFINE_TYPE(MyLib,1,0,5,Circle,MyCircle);
-\endcode
-would make the \e MyCircle class accessable though the \c Circle type in QML whenever MyLib 1.0 to 1.5 is imported.
-
-
-\section1 Creating a new type of QML item in C++
-
-You can create a new type of QML item by:
-\list 1
-\o Creating a subclass of QFxItem,
-\o Adding Q_PROPERTYs appropriate for your item (see \l {properties}{Properties}),
-\o Reimplementing the relevant paint functions,
-\o Registering the type with the QML_DECLARE_TYPE and QML_DEFINE_TYPE macros  (see \l {register}{Register}).
-\endlist
-
-\section2 Creating a subclass of QFxItem
-
-To add a new type, you first must add a new C++ class derived from QFxItem.
-You may of course extend existing QFxItem subclasses.
-
-One existing subclass is QFxPaintedItem, which provides
-a simple cached-image painting model.
-
-\section2 Reimplementing paint functions
-
-\warning This section is out of date. Use the normal QGraphicsItem::paint function.
-
-Two alternative painters are available, offering
-different levels of performance and functionality:
-QPainter, GLPainter.
-
-You can choose to subclass QFxPaintedItem rather than QFxItem,
-and then implement the virtual method:
-
-\code
-    void drawContents(QPainter *painter, const QRect &rect);
-\endcode
-
-This paints into an offscreen pixmap which is then painted to the display (transformed,
-etc. as needed). The cost of this offscreen pixmap should be carefully considered, as
-should the specific performance of the painting done in the paint function.
-
-If you require more control, subclass QFxItem instead.
-QFxItem subclasses must implement both simple software canvas painting
-and GL painting:
-\list
-\o \c QFxItem::paintContents(QPainter &) for the simple software canvas,
-\o \c QFxItem::paintGLContents(GLPainter &) for OpenGL.
-\endlist
-
-See the documentation of those functions for detailed subclassing notes.
-
-*/
diff --git a/doc/src/declarative/ecmascriptblocks.qdoc b/doc/src/declarative/ecmascriptblocks.qdoc
new file mode 100644
index 0000000..4dde19d
--- /dev/null
+++ b/doc/src/declarative/ecmascriptblocks.qdoc
@@ -0,0 +1,74 @@
+/****************************************************************************
+**
+** 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 qmlecmascript.html
+\title ECMAScript Blocks
+
+QML encourages building UIs declaratively, using \l {Property Binding} and existing 
+\l {QML Elements}.  When imperative code is required to implementing more advanced 
+behavior, the \l Script element can be used to add ECMAScript code directly to a
+QML file, or to include an external ECMAScript file.
+
+The \l Script element is a QML language \e intrinsic.  It can be used anywhere in a
+QML file. \e except as the root element of a file or sub-component.  The included 
+ECMAScript is evaluated in a scope chain.  The \l {QML Scope} documentation covers
+the specifics of scoping in QML.  
+
+\section1 Inline ECMAScript
+
+\code
+Rectangle {
+    Script {
+        function factorial(var a) {
+            a = Integer(a);
+            if (a <= 0)
+                return 1;
+            else 
+                return a * factorial(a - 1);
+        }
+    }
+}
+\endcode
+
+\section1 Including a ECMAScript File
+
+*/
diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc
index 5408098..7a03685 100644
--- a/doc/src/declarative/examples.qdoc
+++ b/doc/src/declarative/examples.qdoc
@@ -41,7 +41,6 @@
 
 /*!
 \page qmlexamples.html
-\target qmlexamples
 \title QML Examples
 
 A \l {qmlviewer}{viewer} application is included that allows you to quickly explore many of the
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index bc18108..db35961 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -511,6 +511,18 @@ to be used in bindings should have a NOTIFY signal instead.
 \l {Extending QML -  Binding Example} shows the BirthdayParty example updated to
 include NOTIFY signals for use in binding.
 
+\section1 Binding and Script Properties
+
+While generally no changes are needed to a C++ class to use property
+binding, sometimes more advanced interaction between the binding engine and
+an object is desirable.  To facilitate this, there is a special exception
+in the bind engine for allowing an object to access the binding directly.
+
+If a binding is assigned to a property with a type of QmlBinding
+pointer (ie. \c {QmlBinding *}), each time the binding value changes,
+a QmlBinding instance is assigned to that property.  The QmlBinding instance 
+allows the object to read the binding and to evaluate the binding's current value.
+
 \section1 Extension Objects
 
 \snippet examples/declarative/extending/extended/example.qml 0
@@ -522,15 +534,59 @@ When integrating existing classes and technology into QML, their APIs will often
 need to be tweaked to fit better into the declarative environment.  Although
 the best results are usually obtained by modifying the original classes
 directly, if this is either not possible or is complicated by some other
-concerns extension objects allow limited extension possibilities without
+concerns, extension objects allow limited extension possibilities without
 direct modifications.
 
-Extension objects can only add properties.
+Extension objects are used to add additional properties to an existing type.  
+Extension objects can only add properties, not signals or methods.  An extended 
+type definition allows the programmer to supply an additional type - known as the 
+extension type - when registering the target class whose properties are 
+transparently merged with the original target class when used from within QML.
+
+An extension class is a regular QObject, with a constructor that takes a QObject 
+pointer.  When needed (extension classes are delay created until the first extended 
+property is accessed) the extension class is created and the target object is 
+passed in as the parent.  When an extended property on the original is accessed, 
+the appropriate property on the extension object is used instead.
+
+When an extended type is installed, one of the
+\code
+    #define QML_DEFINE_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QmlName,T, ExtendedT)
+    #define QML_DEFINE_EXTENDED_NOCREATE_TYPE(T, ExtendedT)
+\endcode
+macros should be used instead of the regular \c QML_DEFINE_TYPE or 
+\c QML_DEFINE_NOCREATE_TYPE.  The arguments are identical to the corresponding 
+non-extension object macro, except for the ExtendedT parameter which is the type 
+of the extension object.
 
 \section1 Optimization
 
-*/
+Often to develop high performance elements it is helpful to know more about the 
+status of the QML engine. For example, it might be beneficial to delay 
+initializing some costly data structures until after all the properties have been 
+set.
 
+The QML engine defines an interface class called QmlParserStatus, which contains a
+number of virtual methods that are invoked at various stages during component 
+instantiation.  To receive these notifications, an element implementation inherits 
+QmlParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro.  
+
+For example,
+
+\code
+class Example : public QObject, public QmlParserStatus
+{
+    Q_OBJECT
+    Q_INTERFACES(QmlParserStatus)
+public:
+    virtual void componentComplete()
+    {
+        qDebug() << "Woohoo!  Now to do my costly initialization";
+    }
+};
+\endcode
+
+*/
 
 /*!
 \page qml-extending-types.html
diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc
new file mode 100644
index 0000000..3d75706
--- /dev/null
+++ b/doc/src/declarative/network.qdoc
@@ -0,0 +1,53 @@
+/****************************************************************************
+**
+** 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 qmlnetwork.html
+\title Network Transparency
+
+\list
+\o Documents and script blocks can be fetched transparently over the network (blocking)
+\o Images, fonts can be fetched transparently over the network (non-blocking)
+\o Configuring the network access manager
+\o Relative URL resolution from ECMAScript/QML
+\endlist
+
+*/
diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc
new file mode 100644
index 0000000..4cf08d8
--- /dev/null
+++ b/doc/src/declarative/propertybinding.qdoc
@@ -0,0 +1,103 @@
+/****************************************************************************
+**
+** 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 propertybinding.html
+\title Property Binding
+
+Property binding is a declarative way of specifying the value of a property.  Binding allows
+a property's value to be expressed as an ECMAScript expression that defines the value relative
+to other property values or data accessible in the application.  The property value is 
+automatically kept up to date if the other properties or data values change.
+
+Property bindings are created implicitly in QML whenever an property is assigned an ECMAScript
+expression.  The following QML uses two property bindings to connect the size of the rectangle
+to that of \c otherItem.
+
+\code
+Rectangle {
+    width: otherItem.width
+    height: otherItem.height
+}
+\endcode
+
+QML extends a standards compliant ECMAScript engine, so any valid ECMAScript expression can be 
+used as a property binding.  Bindings can access object properties, make function calls and even
+use builtin ECMAScript objects like \e {Date} and \e {Math}.  Assigning a constant value to a 
+property can even be thought of as a binding - afterall, a constant is a valid ECMAScript 
+expression!  Here are some examples of more complex bindings:
+
+\code
+Rectangle {
+    Script {
+        function calculateMyWidth() {
+            return Math.max(otherItem.width, thirdItem.width);
+        }
+    }
+
+    anchors.centerIn: parent
+    width: Math.min(otherItem.width, 10)
+    height: calculateMyWidth()
+    color: { if (width > 10) "blue"; else "red" }
+}
+\endcode
+
+Being ECMAScript expressions, bindings are evaluated in a scope chain.  The \l {QML Scope} 
+documentation covers the specifics of scoping in QML.
+
+\list
+\o When does a binding not get updated?
+\o Scope
+\o Assigning a constant/other binding clears existing binding
+\o Loops
+\o Using model data
+\endlist
+
+\section1 Binding Element
+
+The implicit binding syntax shown previously is easy to use and works perfectly for most uses
+of bindings.  In some advanced cases, it is necessary to create bindings explicitly using the 
+\l Binding element.
+
+One such example is included in the \l {Passing Data Between C++ and QML} documentation.
+\sa {QML/C++ Data Binding}
+*/
+
diff --git a/doc/src/declarative/qmlforcpp.qdoc b/doc/src/declarative/qmlforcpp.qdoc
deleted file mode 100644
index 5378571..0000000
--- a/doc/src/declarative/qmlforcpp.qdoc
+++ /dev/null
@@ -1,713 +0,0 @@
-/****************************************************************************
-**
-** 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 qmlforcpp.html
-    \target qmlforcpp
-    \title QML for C++ Programmers
-
-    This page describes the QML format and how to use and extend it from C++.
-
-    The QML syntax declaratively describes how to construct an in memory
-    object tree.  QML is usually used to describe a visual scene graph
-    but it is not conceptually limited to this: the QML format is an abstract
-    description of \bold any object tree.
-
-    QML also includes property bindings.  Bindings are ECMAScript expressions
-    of a properties value.  Whenever the value of the expression changes -
-    either for the first time at startup or subsequently thereafter - the
-    property is automatically updated with the new value.
-
-    \tableofcontents
-
-    \section1 Loading and using QML Files
-
-    QmlComponent is used to load a QML file and to create object instances.
-
-    In QML a component is the unit of instantiation, and the most basic unit
-    of scope.  A component is like a template for how to construct an object
-    tree.  One component can create multiple instances of this tree, but the
-    template remains constant.
-
-    The following code uses the C++ interface to create 100 red rectangles
-    based on a simple declarative component description.
-
-    \code
-    QmlEngine engine;
-    QmlComponent redRectangle(&engine, "Rectangle { color: \"red\"; width: 100; height: 100 }");
-    for (int ii = 0; ii < 100; ++ii) {
-        QObject *rectangle = redRectangle.create();
-        // ... do something with the rectangle ...
-    }
-    \endcode
-
-    Each independent file describes a QML component, but it is also possible to
-    create sub-components within a QML file as will be shown later.
-
-    \section1 QML Format 101
-
-    This is some sample QML code.
-
-    \code
-    Image {
-        id: myRect
-        x: 10
-        y: 10
-        width: 100
-        height: 100
-        source: "background.png"
-
-        Text {
-            height: 50
-            width: 100
-            color: "white"
-            font.fontSize: 16
-            text: "Hello world!"
-        }
-    }
-    \endcode
-
-    The QML snippet shown above instantiates one \c Image instance and one
-    \c Text instance and sets properties on both.  \bold Everything in QML
-    ultimately comes down to either instantiating an object instance, or
-    assigning a property a value.  QML relies heavily on Qt's meta object system
-    and can only instantiate classes that derive from QObject.
-
-    In the above example, each property is placed on its own line.  You can
-    also place multiple properties on one line by separating them with a
-    semi-colon. The code below is equivalent to the example above.
-
-    \code
-    Image {
-        id: myRect
-        x: 10; y: 10; width: 100; height: 100
-        source: "background.png"
-        Text { height: 50; width: 100; color: "white"; font.fontSize: 16; text: "Hello world!" }
-    }
-    \endcode
-
-    QML can set properties that are more complex than just simple types like
-    integers and strings.  Properties can be object pointers or Qt interface
-    pointers or even lists of object or Qt interface pointers!  QML is typesafe,
-    and will ensure that only the valid types are assigned to properties.
-
-    Assigning an object to a property is as simple as assigning a basic
-    integer.  Attempting to assign an object to a property when type coercian
-    fails will produce an error.  The following shows an example of valid and of
-    invalid QML and the corresponding C++ classes.
-
-    \table
-    \row \o
-    \code
-    class Image : public QObject
-    {
-        ...
-        Q_PROPERTY(ImageFilter *filter READ filter WRITE setFilter)
-    };
-
-    class ImageFilter : public QObject
-    {
-        ...
-    };
-    \endcode
-    \o \code
-    // OK
-    Image {
-        filter: ImageFilter {}
-    }
-
-    // NOT OK: Image cannot be cast into ImageFilter
-    Image {
-        filter: Image {}
-    }
-    \endcode
-    \endtable
-
-    Classes can also define an optional default property.  The default property
-    is used for assignment if no explicit property has been specified.
-    Any object property can be the default, even complex properties like lists
-    of objects.  The default property of the \c Rect class is the \c children
-    property, a list of \c Item's.  In the following example, as both \c Image
-    and \c Text inherit from \c Item the \c Image and \c Text instances are
-    added to the parent's \c children property.
-
-    \code
-        Rectangle {
-            Image {}
-            Text {}
-        }
-    \endcode
-
-    Properties that return read-only object pointers can be used recursively.
-    This can be used, for example, to group properties together.  The
-    \c Text element has a \c font property that returns an object with a number
-    of sub-properties such as \c family, \c bold, \c italic and \c size.
-    QML makes it easy to interact with these grouped properties, as the
-    following shows - everything you would expect to work, just does.
-
-    \table
-    \row \o
-    \code
-    class Text : public ...
-    {
-        ...
-        Q_PROPERTY(Font *font READ font);
-    };
-    class Font : public QObject
-    {
-        ...
-        Q_PROPERTY(QString family READ family WRITE setFamily);
-        Q_PROPERTY(bool bold READ bold WRITE setBold);
-        Q_PROPERTY(bool italic READ italic WRITE setItalic);
-        Q_PROPERTY(int size READ size WRITE setSize);
-    };
-    \endcode
-    \o
-    \code
-        Text {
-            font.family: "helvetica"
-            font.pointSize: 12
-            font {
-                bold: true
-                italic: true
-            }
-        }
-    \endcode
-    \endtable
-
-    \section1 Defining QML Types
-
-    The QML engine has no intrinsic knowledge of any class types.  Instead
-    the programmer must define the C++ types, their corresponding QML
-    name, library namespace, and version availability.
-
-    \code
-    #define QML_DECLARE_TYPE(T)
-    #define QML_DEFINE_TYPE(URI,VMAJ,VFROM,VTO,QmlName,T)
-    \endcode
-
-    Adding these macros to your library or executable automatically makes the
-    C++ type \a T available from the declarative markup language under the
-    name \a QmlName.  Of course there's nothing stopping you using the same
-    name for both the C++ and the QML name!
-    Any type can be added to the QML engine using these macros.  The only
-    requirements are that \a T inherits QObject, is not abstract,
-    and that it has a default constructor.
-
-    \section1 Property Binding
-
-    Assigning constant values and trees to properties will only get you so
-    far.  Property binding allows a property's value to be dependant on the
-    value of other properties and data.  Whenever these dependencies change,
-    the property's value is automatically updated.
-
-    Property bindings are ECMAScript expressions and can be applied to any
-    object property.  C++ classes don't have to do anything special to get
-    binding support other than define appropriate properties.  When a non-literal
-    property assignment appears in a QML file, it is automatically treated as a
-    property binding.
-
-    Here's a simple example that stacks a red, blue and green rectangle.
-    Bindings are used to ensure that the height of each is kept equal to it's
-    parent's.  Were the root rectangle's height property to change, the child
-    rectangles height would be updated automatically.
-
-    \code
-        Rectangle {
-            color: "red"
-            width: 100
-            Rectangle {
-                color: "blue"
-                width: 50
-                height: parent.height
-                Rectangle {
-                    color: "green"
-                    width: 25
-                    height: parent.height
-                }
-            }
-        }
-    \endcode
-
-    Binding expressions execute in a context.  A context behaves as a scope and
-    defines how the expression resolves property and variable names.   Although
-    the two expressions in the last example are the same, the value of \c parent
-    resolves differently because each executes in a different context.  Although
-    QML generally takes care of everything for the programmer, a thorough
-    understanding of bind contexts is important in some of the more complex QML
-    structures.
-
-    Every expression is executed in a bind context, encapsulated by the
-    QmlContext C++ class.  As covered in the class documentation, a
-    bind context contains a map of names to values, and a list of default
-    objects.  When resolving a name, the name to value map is searched first.
-    If the name cannot be found, the default object's are iterated in turn and
-    the context attempts to resolve the name as a property of one of the default
-    objects.
-
-    There are generally two contexts involved in the execution of a binding.
-    The first is the "object context" - a bind context associated with the
-    closest instantiated object and containing just one default object, and
-    that's instantiated object itself.  The effect of the object
-    context is pretty simple - names in the binding expression resolve to
-    properties on the object first.  It is important to note - particularly in
-    the case of grouped properties - the object context is that of the
-    instantiated object,  the consequences of which are shown below.
-
-    \code
-    // OK                                  // NOT OK
-    Text {                                 Text {
-        font {                                 font {
-            bold: font.italic                      bold: italic
-        }                                      }
-    }                                      }
-    \endcode
-
-    The second context is the "component context".  Each QML component (and
-    consequently each QML file) is created in its own unique binding context.
-    Like the object context, the component context contains just one default
-    object - but in this case it is the component's root object.  An example
-    will illustrate best - the resultant text will read "background.png".
-
-    \code
-    Image {
-        source: "background.png"
-        Text {
-            text: source
-        }
-    }
-    \endcode
-
-    If the name is not found in either of these contexts, the context heirarchy
-    is searched parent-by-parent until the name is either found, or the
-    heirarchy is exhausted.
-
-    The first property binding example shown involved fixing the height of three
-    rectangles.  It did this by fixing the height of each rectangle to its
-    parent, rather than fixing them all to a single common point.  Here's the
-    example rewritten to do just that.
-
-    \code
-    Rectangle {
-        color: "red"
-        width: 100
-        Rectangle {
-            color: "blue"
-            width: 50
-            height: parent.height
-            Rectangle {
-                color: "green"
-                width: 25
-                height: parent.parent.height
-            }
-        }
-    }
-    \endcode
-
-    Clearly this sort of fragile relationship is undesirable and unmanageable -
-    moving the green rectangle to be a sibling of the blue or introducing a
-    further rectangle between the two would break the example.
-
-    To address this problem, QML includes a way to directly reference any object
-    within a component (or parent component for that matter), called "ids".
-    Developers assign an object an id, and can then reference it directly by
-    name.  Developers assign an object an id by setting the special \c id
-    property.  Every object automatically has this magical property (if the
-    object also has an actual property called \c id, that gets set too).  As
-    an id allows an object to be referenced directly, it must be unique within
-    a component.  By convention, id's should start with an uppercase letter.
-
-    \code
-    Rectangle {
-        id: root
-        color: "red"
-        width: greenRect.width + 75
-        height: root.height
-        Rectangle {
-            color: "blue"
-            width: greenRect.width + 25
-            Rectangle {
-                id: greenRect
-                color: "green"
-                width: 25
-                height: root.height
-            }
-        }
-    }
-    \endcode
-
-    To relate id's back to QmlContext, id's exist as properties on the
-    component context.
-
-    Bind expressions can reference any object property.  The QML bind engine
-    relies on the presence of the NOTIFY signal in the Q_PROPERTY declaration
-    on a class to alert it that a property's value has changed.  If this is
-    omitted, the bind expression can still access the property's value, but
-    the expression will not be updated if the value changes.  The following is
-    an example of a QML friendly property declaration.
-
-    \code
-    class Example : public QObject
-    {
-    Q_OBJECT
-    Q_PROPERTY(int sample READ sample WRITE setSample NOTIFY sampleChanged)
-    public:
-        int sample() const;
-        void setSample(int);
-    signals:
-        void sampleChanged(int);
-    };
-    \endcode
-
-    While generally no changes are needed to a C++ class to use property
-    binding, sometimes more advanced interaction between the binding engine and
-    an object is desirable.  To facilitate this, there is a special exception
-    in the bind engine for allowing an object to access the binding directly.
-
-    If a binding is assigned to a property with a type of QmlBindableValue
-    pointer (ie. QmlBindableValue *), each time the binding value changes,
-    a QmlBindableValue instance is assigned to that property.  The
-    QmlBindableValue instance allows the object to read the binding and to
-    evaluate the binding's current value.
-
-    \section1 Signal Properties
-
-    In addition to reading and writing regular properties, QML allows you to
-    easily associate ECMAScript with signals.  Consider the following example,
-    in which Button is a made-up type with a clicked() signal.
-
-    \code
-    Button {
-        text: "Hello world!"
-        onClicked: print(text)
-    }
-    \endcode
-
-    Clicking on the button causes "Hello world!" to be printed to the console
-    (or lost forever if you're running Windows).
-
-    Like properties, signals automatically become available in QML without
-    any additional work.  As illustrated signals are mapped into QML as special
-    "signal properties", using the name "on<Signal Name>" where the first
-    character of the signal's name is uppercased.  If more than one signal of
-    the same name is exist on a class, only the first is available (see the
-    \l Connection element for more general signal connections).
-
-    An important observation to make here is the lack of braces.  While both
-    property bindings and signal properties involve executing ECMAScript code,
-    property bindings dynamically update the property value (hence the braces),
-    whereas with signal properties the constant script "value" is actually
-    assigned to the signal property.  Trying to bind a value to a signal
-    property will not work!
-
-    Signal parameters are also available to the executing script, as shown
-    below, as long as you remember to name the parameters of your signal
-    in C++ (see QMetaMethod::parameterNames()).
-
-    \table
-    \row \o
-    \code
-    Example {
-        onDoSomething: for(var ii = 0; ii &lt; count; ++ii)
-                           print(message)
-    }
-    \endcode
-    \o
-    \code
-    class Example : public QObject
-    {
-    Q_OBJECT
-    signals:
-        void doSomething(int count, const QString &message);
-    };
-    \endcode
-    \endtable
-
-    Just like property bindings, signal scripts are executed in a context.  The
-    signal script context is identical in scope to the "object context" under
-    property binding, with the exception that it has the signal parameters
-    bound in.
-
-    In addition to scripts, it is possible to assign objects to signal properties.
-    This automatically connects the signal to the object's default method.  A
-    default method is defined just like a default property, though the special
-    "DefaultMethod" class info.
-
-    \code
-    Q_CLASSINFO("DefaultMethod", "myMethod(int)");
-    \endcode
-
-    This is useful in achieving several use cases, like that below which moves
-    the button when it is clicked.
-
-    \code
-    Button {
-        id: myButton
-        onClicked: NumberAnimation {
-            target: myButton
-            property: "x"
-            to: 100
-        }
-    }
-    \endcode
-
-    If the class itself actually defines a property called "on<Name>", this will
-    be assigned the string value and the signal handling behaviour will be
-    disabled.
-
-    \section1 Attached Properties
-
-    Attached properties allow unrelated types to annotate another type with some
-    additional properties.  Some APIs or operations are inherintly imperative,
-    and attached properties help out when translating these APIs into the
-    declarative QML language.
-
-    Qt's QGridLayout is one such example.
-
-    \code
-    QGridLayout {
-        QLabel {
-            QGridLayout.row: 0
-            QGridLayout.column: 0
-            text: "Name:"
-        }
-        QLineEdit {
-            QGridLayout.row: 0
-            QGridLayout.column: 1
-        }
-
-        QLabel {
-            QGridLayout.row: 1
-            QGridLayout.column: 0
-            text: "Occupation:"
-        }
-        QLineEdit {
-            QGridLayout.row: 1
-            QGridLayout.column: 1
-        }
-    }
-    \endcode
-
-    Attached properties are identified by the use of a type name, in the
-    case shown \c QGridLayout, as a grouped property specifier.  To prevent
-    ambiguity with actual class instantiations, attached properties must
-    always be specified to include a period but can otherwise be used just like
-    regular properties.
-
-    C++ types provide attached properties by declaring the public function \c qmlAttachedProperties like this example.
-
-    \table
-    \row \o
-    \code
-        static QObject *Type::qmlAttachedProperties(QObject *);
-    \endcode
-    \o
-    \code
-    class Example : public QObject
-    {
-        Q_OBJECT
-    public:
-        static QObject *qmlAttachedProperties(QObject *);
-    };
-    \endcode
-    \endtable
-
-    When an attached property is accessed, the QML engine will call this method
-    to create an attachment object, passing in the object instance that the
-    attached property applies to.  The attachment object should define all
-    the attached properties, and is generally parented to the provided object
-    instance to avoid memory leaks.  The QML engine does not saves this object,
-    so it is not necessary for the attached property function to ensure that
-    multiple calls for the same instance object return the same attached object.
-
-    While conceptually simple, implementing an attachment object is not quite
-    so easy.  The \c qmlAttachedProperties function is static - attachment
-    objects are not associated with any particular instance.  How the values
-    of the attached properties apply to the behaviour they are controlling is
-    entirely implementation dependent.  An additional consequence of this is
-    that \bold any object can attach \bold any attached property.  The following is
-    perfectly valid, although the attached property has no actual effect:
-
-    \code
-    FancyGridLayout {
-        Item {
-            Button {
-                QGridLayout.row: 1
-            }
-        }
-    }
-    \endcode
-
-    The property has no effect because the (made-up) FancyGridLayout type defines the meaning
-    of the \c row attached property only to apply to its direct children.  It
-    is possible that other types may have attached properties that affect
-    objects that aren't their direct children.
-
-    Attached properties are an advanced feature that should be used with
-    caution.
-
-    \note We may implement a convenience wrapper that makes using attached
-    properties easier for the common "attach to children" case.
-
-    \section1 Property Value Sources
-
-    Intrinsically, the QML engine can assign a property either a static value,
-    such as a number or an object tree, or a property binding.  It is possible for
-    advanced users to extend the engine to assign other "types" of values to
-    properties.  These "types" are known as property value sources.
-
-    Consider the following example.
-
-    \code
-    Rectangle {
-        x: NumberAnimation { running: true; repeat; true; from: 0; to: 100; }
-    }
-    \endcode
-
-    Here the \c x property of the rectangle will be animated from 0 to 100.
-    To support this, the NumberAnimation class inherits the
-    QmlPropertyValueSource class.  If a type inherits this class and is assigned
-    to a property for which type assignment would otherwise fail (ie. the
-    property itself doesn't have a type of QmlPropertyValueSource *), the QML
-    engine will automatically set the property as the target of the value
-    source.
-
-    \section1 Parser Status
-
-    Generally using QML is a breeze - you implement your classes in C++, add
-    the appropriate properties, signals and slots and off you go.  The QML
-    engine takes care of instantiating your classes and setting the properties
-    and everything works fine.
-
-    However, sometimes it is helpful to know a little more about the status of
-    the QML parser.  For example, it might be beneficial from a performance
-    standpoint to delay initializing some data structures until all the
-    properties have been set.
-
-    To assist with this, the QML engine defines an interface class called
-    QmlParserStatus.  The interface defines a number of virtual methods that are
-    invoked at various stages of the component instantiation.  To receive
-    these notifications, all a class has to do is to inherit the interface, and
-    notify the Qt meta system using the Q_INTERFACES() macro.  For example,
-
-    \code
-    class Example : public QObject, public QmlParserStatus
-    {
-        Q_OBJECT
-        Q_INTERFACES(QmlParserStatus)
-    public:
-        virtual void componentComplete()
-        {
-            qDebug() << "Woohoo!  Now to do my costly initialization";
-        }
-    };
-    \endcode
-
-    \section1 Extended Type Definitions
-
-    QML requires that types have the appropriate properties and signals to
-    work well within the declarative environment.  In the case of existing
-    types, it is sometimes necessary to add signals, properties or slots to a
-    target class to make it more QML friendly but the original type cannot be
-    modified.  For these cases, the QML engine supports extended type
-    definitions.
-
-    An extended type definition allows the programmer to supply an additional
-    type - known as the extension type - when registering the target class
-    whose properties, signals and slots are transparently merged with the
-    original target class when used from within QML.
-
-    An extension class is a regular QObject, with a constructor that takes a
-    QObject pointer.  When needed (extension classes are delay created
-    until the first extension attribute is accessed) the extension
-    class is created and the target object is passed in as the parent.  When
-    an extension attribute on the original is accessed, the appropriate signal,
-    property or slots on the extension object is used instead.
-
-    When an extended type is installed, the
-    \code
-        #define QML_DEFINE_EXTENDED_TYPE(T,QmlName,ExtendedTypeName)
-    \endcode
-    macro should be used instead of the regular \c QML_DEFINE_TYPE.
-
-    This example shows the addition of a read-only \c textLength property to
-    QLabel being implemented as an extension.
-
-    \table
-    \row
-    \o
-    \code
-    class QLabelExtension : public QObject
-    {
-        Q_OBJECT
-        Q_PROPERTY(int textLength READ textLength)
-    public:
-        QWidgetExtension(QObject *parent) : QObject(parent) {}
-        int textLength() const {
-            return static_cast<QLabel *>(parent())->text().count();
-        }
-    };
-    QML_DEFINE_EXTENDED_TYPE(QLabel,QLabel,QLabelExtension);
-    \endcode
-    \o
-    \code
-    QLabel {
-        id: label1
-        text: "Hello World!"
-    }
-    QLabel {
-        text: "label1 text length: " + label1.textLength
-    }
-    \endcode
-    \endtable
-
-    Attributes defined through extensions are inherited, just like attributes
-    defined on a normal class.  Any types that inherit from \c QLabel, will
-    also have the \c textLength property.  Derived types can include additional
-    extensions which are merged together, but only a single extension can be
-    specified for each single C++ class.
-
-    Extended type definitions can even be used to add an attached properties
-    function to a type - just declare the \c qmlAttachedProperties function on
-    the extension object.
-
-*/
-
diff --git a/doc/src/declarative/qmlmodels.qdoc b/doc/src/declarative/qmlmodels.qdoc
index d0a5464..6ebb734 100644
--- a/doc/src/declarative/qmlmodels.qdoc
+++ b/doc/src/declarative/qmlmodels.qdoc
@@ -71,14 +71,87 @@ or C++ (via QmlContext::setContextProperty(), for example).
 
 \section1 QML Data Models
 
-\list
-\o ListModel is a simple hierarchy of elements specified in QML.  The
+\section2 ListModel
+
+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
+
+\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
+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.
-\o VisualItemModel allows QML items to be provided as a model.  This model contains
+
+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.
-\endlist
+
+\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
@@ -92,11 +165,28 @@ both the data and delegate (its child items).  This model does not provide any r
 
 \section1 Other Data Models
 
-\list
-\o An Integer specifies a model containing the integer number of elements.
+
+\section2 An Integer
+
+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
+
+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.
-\endlist
 
 */
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index 1a13049..56f3252 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -40,57 +40,68 @@
 ****************************************************************************/
 
 /*!
-    \module QtDeclarative
-    \title QtDeclarative Module
-    \ingroup modules
+\module QtDeclarative
+\title QtDeclarative Module
+\ingroup modules
 
-    \brief The Qt Declarative module provides a declarative framework for building
-    highly dynamic and fluid applications.
+\brief The Qt Declarative module provides a declarative framework for building
+highly dynamic, custom UIs
 
-    Qt Declarative is targetted at the sorts of user
-    interface (and the sorts of hardware) in embedded devices such as phones, media
-    players, and set-top boxes. It is also appropriate for highly custom desktop
-    user interfaces, or special elements in more traditional desktop
-    user interfaces.
+Qt Declarative aids programmers and designers in building the animation rich, 
+highly fluid user interfaces that are becoming common in portable consumer 
+electronics devices, such as mobile phones, media players, set-top boxes and 
+netbooks.  The Qt Declarative module provides an engine for interpreting the 
+declarative QML language, and a rich set of \l {QML Elements} that can be used 
+from QML.
 
-    Building fluid applications is done declaratively, rather than procedurally.
-    That is, you specify \e what the UI should look like and how it should behave
-    in an declarative format called QML, rather than specifying step-by-step \e how to
-    build it in a language like C++ or JavaScript.  Specifying a UI declaratively
-    does not just include the layout of the interface items, but also the way each
-    individual item looks and behaves and the overall flow of the application.
+QML is an extension to \l {http://www.ecma-international.org/publications/standards/Ecma-262.htm}
+{ECMAScript}, that provides a mechanism to declaratively build an object tree 
+of \l {QML Elements}.  QML improves the integration between ECMAScript and Qt's
+existing QObject based type system, adds support for automatic 
+\l {Property Binding}s and provides \l {Network Transparency} at the language 
+level.
 
-    Getting Started:
-    \list
-    \o \l {Introduction to the QML language}
-    \o \l {tutorial}{Tutorial: 'Hello World'}
-    \o \l {tutorials-declarative-contacts.html}{Tutorial: 'Introduction to QML'}
-    \o \l {advtutorial.html}{Advanced Tutorial: 'Same Game'}
-    \o \l {qmlexamples}{Examples}
-    \o \l {qmlforcpp}{QML For C++ Programmers}
-    \endlist
+The \l {QML Elements} are a sophisticated set of graphical and behavioral building
+blocks.  \l {QML Elements} are combined together in QML files to build components 
+ranging in complexity from simple pushbuttons and sliders, to complete 
+internet-enabled applications like a \l {http://www.flickr.com}{flickr} photo browser.
 
-    Core QML Features:
-    \list
-    \o \l {binding}{Data Binding}
-    \o \l {qmlmodels}{Data Models}
-    \o \l {anchor-layout}{Anchor-based Layout}
-    \o \l {qmlanimation}{Animation}
-    \o \l {qmlmodules}{Modules}
-    \o \l {qmlfocus}{Keyboard Focus}
-    \o \l {Extending types from QML}
-    \endlist
+Qt Declarative builds on \l {QML for Qt programmers}{Qt's existing strengths}.
+QML can be be used to incrementally extend an existing application or to build 
+completely new applications.  QML is fully \l {Extending QML}{extensible from C++}.
 
-    QML Reference:
-    \list
-    \o \l {QML Format Reference}
-    \o \l {elements}{QML Elements}
-    \endlist
+\section1 Getting Started:
+\list
+\o \l {Introduction to the QML language}
+\o \l {tutorial}{Tutorial: 'Hello World'}
+\o \l {tutorials-declarative-contacts.html}{Tutorial: 'Introduction to QML'}
+\o \l {advtutorial.html}{Advanced Tutorial: 'Same Game'}
+\o \l {QML Examples}
+\endlist
 
-    C++ Reference:
-    \list
-    \o \l {Extending QML}
-    \o \l {qtbinding}{QML/C++ Data Binding}
-    \o \l {cppitem}{C++ Components}
-    \endlist
+\section1 Core QML Features:
+\list
+\o \l {Anatomy of a QML Document}
+\o \l {Property Binding}
+\o \l {ECMAScript Blocks}
+\o \l {Network Transparency}
+\o \l {qmlmodels}{Data Models}
+\o \l {anchor-layout}{Anchor-based Layout}
+\o \l {qmlanimation}{Animation}
+\o \l {qmlmodules}{Modules}
+\o \l {qmlfocus}{Keyboard Focus}
+\o \l {Extending types from QML}
+\endlist
+
+\section1 QML Reference:
+\list
+\o \l {QML Format Reference}
+\o \l {QML Elements}
+\endlist
+
+\section1 C++ Reference:
+\list
+\o \l {Extending QML}
+\o \l {qtbinding}{QML/C++ Data Binding}
+\endlist
 */
diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc
index 00c2d48..ea27d7e 100644
--- a/doc/src/declarative/qtprogrammers.qdoc
+++ b/doc/src/declarative/qtprogrammers.qdoc
@@ -65,8 +65,7 @@ QML provides direct access to the following concepts from Qt:
  \o Qt models - used directly in data binding (QAbstractItemModel and next generation QListModelInterface)
 \endlist
 
-Qt knowledge is \e required for \l {cppitem}{writing elements in C++}.
-
+Qt knowledge is \e required for \l {Extending QML}.
 
 \section1 QML Items compared with QWidgets
 
diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc
new file mode 100644
index 0000000..c35f3e3
--- /dev/null
+++ b/doc/src/declarative/scope.qdoc
@@ -0,0 +1,49 @@
+/****************************************************************************
+**
+** 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 qmlscope.html
+\title QML Scope
+
+QML is a \e {dynamically scoped} language.  \l {Property Binding}s and \l {ECMAScript Blocks} 
+are executed
+
+*/