doc/src/qtquick1/tutorial.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qml-tutorial.html
  30 \inqmlmodule QtQuick 1
  31 \title QML Tutorial
  32 \brief An introduction to the basic concepts and features of QML.
  33 \nextpage QML Tutorial 1 - Basic Types
  34
  35 This tutorial gives an introduction to QML, the mark up language for Qt Quick. It doesn't cover everything;
  36 the emphasis is on teaching the key principles, and features are introduced as needed.
  37
  38 Through the different steps of this tutorial we will learn about QML basic types, we will create our own QML component
  39 with properties and signals, and we will create a simple animation with the help of states and transitions.
  40
  41 Chapter one starts with a minimal "Hello world" program and the following chapters introduce new concepts.
  42
  43 The tutorial's source code is located in the $QTDIR/examples/declarative/tutorials/helloworld directory.
  44
  45 Tutorial chapters:
  46
  47 \list 1
  48 \o \l {QML Tutorial 1 - Basic Types}{Basic Types}
  49 \o \l {QML Tutorial 2 - QML Components}{QML Components}
  50 \o \l {QML Tutorial 3 - States and Transitions}{States and Transitions}
  51 \endlist
  52
  53 */
  54
  55 /*!
  56 \page qml-tutorial1.html
  57 \inqmlmodule QtQuick 1
  58 \title QML Tutorial 1 - Basic Types
  59 \contentspage QML Tutorial
  60 \previouspage QML Tutorial
  61 \nextpage QML Tutorial 2 - QML Component
  62
  63 This first program is a very simple "Hello world" example that introduces some basic QML concepts.
  64 The picture below is a screenshot of this program.
  65
  66 \image declarative-tutorial1.png
  67
  68 Here is the QML code for the application:
  69
  70 \snippet examples/declarative/tutorials/helloworld/tutorial1.qml 0
  71
  72 \section1 Walkthrough
  73
  74 \section2 Import
  75
  76 First, we need to import the types that we need for this example. Most QML files will import the built-in QML
  77 types (like \l{Rectangle}, \l{Image}, ...) that come with Qt, using:
  78
  79 \snippet examples/declarative/tutorials/helloworld/tutorial1.qml 3
  80
  81 \section2 Rectangle element
  82
  83 \snippet examples/declarative/tutorials/helloworld/tutorial1.qml 1
  84
  85 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.
  86 We give it an \c{id} to be able to refer to it later. In this case, we call it "page".
  87 We also set the \c width, \c height and \c color properties.
  88 The \l{Rectangle} element contains many other properties (such as \c x and \c y), but these are left at their default values.
  89
  90 \section2 Text element
  91
  92 \snippet examples/declarative/tutorials/helloworld/tutorial1.qml 2
  93
  94 We add a \l Text element as a child of the root Rectangle element that displays the text 'Hello world!'.
  95
  96 The \c y property is used to position the text vertically at 30 pixels from the top of its parent.
  97
  98 The \c anchors.horizontalCenter property refers to the horizontal center of an element.
  99 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}).
 100
 101 The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{dot properties}{dot notation}.
 102
 103
 104 \section2 Viewing the example
 105
 106 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.
 107 For example, to run the provided completed Tutorial 1 example from the install location, you would type:
 108
 109 \code
 110 bin/qmlviewer $QTDIR/examples/declarative/tutorials/helloworld/tutorial1.qml
 111 \endcode
 112 */
 113
 114 /*!
 115 \page qml-tutorial2.html
 116 \inqmlmodule QtQuick 1
 117 \title QML Tutorial 2 - QML Components
 118 \contentspage QML Tutorial
 119 \previouspage QML Tutorial 1 - Basic Types
 120 \nextpage QML Tutorial 3 - States and Transitions
 121
 122 This chapter adds a color picker to change the color of the text.
 123
 124 \image declarative-tutorial2.png
 125
 126 Our color picker is made of six cells with different colors.
 127 To avoid writing the same code multiple times for each cell, we create a new \c Cell component.
 128 A component provides a way of defining a new type that we can re-use in other QML files.
 129 A QML component is like a black-box and interacts with the outside world through properties, signals and functions and is generally
 130 defined in its own QML file. (For more details, see \l {Defining New Components}).
 131 The component's filename must always start with a capital letter.
 132
 133 Here is the QML code for \c Cell.qml:
 134
 135 \snippet examples/declarative/tutorials/helloworld/Cell.qml 0
 136
 137 \section1 Walkthrough
 138
 139 \section2 The Cell Component
 140
 141 \snippet examples/declarative/tutorials/helloworld/Cell.qml 1
 142
 143 The root element of our component is an \l Item with the \c id \e container.
 144 An \l Item is the most basic visual element in QML and is often used as a container for other elements.
 145
 146 \snippet examples/declarative/tutorials/helloworld/Cell.qml 4
 147
 148 We declare a \c cellColor property. This property is accessible from  \e outside our component, this allows us
 149 to instantiate the cells with different colors.
 150 This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Property Binding}).
 151
 152 \snippet examples/declarative/tutorials/helloworld/Cell.qml 5
 153
 154 We want our component to also have a signal that we call \e clicked with a \e cellColor parameter of type \e color.
 155 We will use this signal to change the color of the text in the main QML file later.
 156
 157 \snippet examples/declarative/tutorials/helloworld/Cell.qml 2
 158
 159 Our cell component is basically a colored rectangle with the \c id \e rectangle.
 160
 161 The \c anchors.fill property is a convenient way to set the size of an element.
 162 In this case the rectangle will have the same size as its parent (see \l{anchor-layout}{Anchor-Based Layout}).
 163
 164 \snippet examples/declarative/tutorials/helloworld/Cell.qml 3
 165
 166 In order to change the color of the text when clicking on a cell, we create a \l MouseArea element with
 167 the same size as its parent.
 168
 169 A \l MouseArea defines a signal called \e clicked.
 170 When this signal is triggered we want to emit our own \e clicked signal with the color as parameter.
 171
 172 \section2 The main QML file
 173
 174 In our main QML file, we use our \c Cell component to create the color picker:
 175
 176 \snippet examples/declarative/tutorials/helloworld/tutorial2.qml 0
 177
 178 We create the color picker by putting 6 cells with different colors in a grid.
 179
 180 \snippet examples/declarative/tutorials/helloworld/tutorial2.qml 1
 181
 182 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.
 183 We can react to any signal of our component through a property of the name \e 'onSignalName' (see \l{Signal Handlers}).
 184 */
 185
 186 /*!
 187 \page qml-tutorial3.html
 188 \inqmlmodule QtQuick 1
 189 \title QML Tutorial 3 - States and Transitions
 190 \contentspage QML Tutorial
 191 \previouspage QML Tutorial 2 - QML Component
 192
 193 In this chapter, we make this example a little bit more dynamic by introducing states and transitions.
 194
 195 We want our text to move to the bottom of the screen, rotate and become red when clicked.
 196
 197 \image declarative-tutorial3_animation.gif
 198
 199 Here is the QML code:
 200
 201 \snippet examples/declarative/tutorials/helloworld/tutorial3.qml 0
 202
 203 \section1 Walkthrough
 204
 205 \snippet examples/declarative/tutorials/helloworld/tutorial3.qml 2
 206
 207 First, we create a new \e down state for our text element.
 208 This state will be activated when the \l MouseArea is pressed, and deactivated when it is released.
 209
 210 The \e down state includes a set of property changes from our implicit \e {default state}
 211 (the items as they were initially defined in the QML).
 212 Specifically, we set the \c y property of the text to \c 160, the rotation to \c 180 and the \c color to red.
 213
 214 \snippet examples/declarative/tutorials/helloworld/tutorial3.qml 3
 215
 216 Because we don't want the text to appear at the bottom instantly but rather move smoothly,
 217 we add a transition between our two states.
 218
 219 \c from and \c to define the states between which the transition will run.
 220 In this case, we want a transition from the default state to our \e down state.
 221
 222 Because we want the same transition to be run in reverse when changing back from the \e down state to the default state,
 223 we set \c reversible to \c true.
 224 This is equivalent to writing the two transitions separately.
 225
 226 The \l ParallelAnimation element makes sure that the two types of animations (number and color) start at the same time.
 227 We could also run them one after the other by using \l SequentialAnimation instead.
 228
 229 For more details on states and transitions, see \l {QML States} and the \l{declarative/animation/states}{states and transitions example}.
 230 */