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