Doc

1 files changed, 188 insertions, 0 deletions

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
+*/