Update 'hello world' tutorial.

9 files changed, 95 insertions, 242 deletions

diff --git a/doc/src/declarative/qmlintro.qdoc b/doc/src/declarative/qmlintro.qdoc
index e87b7a8..ef84b8e 100644
--- a/doc/src/declarative/qmlintro.qdoc
+++ b/doc/src/declarative/qmlintro.qdoc
@@ -153,7 +153,7 @@ Item {
 }
 \endcode
 
-\section3 The 'id' property
+\section3 The \c id property
 
 The \c id property is a special property of type \e id. Assigning an id to an object allows you
 to refer to it elsewhere.
diff --git a/doc/src/declarative/qmlreference.qdoc b/doc/src/declarative/qmlreference.qdoc
index bb0d61a..b26fc64 100644
--- a/doc/src/declarative/qmlreference.qdoc
+++ b/doc/src/declarative/qmlreference.qdoc
@@ -18,7 +18,7 @@
     Getting Started:
     \list
     \o \l {Introduction to the QML language} (in progress)
-    \o \l {tutorial}{Tutorial: 'Hello World'}
+    \o \l {tutorial}{Tutorial: 'Hello world!'}
     \o \l {tutorials-declarative-contacts.html}{Tutorial: 'Introduction to QML'}
     \o \l {qmlexamples}{Examples}
     \endlist
diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc
index a2a34b9..b59384c 100644
--- a/doc/src/declarative/tutorial.qdoc
+++ b/doc/src/declarative/tutorial.qdoc
@@ -2,7 +2,11 @@
 \page tutorial.html
 \title Tutorial
 
-This tutorial gives an introduction to QML. It doesn't cover everything; the emphasis is on teaching the key principles, and features are introduced as needed.
+This tutorial gives an introduction to QML. It doesn't cover everything; the emphasis is on teaching the key principles,
+and features are introduced as needed.
+
+Through the different steps of this tutorial we will learn about QML basic types, we will create our own QML component
+with properties and signals, and we will create a simple animation with the help of states and transitions.
 
 Chapter one starts with a minimal "Hello world" program and the following chapters introduce new concepts.
 
@@ -11,9 +15,9 @@ The tutorial's source code is located in the $QTDIR/examples/declarative/tutoria
 Tutorial chapters:
 
 \list
-\o \l {tutorial1}{Tutorial 1}
-\o \l {tutorial2}{Tutorial 2}
-\o \l {tutorial3}{Tutorial 3}
+\o \l {tutorial1}{Tutorial 1 - Basic Types}
+\o \l {tutorial2}{Tutorial 2 - QML Component}
+\o \l {tutorial3}{Tutorial 3 - States and Transitions}
 \endlist
 
 */
