Doc

4 files changed, 189 insertions, 75 deletions

diff --git a/doc/src/declarative/anatomy.qdoc b/doc/src/declarative/anatomy.qdoc
deleted file mode 100644
index f816464..0000000
--- a/doc/src/declarative/anatomy.qdoc
+++ /dev/null
@@ -1,74 +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 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/pics/anatomy-component.png b/doc/src/declarative/pics/anatomy-component.png
new file mode 100644
index 0000000..70ed983
--- /dev/null
+++ b/doc/src/declarative/pics/anatomy-component.png
diff --git a/doc/src/declarative/qmldocument.qdoc b/doc/src/declarative/qmldocument.qdoc
new file mode 100644
index 0000000..84e7926
--- /dev/null
+++ b/doc/src/declarative/qmldocument.qdoc
@@ -0,0 +1,188 @@
+/****************************************************************************
+**
+** 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 qmldocuments.html
+\title QML Documents
+
+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.
+
+A simple QML document looks like this:
+
+\code
+import Qt 4.6
+
+Rectangle {
+    width: 240; height: 320; 
+
+    resources: [
+        Component {
+            id: contactDelegate
+            Text {
+                text: modelData.firstName + " " + modelData.lastName
+            }
+        }
+    ]
+
+    ListView {
+        anchors.fill: parent
+        model: contactModel
+        delegate: contactDelegate
+    } 
+}
+\endcode
+
+A QML document always begins with one or more import statements.  To prevent elements 
+introduced in later versions from affecting existing QML programs, the element types 
+available within a document are controlled by the imported QML \l {Modules}.  That is, 
+QML is a \e versioned language.
+
+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. \c import statements 
+do not "include" code in the document, but instead instruct the QML runtime on how to 
+resolve type references found in the document.  Any type reference present in a QML 
+document - such as \c Rectangle and \c ListView - including those made within an 
+\l {ECMAScript Block} or \l {Property Binding}s, are \e resolved based exclusively on the 
+import statements.  QML does not import any modules by default, so at least one \c import
+statement must be present or no elements will be available!
+
+A QML document defines a single, top-level \l {QmlComponent}{QML component}.  A QML component 
+is a template that is interpreted by the QML runtime to create an object with some predefined 
+behaviour.  As it is a template, a single QML component can be "run" multiple times to 
+produce several objects, each of which are said to be \e instances of the component.  
+
+Once created, instances are not dependent on the component that created them, so they can 
+operate on independent data.  Here is an example of a simple "button" component that is 
+instantiated four times, each with a different value for its \c text property.
+
+\table
+\row
+\o
+\raw HTML
+<table><tr><td>
+\endraw
+\code
+import Qt 4.6
+
+BorderImage {
+    property alias text: textElement.text
+    width: 100; height: 30; source: "images/toolbutton.sci"
+
+    Text {
+        id: textElement
+        anchors.centerIn: parent
+        font.pointSize: 20
+        style: Text.Raised
+        color: "white"
+    }
+}
+\endcode
+\raw HTML
+</td> <td>
+\endraw
+\image anatomy-component.png
+\raw HTML
+</td> </tr> </table>
+\endraw
+\endtable
+
+In addition to the top-level component that all QML documents define, documents may also 
+include additional \e inline components.  Inline components are declared  using the 
+\l Component element, as can be seen in the first example above.  Inline components share 
+all the characteristics of regular top-level components and use the same \c import list as their
+containing QML document.  Components are one of the most basic building blocks in QML, and are 
+frequently used as "factories" by other elements.  For example, the \l ListView element uses the
+\c delegate component as the template for instantiating list items - each list item is just a
+new instance of the component with the item specific data set appropriately.
+
+Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a 
+property.   \l Component objects may also have an object id.  In the first example on this page,
+the inline component is added to the \l Rectangle's \c resources list, and then 
+\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate 
+property.  While using property binding allows the \l Component object to be shared (for example,
+if the QML document contained multiple \l ListView's with the same delegate), in this case the 
+\l Component could have been assigned directly to the \l ListView's \c delegate.  The QML 
+language even contains a syntactic optimization when assigning directly to a component property 
+for this case where it will automatically insert the \l Component tag.
+
+These final two examples are behaviorally identical to the original document.
+
+\table
+\row
+\o
+\code
+import Qt 4.6
+
+Rectangle {
+    width: 240; height: 320; 
+
+    ListView {
+        anchors.fill: parent
+        model: contactModel
+        delegate: Component {
+            Text {
+                text: modelData.firstName + " " + modelData.lastName
+            }
+        }
+    } 
+}
+\endcode
+\o
+\code
+import Qt 4.6
+
+Rectangle {
+    width: 240; height: 320; 
+
+    ListView {
+        anchors.fill: parent
+        model: contactModel
+        delegate: Text {
+            text: modelData.firstName + " " + modelData.lastName
+        }
+    } 
+}
+\endcode
+\endtable
+
+\sa QmlComponent
+*/
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index 56f3252..bd50034 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -81,7 +81,7 @@ completely new applications.  QML is fully \l {Extending QML}{extensible from C+
 
 \section1 Core QML Features:
 \list
-\o \l {Anatomy of a QML Document}
+\o \l {QML Documents}
 \o \l {Property Binding}
 \o \l {ECMAScript Blocks}
 \o \l {Network Transparency}