1 files changed, 226 insertions, 0 deletions
diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc
new file mode 100644
index 00000000..91db7be4
--- /dev/null
+++ b/doc/src/declarative/tutorial.qdoc
@@ -0,0 +1,226 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 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:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qml-tutorial.html
+\title QML Tutorial
+\brief An introduction to the basic concepts and features of QML.
+\nextpage QML Tutorial 1 - Basic Types
+
+This tutorial gives an introduction to QML, the mark up language for Qt Quick. 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.
+
+The tutorial's source code is located in the $QTDIR/examples/declarative/tutorials/helloworld directory.
+
+Tutorial chapters:
+
+\list 1
+\o \l {QML Tutorial 1 - Basic Types}{Basic Types}
+\o \l {QML Tutorial 2 - QML Components}{QML Components}
+\o \l {QML Tutorial 3 - States and Transitions}{States and Transitions}
+\endlist
+
+*/
+
+/*!
+\page qml-tutorial1.html
+\title QML Tutorial 1 - Basic Types
+\contentspage QML Tutorial
+\previouspage QML Tutorial
+\nextpage QML Tutorial 2 - QML Component
+
+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:
+
+\snippet examples/declarative/tutorials/helloworld/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, using:
+
+\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 3
+
+\section2 Rectangle element
+
+\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 1
+
+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 "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
+
+\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 2
+
+We add a \l Text element as a child of the root Rectangle element that displays 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 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}).
+
+The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{dot properties}{dot notation}.
+
+
+\section2 Viewing the example
+
+To view what you have created, run the \l{QML Viewer} tool (located in the \c bin directory) with your filename as the first argument.
+For example, to run the provided completed Tutorial 1 example from the install location, you would type:
+
+\code
+bin/qmlviewer $QTDIR/examples/declarative/tutorials/helloworld/tutorial1.qml
+\endcode
+*/
+
+/*!
+\page qml-tutorial2.html
+\title QML Tutorial 2 - QML Components
+\contentspage QML Tutorial
+\previouspage QML Tutorial 1 - Basic Types
+\nextpage QML Tutorial 3 - States and Transitions
+
+This chapter adds a color picker to change the color of the text.
+
+\image declarative-tutorial2.png
+
+Our color picker is made of six cells with different colors.
+To avoid writing the same code multiple times for each cell, we 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 functions and is generally
+defined in its own QML file. (For more details, see \l {Defining New Components}).
+The component's filename must always start with a capital letter.
+
+Here is the QML code for \c Cell.qml:
+
+\snippet examples/declarative/tutorials/helloworld/Cell.qml 0
+
+\section1 Walkthrough
+
+\section2 The Cell Component
+
+\snippet examples/declarative/tutorials/helloworld/Cell.qml 1
+
+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.
+
+\snippet examples/declarative/tutorials/helloworld/Cell.qml 4
+
+We declare a \c cellColor 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{Property Binding}).
+
+\snippet examples/declarative/tutorials/helloworld/Cell.qml 5
+
+We want our component to also have a signal that we call \e clicked with a \e cellColor parameter of type \e color.
+We will use this signal to change the color of the text in the main QML file later.
+
+\snippet examples/declarative/tutorials/helloworld/Cell.qml 2
+
+Our cell component is basically a colored rectangle with the \c id \e rectangle.
+
+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}).
+
+\snippet examples/declarative/tutorials/helloworld/Cell.qml 3
+
+In order to change the color of the text when clicking on a cell, we create a \l MouseArea element with
+the same size as its parent.
+
+A \l MouseArea 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
+
+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 \e cellColor 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}).
+*/
+
+/*!
+\page qml-tutorial3.html
+\title QML Tutorial 3 - States and Transitions
+\contentspage QML Tutorial
+\previouspage QML Tutorial 2 - QML Component
+
+In this chapter, we make this example a little bit more dynamic by introducing states and transitions.
+
+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:
+
+\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 0
+
+\section1 Walkthrough
+
+\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 2
+
+First, we create a new \e down state for our text element.
+This state will be activated when the \l MouseArea 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/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 {QML States} and the \l{declarative/animation/states}{states and transitions example}.
+*/