Merge branch 'kinetic-declarativeui' of git@scm.dev.nokia.troll.no:qt/kinetic into kinetic-declarativeui

Conflicts:
	doc/src/declarative/tutorial1.qdoc
	doc/src/declarative/tutorial2.qdoc
	doc/src/declarative/tutorial3.qdoc

1 files changed, 37 insertions, 98 deletions

diff --git a/doc/src/declarative/tutorial2.qdoc b/doc/src/declarative/tutorial2.qdoc
index c97fddf..a3154de 100644
--- a/doc/src/declarative/tutorial2.qdoc
+++ b/doc/src/declarative/tutorial2.qdoc
@@ -1,130 +1,69 @@
 /*!
 \page tutorial2.html
 \target tutorial2
-\title Tutorial 2 - Some colors
+\title Tutorial 2 - QML Component
 
 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/Cell.qml 0
 
 \section1 Walkthrough
 
 \section2 The Cell Component
 
-\code
-Item {
-    id: CellContainer
-    width: 40
-    height: 25
-}
-\endcode
+\snippet examples/declarative/tutorials/helloworld/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/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/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/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/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/tutorial2.qml 0
+
+We create the color picker by putting 6 cells with different colors in a grid.
+
+\snippet examples/declarative/tutorials/helloworld/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]