Doc

7 files changed, 357 insertions, 34 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 79ba6ac..94465a1 100644
--- a/doc/src/declarative/binding.qdoc
+++ b/doc/src/declarative/binding.qdoc
@@ -40,39 +40,6 @@
 ****************************************************************************/
 
 /*!
-\page binding.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.
-
-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/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/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/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index d60f4ed..fa5c0e6 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -71,7 +71,10 @@
 
     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}
@@ -83,7 +86,7 @@
     QML Reference:
     \list
     \o \l {QML Format Reference}
-    \o \l {elements}{QML Elements}
+    \o \l {QML Elements}
     \endlist
 
     C++ Reference:
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
+
+*/