1 files changed, 351 insertions, 0 deletions
diff --git a/doc/src/declarative/qdeclarativeintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc
new file mode 100644
index 0000000..4d05a8c
--- /dev/null
+++ b/doc/src/declarative/qdeclarativeintro.qdoc
@@ -0,0 +1,351 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qdeclarativeintroduction.html
+\title Introduction to the QML language
+
+\tableofcontents
+
+QML is a declarative language designed to describe the user interface of a
+program: both what it looks like, and how it behaves. In QML, a user
+interface is specified as a tree of objects with properties.
+
+This introduction is meant for those with little or no programming
+experience. JavaScript is used as a scripting language in QML, so you may want
+to learn a bit more about it (\l{JavaScript: The Definitive Guide}) before diving
+deeper into QML. It's also helpful to have a basic understanding of other web
+technologies like HTML and CSS, but it's not required.
+
+\section1 Basic QML Syntax
+
+QML looks like this:
+
+\code
+Rectangle {
+    width: 200
+    height: 200
+    color: "white"
+    Image {
+        source: "pics/logo.png"
+        anchors.centerIn: parent
+    }
+}
+\endcode
+
+Objects are specified by their type, followed by a pair of braces. Object
+types always begin with a capital letter. In the above example, there are
+two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify
+information about the object, such as its properties.
+
+Properties are specified as \c {property: value}. In the above example, we 
+can see the Image has a property named \c source, which has been assigned the 
+value \c "pics/logo.png". The property and its value are separated by a colon.
+
+Properties can be specified one-per-line:
+
+\code
+Rectangle {
+    width: 100
+    height: 100
+}
+\endcode
+
+or you can put multiple properties on a single line:
+
+\code
+Rectangle { width: 100; height: 100 }
+\endcode
+
+When multiple property/value pairs are specified on a single line, they
+must be separated by a semicolon.
+
+\section1 Expressions
+
+In addition to assigning values to properties, you can also assign
+expressions written in JavaScript.
+
+\code
+Rotation {
+    angle: 360 * 3
+}
+\endcode
+
+These expressions can include references to other objects and properties, in which case
+a \e binding is established: when the value of the expression changes, the property the
+expression has been assigned to is automatically updated to that value.
+
+\code
+Item {
+    Text {
+        id: text1
+        text: "Hello World"
+    }
+    Text {
+        id: text2
+        text: text1.text
+    }
+}
+\endcode
+
+In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed,
+\c text2 is automatically changed to the same value.
+
+Note that to refer to other objects, we use their \e id values. (See below for more
+information on the \e id property.)
+
+\section1 QML Comments
+
+Commenting in QML is similar to JavaScript.
+\list
+\o Single line comments start with // and finish at the end of the line.
+\o Multiline comments start with /* and finish with *\/
+\endlist
+
+\quotefile doc/src/snippets/declarative/comments.qml
+
+Comments are ignored by the engine. The are useful for explaining what you
+are doing: for referring back to at a later date, or for others reading
+your QML files.
+
+Comments can also be used to prevent the execution of code, which is
+sometimes useful for tracking down problems.
+
+\code
+Text {
+    text: "Hello world!"
+    //opacity: 0.5
+}
+\endcode
+
+In the above example, the Text object will have normal opacity, since the
+line opacity: 0.5 has been turned into a comment.
+
+\section1 Properties
+\target intro-properties
+
+\section2 Property naming
+
+Properties begin with a lowercase letter (with the exception of \l{Attached Properties}).
+
+\section2 Property types
+
+QML supports properties of many types (see \l{QML Basic Types}). The basic types include int,
+real, bool, string, color, and lists.
+
+\code
+Item {
+    x: 10.5             // a 'real' property
+    ...
+    state: "details"    // a 'string' property
+    focus: true         // a 'bool' property
+}
+\endcode
+
+QML properties are what is known as \e typesafe. That is, they only allow you to assign a value that
+matches the property type. For example, the \c x property of item is a real, and if you try to assign
+a string to it you will get an error.
+
+\badcode
+Item {
+    x: "hello"  // illegal!
+}
+\endcode
+
+\section3 The \c id property
+
+Each object can be given a special unique property called an \e id. Assigning an id enables the object
+to be referred to by other objects and scripts.
+
+The first Rectangle element below has an \e id, "myRect". The second Rectange element defines its
+own width by referring to \tt myRect.width, which means it will have the same \tt width
+value as the first Rectangle element.
+
+\code
+Item {
+    Rectangle {
+        id: myRect
+        width: 100
+        height: 100
+    }
+    Rectangle {
+        width: myRect.width
+        height: 200
+    }
+}
+\endcode
+
+Note that an \e id must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores.
+
+
+\section2 List properties
+
+List properties look like this:
+
+\code
+Item {
+    children: [
+        Image {},
+        Text {}
+    ]
+}
+\endcode
+
+The list is enclosed in square brackets, with a comma separating the
+list elements. In cases where you are only assigning a single item to a
+list, you can omit the square brackets:
+
+\code
+Image {
+    children: Rectangle {}
+}
+\endcode
+
+\section2 Default properties
+
+Each object type can specify one of its list or object properties as its default property.
+If a property has been declared as the default property, the property tag can be omitted.
+
+For example this code:
+\code
+State {
+    changes: [
+        PropertyChanges {},
+        PropertyChanges {}
+    ]
+}
+\endcode
+
+can be simplified to:
+
+\code
+State {
+    PropertyChanges {}
+    PropertyChanges {}
+}
+\endcode
+
+because \c changes is the default property of the \c State type.
+
+\section2 Grouped Properties
+\target dot properties
+
+In some cases properties form a logical group and use a 'dot' or grouped notation
+to show this.
+
+Grouped properties can be written like this:
+\qml
+Text {
+    font.pixelSize: 12
+    font.bold: true
+}
+\endqml
+
+or like this:
+\qml
+Text {
+    font { pixelSize: 12; bold: true }
+}
+\endqml
+
+In the element documentation grouped properties are shown using the 'dot' notation.
+
+\section2 Attached Properties
+\target attached-properties
+
+Some objects attach properties to another object.  Attached Properties
+are of the form \e {Type.property} where \e Type is the type of the
+element that attaches \e property.
+
+For example:
+\code
+Component {
+    id: myDelegate
+    Text {
+        text: "Hello"
+        color: ListView.isCurrentItem ? "red" : "blue"
+    }
+}
+ListView {
+    delegate: myDelegate
+}
+\endcode
+
+The \l ListView element attaches the \e ListView.isCurrentItem property
+to each delegate it creates.
+
+Another example of attached properties is the \l Keys element which
+attaches properties for handling key presses to
+any visual Item, for example:
+
+\code
+Item {
+    focus: true
+    Keys.onSelectPressed: console.log("Selected")
+}
+\endcode
+
+\section2 Signal Handlers
+
+Signal handlers allow actions to be taken in reponse to an event.  For instance,
+the \l MouseArea element has signal handlers to handle mouse press, release
+and click:
+
+\code
+MouseArea {
+    onPressed: console.log("mouse button pressed")
+}
+\endcode
+
+All signal handlers begin with \e "on".
+
+Some signal handlers include an optional parameter, for example
+the MouseArea onPressed signal handler has a \e mouse parameter:
+
+\code
+MouseArea {
+    acceptedButtons: Qt.LeftButton | Qt.RightButton
+    onPressed: if (mouse.button == Qt.RightButton) console.log("Right mouse button pressed")
+}
+\endcode
+
+
+*/