1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Design Studio documentation.
**
** 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 The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/
/*!
\example progressbar
\ingroup studioexamples
\title Progress Bar
\brief Illustrates how to use timelines to create an animated progress bar.
\image progressbar.png "Progress Bar example application"
\e {Progress Bar} animates rectangles and numbers using timelines.
\section1 Creating the Progress Bar
First, we create an empty Qt Quick project, as described in
\l {Creating Projects}. For the purposes of this example,
we call the project \e progressbar.
In this example, we use two overlapping rectangles and a text label to
create the progress bar. For another example of a progress bar, see the
\l [QtQuickControls2] {ProgressBar} in Qt Quick Controls.
In the Design mode, we drag and drop a \uicontrol Rectangle from the
\uicontrol Library to the \uicontrol {Form Editor} and modify its size
to create the background for the progress bar. We change its id to
\e background in the \uicontrol Properties view.
We want to be able to control the background rectangle and the text label
that was added by the project wizard, so we will use an \uicontrol Item
for that. We drag and drop the item from the \uicontrol Library to the
\uicontrol {Form Editor} and change its id to \e root in the
\uicontrol Properties view.
To make the background and text children of the item, we drag and drop them
to the item in the \uicontrol Navigator view. This enables us to use the anchor
buttons in \uicontrol Properties > \uicontrol Layout to anchor them to their
parent. We anchor the background to its parent on all edges, with a 30-pixel
margin at the top to leave space for the text. We then anchor the text to
the top of the item.
\image progressbar-rectangle.png "Progress bar background in the Form Editor"
We now drag and drop another rectangle on top of the background rectangle in
the \uicontrol Navigator and change its id to \e indicator in the properties.
We then anchor the left, top, and bottom of the indicator to its parent with
5-pixel margins. We leave the right side free, because its value needs to
change for the animation.
For more information about creating and positioning components, see
\l {Creating Components}.
\section1 Animating Progress Bar Elements
The text label will indicate the progress in numbers and changing color,
while the indicator rectangle will indicate it by getting wider and
changing color. To animate the label and indicator, we'll add timelines
in the \uicontrol Timeline view.
For more information about using the timeline, see \l {Creating Animations}.
\section2 Adding Color Animation
First, we add a color animation to the \e root item. We select the
\inlineimage plus.png
button to add a 100-frame timeline to root. You can use the default
values for all other fields.
\image progressbar-timeline-settings.png "Timeline settings"
To start recording a color animation on the timeline, we check that the
playhead is at frame 0 and then select the \inlineimage recordfill.png
(\uicontrol {Auto Key (K)}) button (or press \key k).
\image progressbar-timeline.png "Color animation timeline"
We then set the color at frame 0 to green (\e {#8de98d}) in
\uicontrol Properties > \uicontrol Text > \uicontrol {Text Color}.
We can either pick a color from the color selector or use the
\uicontrol {Set Binding} command in the \inlineimage submenu.png
(\uicontrol Settings) menu to open the \uicontrol {Binding Editor}.
We then move the playhead to frame 50 and set the text color to red
(\e {#de4f4f}). Finally, we move the playhead to frame 100 and set
the color to yellow (\e {#f0c861}).
When we deselect the record button to stop recording the timeline, the
new timeline appears in the view.
We can drag the playhead along the timeline to see the color animation.
\section2 Animating the Indicator
We select \e indicator in \uicontrol Navigator and then select the record
button again to animate the width of the indicator. At frame 0, we set the
width to 0 in \uicontrol Properties > \uicontrol Geometry > \uicontrol Size.
We then move the playhead to 100 frames and set the width to 590.
\image progressbar-timeline-indicator.png "Indicator timeline"
We will now copy the color animation from the text label to the indicator.
First, we right-click the text item in the \uicontrol Timeline view to open
a context menu and select \uicontrol {Copy All Keyframes from Item} to copy
the keyframe values we specified for the text label.
Next, we select the indicator in the \uicontrol Navigator, and then select
\uicontrol {Insert Keyframes for Item} to paste the keyframe
values to the indicator.
\image progressbar-timeline-indicator-color.png "Indicator timeline with color animation"
When we move the playhead, we can see that the color animation is also
applied to the indicator.
\section1 Creating a Reusable Component
We want the progress bar to be reusable, so we'll move it to a separate
QML file. To make sure that the component will contain the timeline, we
select \uicontrol {Filter Tree} in the \uicontrol Navigator, and then
deselect the \uicontrol {Show Only Visible Items} check box to show the
timeline item in the \uicontrol Navigator. We then move the timeline item
to \e root to have it moved as a part of the root component.
Now we can right-click root to open a context menu and select
\uicontrol {Move Component into Separate File}. We can see the
properties that will be available from outside of the component.
\image progressbar-move-component.png "Move Component into Separate File dialog"
\section1 Exporting Properties
We now select the root component in the \uicontrol Navigator, and
then select \uicontrol {Go into Component} in the context menu to
open \e Root.qml in the \uicontrol {Form Editor}.
We want to be able to use the keyframe value as the value of the text label,
so we will export it as a property alias. We select \e timeline in the
\uicontrol Navigator and then \uicontrol Properties > \uicontrol Timeline >
\uicontrol {Current frame} > \uicontrol Settings >
\uicontrol {Export Property as Alias}.
\image progressbar-root-export-property.png "Export keyframe group as a property"
When we select \e root in the \uicontrol Navigator, we can see the
\e timelineCurrentFrame property in \uicontrol Connections
> \uicontrol Bindings. We double-click it to change its name
to \e progress.
\image progressbar-bindings-progress.png "Connections view Bindings tab"
We will bind some JavaScript to the value of the text label to turn
it into a running number that reflects the number of the keyframe on the
timeline. We select the text label in the \uicontrol Navigator, and then
select \uicontrol Properties > \uicontrol Text > \uicontrol {Set Binding}
to open the \uicontrol {Binding Editor}. We set
\c {Math.round(root.progress)} as the value of the text label.
When we move back to the top-level file, we can see that the number of the
current keyframe (0) is displayed as the value of the text label.
\section1 Animating Progress Bar Instances
We want to experiment with different start and end values and easing curves,
so we copy-paste the progress bar instance twice in the top-level file. We
use a column layout to lay out the progress bar instances.
We can now add timelines for each progress bar instance, with different
settings. We select the \inlineimage plus.png
button to add a 4000-frame timeline to the first progress bar instance
(\e root). We select the \uicontrol Continuous check box, so that the
animation will loop.
In \uicontrol Properties > \uicontrol Root, we can see the
\uicontrol progress property that we can animate. If we had
called the component and property something else, we would
see the names we gave them here.
With the playhead in the first frame, we select the record button and
give the \uicontrol progress property the initial value of \e 5. We then
move the playhead to frame 2000 and give it the value of \e 95. We
continue to the last frame and set the value back to \e 5 to have a
smooth looping animation.
When we select the \uicontrol {Show Live Preview} button on the
\uicontrol {Form Editor} toolbar, we see a running number and moving
progress indicator of the animated progress bar instance.
\image progressbar-animated.png
We now change the settings of the other two progress bar instances. We
make one of the indicators move from right to left by starting from frame
100. When all our progress bar instances have been animated, we'll continue
by specifying easing curves for them.
For more information about previewing UIs, see \l {Previewing}.
\section1 Specifying Easing Curves
We can add custom easing curves to every keyframe in the animations. First,
we select the keyframe to add the easing curve to, and then select
\uicontrol {Edit Easing Curve} in the context menu. We can select several
keyframes simultaneously if we want to use the same easing curve for them.
We select the easing curve in the \uicontrol {Easing Curve Editor}.
\image studio-easing-curve-editor.png "Easing Curve Editor"
When we apply easing curves to animations, the shape of the keyframe
marker changes from \inlineimage keyframe_linear_inactive.png
to \inlineimage keyframe_manualbezier_inactive.png
.
For more information, see \l{Editing Easing Curves}.
*/
|