diff --git a/doc/src/declarative/tutorial1.qdoc b/doc/src/declarative/tutorial1.qdoc
index d4f1095..f46c59d 100644
--- a/doc/src/declarative/tutorial1.qdoc
+++ b/doc/src/declarative/tutorial1.qdoc
@@ -1,68 +1,46 @@
 /*!
 \page tutorial1.html
-\title Tutorial 1 - Hello World!
+\title Tutorial 1 - Basic Types
 \target tutorial1
 
-This first program is a simple "Hello world" example. The picture below is a screenshot of this program.
+This first program is a very simple "Hello world" example that introduces some basic QML concepts.
+The picture below is a screenshot of this program.
 
 \image declarative-tutorial1.png
 
 Here is the QML code for the application:
 
-\code
-Rectangle {
-    id: Page
-    width: 480
-    height: 200
-    color: "LightGrey"
-    Text {
-        id: HelloText
-        text: "Hello world!"
-        font.pointSize: 24
-        font.bold: true
-        y: 30
-        anchors.horizontalCenter: Page.horizontalCenter
-    }
-}
-\endcode
+\snippet examples/declarative/tutorials/helloworld/t1/tutorial1.qml 0
 
 \section1 Walkthrough
 
+\section2 Import
+
+First, we need to import the types that we need for this example. Most QML files will import the built-in QML
+types (like \l{Rectangle}, \l{Image}, ...) that come with Qt with:
+
+\snippet examples/declarative/tutorials/helloworld/t1/tutorial1.qml 3
+
 \section2 Rectangle element
 
-\code
-Rectangle {
-    id: Page
-    width: 480
-    height: 200
-    color: "LightGrey"
-}
-\endcode
+\snippet examples/declarative/tutorials/helloworld/t1/tutorial1.qml 1
 
-First, we declare a root element of type \l Rectangle. It is one of the basic building blocks you can use to create an application in QML.
-We give it an id to be able to refer to it later. In this case, we call it \e Page. We also set the \c width, \c height and \c color properties.
-The \l Rectangle element contains many other properties (such as \c x and \c y), but these are left at their default values.
+We declare a root element of type \l{Rectangle}. It is one of the basic building blocks you can use to create an application in QML.
+We give it an \c{id} to be able to refer to it later. In this case, we call it \e page. We also set the \c width, \c height and \c color properties.
+The \l{Rectangle} element contains many other properties (such as \c x and \c y), but these are left at their default values.
 
 \section2 Text element
 
-\code
-Text {
-    id: HelloText
-    text: "Hello world!"
-    font.pointSize: 24
-    font.bold: true
-    y: 30
-    anchors.horizontalCenter: Page.horizontalCenter
-}
-\endcode
+\snippet examples/declarative/tutorials/helloworld/t1/tutorial1.qml 2
 
-We add a text element as a child of our root element to display the text 'Hello world!'.
+We add a \l Text element as a child of our root element that will display the text 'Hello world!'.
 
 The \c y property is used to position the text vertically at 30 pixels from the top of its parent.
 
-The \c font.pointSize and \c font.bold properties are related to fonts and use the \e 'dot' notation.
+The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{Dot Properties}{dot notation}.
 
-The \c anchors.horizontalCenter property refers to the horizontal center of an element. In this case, we specify that our text element should be horizontally centered in the \e Page element.
+The \c anchors.horizontalCenter property refers to the horizontal center of an element.
+In this case, we specify that our text element should be horizontally centered in the \e page element (see \l{anchor-layout}{Anchor-based Layout}).
 
 \section2 Viewing the example
 
diff --git a/doc/src/declarative/tutorial2.qdoc b/doc/src/declarative/tutorial2.qdoc
index c6fd06b..21b5ebd 100644
--- a/doc/src/declarative/tutorial2.qdoc
+++ b/doc/src/declarative/tutorial2.qdoc
@@ -1,130 +1,69 @@
 /*!
 \page tutorial2.html
-\title Tutorial 2 - Some colors
+\title Tutorial 2 - QML Component
 \target tutorial2
 
 This chapter adds a color picker to change the color of the text.
 
 \image declarative-tutorial2.png
 
-Our color picker is made of many cells with different colors. To avoid writing the same code many times, we first create a new \c Cell component with a color property (see \l components).
+Our color picker is made of six cells with different colors.
+To avoid writing the same code multiple times, we first create a new \c Cell component.
+A component provides a way of defining a new type that we can re-use in other QML files.
+A QML component is like a black-box and interacts with the outside world through properties, signals and slots and is generally
+defined in its own QML file (for more details, see \l components).
 
 Here is the QML code for \c Cell.qml:
 
-\code
-Item {
-    property var color
-
-    id: CellContainer
-    width: 40
-    height: 25
-
-    Rectangle {
-        anchors.fill: parent
-        color: CellContainer.color
-    }
-    MouseRegion {
-        anchors.fill: parent
-        onClicked: { HelloText.color = CellContainer.color }
-    }
-}
-\endcode
-
-Then, we use our \c Cell component to create the color picker in the QML code for the application:
-
-\code
-Rectangle {
-    id: Page
-    width: 480
-    height: 200
-    color: "LightGrey"
-    Text {
-        id: HelloText
-        text: "Hello world!"
-        font.pointSize: 24
-        font.bold: true
-        y: 30
-        anchors.horizontalCenter: Page.horizontalCenter
-    }
-    Grid {
-        id: ColorPicker
-        x: 0
-        anchors.bottom: Page.bottom
-        width: 120; height: 50
-        rows: 2; columns: 3
-        Cell { color: "#ff0000" }
-        Cell { color: "#00ff00" }
-        Cell { color: "#0000ff" }
-        Cell { color: "#ffff00" }
-        Cell { color: "#00ffff" }
-        Cell { color: "#ff00ff" }
-    }
-}
-\endcode
+\snippet examples/declarative/tutorials/helloworld/t2/Cell.qml 0
 
 \section1 Walkthrough
 
 \section2 The Cell Component
 
-\code
-Item {
-    id: CellContainer
-    width: 40
-    height: 25
-}
-\endcode
+\snippet examples/declarative/tutorials/helloworld/t2/Cell.qml 1
 
-The root element of our component is an \c Item. It is the most basic element in QML and is often used as a container for other elements.
+The root element of our component is an \l Item with the \c id \e container.
+An \l Item is the most basic visual element in QML and is often used as a container for other elements.
 
-\code
-property var color
-\endcode
+\snippet examples/declarative/tutorials/helloworld/t2/Cell.qml 4
 
-We declare a \c color property. This property is accessible from  \e outside our component, this allows us to instantiate the cells with different colors.
+We declare a \c color property. This property is accessible from  \e outside our component, this allows us
+to instantiate the cells with different colors.
+This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Properties}).
 
-\code
-Rectangle {
-    anchors.fill: parent
-    color: CellContainer.color
-}
-\endcode
+\snippet examples/declarative/tutorials/helloworld/t2/Cell.qml 5
 
-Our cell component is basically a colored rectangle.
+We want our component to also have a signal that we call \e clicked with a \e color parameter.
+We will use this signal to change the color of the text in the main QML file later.
 
-The \c anchors.fill property is a convenient way to set the size of an element. In this case the \c Rectangle will have the same size as its parent.
+\snippet examples/declarative/tutorials/helloworld/t2/Cell.qml 2
 
-We bind the \c color property of this \c Rectangle to the color property of our component.
+Our cell component is basically a colored rectangle with the \c id \e rectangle.
 
-\code
-MouseRegion {
-    anchors.fill: parent
-    onClicked: { HelloText.color = CellContainer.color }
-}
-\endcode
+The \c anchors.fill property is a convenient way to set the size of an element.
+In this case the rectangle will have the same size as its parent (see \l{anchor-layout}{Anchor-based Layout}).
 
-In order to change the color of the text when clicking on a cell, we create a \c MouseRegion element with the same size as its parent.
+\snippet examples/declarative/tutorials/helloworld/t2/Cell.qml 3
 
-The \c onClicked property sets the \c color property of the element named \e HelloText to our cell color.
+In order to change the color of the text when clicking on a cell, we create a \l MouseRegion element with
+the same size as its parent.
+
+A \l MouseRegion defines a signal called \e clicked.
+When this signal is triggered we want to emit our own \e clicked signal with the color as parameter.
 
 \section2 The main QML file
 
-\code
-Grid {
-    id: ColorPicker
-    x: 0
-    anchors.bottom: Page.bottom
-    width: 120; height: 50
-    rows: 2; columns: 3
-    Cell { color: "#ff0000" }
-    Cell { color: "#00ff00" }
-    Cell { color: "#0000ff" }
-    Cell { color: "#ffff00" }
-    Cell { color: "#00ffff" }
-    Cell { color: "#ff00ff" }
-}
-\endcode
-
-In the main QML file, the only thing we have to do is to create a color picker by putting 6 cells with different colors in a grid.
+In our main QML file, we use our \c Cell component to create the color picker:
+
+\snippet examples/declarative/tutorials/helloworld/t2/tutorial2.qml 0
+
+We create the color picker by putting 6 cells with different colors in a grid.
+
+\snippet examples/declarative/tutorials/helloworld/t2/tutorial2.qml 1
+
+When the \e clicked signal of our cell is triggered, we want to set the color of the text to the color passed as a parameter.
+We can react to any signal of our component through a property of the name \e 'onSignalName' (see \l{Signal Handlers}).
 
 [Previous: \l tutorial1] [Next: \l tutorial3]
 
diff --git a/doc/src/declarative/tutorial3.qdoc b/doc/src/declarative/tutorial3.qdoc
index a0d842c..21b7ae5 100644
--- a/doc/src/declarative/tutorial3.qdoc
+++ b/doc/src/declarative/tutorial3.qdoc
@@ -1,111 +1,43 @@
-/*! 
+/*!
 \page tutorial3.html
-\title Tutorial 3 - States
+\title Tutorial 3 - States and Transitions
 \target tutorial3
 
-In this chapter, we make this example a little bit more dynamic by introducing states.
+In this chapter, we make this example a little bit more dynamic by introducing states and transitions.
 
-We want our text to jump at the bottom of the screen and become red when clicked.
+We want our text to move to the bottom of the screen, rotate and become red when clicked.
 
 \image declarative-tutorial3_animation.gif
 
 Here is the QML code:
 
-\code
-Rectangle {
-    id: Page
-    width: 480
-    height: 200
-    color: "LightGrey"
-    Text {
-        id: HelloText
-        text: "Hello world!"
-        font.pointSize: 24
-        font.bold: true
-        y: 30
-        anchors.horizontalCenter: Page.horizontalCenter
-        states: [
-            State {
-                name: "down"
-                when: MouseRegion.pressed == true
-                PropertyChanges { target: HelloText; y: 160; color: "red" }
-            }
-        ]
-        transitions: [
-            Transition {
-                from: "*"
-                to: "down"
-                reversible: true
-                ParallelAnimation {
-                    NumberAnimation {
-                        properties: "y"
-                        duration: 500
-                        easing: "easeOutBounce"
-                    }
-                    ColorAnimation { property: "color"; duration: 500 }
-                }
-            }
-        ]
-    }
-    MouseRegion { id: MouseRegion; anchors.fill: HelloText }
-    Grid {
-        id: ColorPicker
-        x: 0
-        anchors.bottom: Page.bottom
-        width: 120; height: 50
-        rows: 2; columns: 3
-        Cell { color: "#ff0000" }
-        Cell { color: "#00ff00" }
-        Cell { color: "#0000ff" }
-        Cell { color: "#ffff00" }
-        Cell { color: "#00ffff" }
-        Cell { color: "#ff00ff" }
-    }
-}
-\endcode
+\snippet examples/declarative/tutorials/helloworld/t3/tutorial3.qml 0
 
 \section1 Walkthrough
 
-\code
-states: [
-    State {
-        name: "down"
-        when: MouseRegion.pressed == true
-        PropertyChanges { target: HelloText; y: 160; color: "red" }
-    }
-]
-\endcode
-
-First, we create a new state \e down for our text element. This state will be activated when MouseRegion is pressed, and deactivated when it is released.
-
-The \e down state includes a set of property changes from our implicit \e {default state} (the items as they were initially defined in the QML). Specifically, we set the \c y property of the text to 160 and the \c color to red.
-
-\code
-Transition {
-    from: "*"
-    to: "down"
-    reversible: true
-}
-\endcode
-
-Because we don't want the text to appear at the bottom instantly but rather move smoothly, we add a transition between our two states.
-
-\c from and \c to define the states between which the transition will run. In this case, we want a transition from any state to our \e down state.
-
-Because we want the same transition to be run in reverse when changing back from the \e down state to the default state, we set \c reversible to \c true. This is equivalent to writing the two transitions separately.
-
-\code
-ParallelAnimation {
-    NumberAnimation {
-        properties: "y"
-        duration: 500
-        easing: "easeOutBounce"
-    }
-    ColorAnimation { property: "color"; duration: 500 }
-}
-\endcode
-
-The \c ParallelAnimation element makes sure that the two animations (color and position) will start at the same time. We could also run them one after the other by using \c SequentialAnimation instead.
+\snippet examples/declarative/tutorials/helloworld/t3/tutorial3.qml 2
+
+First, we create a new \e down state for our text element.
+This state will be activated when the \l MouseRegion is pressed, and deactivated when it is released.
+
+The \e down state includes a set of property changes from our implicit \e {default state}
+(the items as they were initially defined in the QML).
+Specifically, we set the \c y property of the text to \c 160, the rotation to \c 180 and the \c color to red.
+
+\snippet examples/declarative/tutorials/helloworld/t3/tutorial3.qml 3
+
+Because we don't want the text to appear at the bottom instantly but rather move smoothly,
+we add a transition between our two states.
+
+\c from and \c to define the states between which the transition will run.
+In this case, we want a transition from the default state to our \e down state.
+
+Because we want the same transition to be run in reverse when changing back from the \e down state to the default state,
+we set \c reversible to \c true.
+This is equivalent to writing the two transitions separately.
+
+The \l ParallelAnimation element makes sure that the two types of animations (number and color) start at the same time.
+We could also run them one after the other by using \l SequentialAnimation instead.
 
 For more details on states and transitions, see \l {states-transitions}{States and Transitions}.
 
diff --git a/doc/src/images/declarative-tutorial1.png b/doc/src/images/declarative-tutorial1.png
index ea0000f..c9d3844 100644
--- a/doc/src/images/declarative-tutorial1.png
+++ b/doc/src/images/declarative-tutorial1.png
diff --git a/doc/src/images/declarative-tutorial2.png b/doc/src/images/declarative-tutorial2.png
index 0538451..835484a 100644
--- a/doc/src/images/declarative-tutorial2.png
+++ b/doc/src/images/declarative-tutorial2.png
diff --git a/doc/src/images/declarative-tutorial3_animation.gif b/doc/src/images/declarative-tutorial3_animation.gif
index d2d4c63..80b78de 100644
--- a/doc/src/images/declarative-tutorial3_animation.gif
+++ b/doc/src/images/declarative-tutorial3_animation.gif