path: root/doc/src/declarative/tutorial.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** 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.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $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}.
*/