Warning: That file was not part of the compilation database. It may have many parsing errors.

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

Warning: That file was not part of the compilation database. It may have many parsing errors.