1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qquickprogressbar_p.h"
5#include "qquickcontrol_p_p.h"
6
7QT_BEGIN_NAMESPACE
8
9/*!
10 \qmltype ProgressBar
11 \inherits Control
12//! \instantiates QQuickProgressBar
13 \inqmlmodule QtQuick.Controls
14 \since 5.7
15 \ingroup qtquickcontrols-indicators
16 \brief Indicates the progress of an operation.
17
18 \image qtquickcontrols-progressbar.gif
19
20 ProgressBar indicates the progress of an operation. The value should be updated
21 regularly. The range is defined by \l from and \l to, which both can contain any value.
22
23 \code
24 ProgressBar {
25 value: 0.5
26 }
27 \endcode
28
29 ProgressBar also supports a special \l indeterminate mode, which is useful,
30 for example, when unable to determine the size of the item being downloaded,
31 or if the download progress gets interrupted due to a network disconnection.
32
33 \image qtquickcontrols-progressbar-indeterminate.gif
34
35 \code
36 ProgressBar {
37 indeterminate: true
38 }
39 \endcode
40
41 The indeterminate mode is similar to a \l BusyIndicator. Both can be used
42 to indicate background activity. The main difference is visual, and that
43 ProgressBar can also present a concrete amount of progress (when it can be
44 determined). Due to the visual difference, indeterminate progress bars and
45 busy indicators fit different places in user interfaces. Typical places for
46 an indeterminate progress bar:
47 \list
48 \li at the bottom of a \l ToolBar
49 \li inline within the content of a \l Page
50 \li in an \l ItemDelegate to show the progress of a particular item
51 \endlist
52
53 \sa {Customizing ProgressBar}, BusyIndicator, {Indicator Controls}
54*/
55
56class QQuickProgressBarPrivate : public QQuickControlPrivate
57{
58public:
59 qreal from = 0;
60 qreal to = 1;
61 qreal value = 0;
62 bool indeterminate = false;
63};
64
65QQuickProgressBar::QQuickProgressBar(QQuickItem *parent)
66 : QQuickControl(*(new QQuickProgressBarPrivate), parent)
67{
68}
69
70/*!
71 \qmlproperty real QtQuick.Controls::ProgressBar::from
72
73 This property holds the starting value for the progress. The default value is \c 0.0.
74
75 \sa to, value
76*/
77qreal QQuickProgressBar::from() const
78{
79 Q_D(const QQuickProgressBar);
80 return d->from;
81}
82
83void QQuickProgressBar::setFrom(qreal from)
84{
85 Q_D(QQuickProgressBar);
86 if (qFuzzyCompare(p1: d->from, p2: from))
87 return;
88
89 d->from = from;
90 emit fromChanged();
91 emit positionChanged();
92 emit visualPositionChanged();
93 if (isComponentComplete())
94 setValue(d->value);
95}
96
97/*!
98 \qmlproperty real QtQuick.Controls::ProgressBar::to
99
100 This property holds the end value for the progress. The default value is \c 1.0.
101
102 \sa from, value
103*/
104qreal QQuickProgressBar::to() const
105{
106 Q_D(const QQuickProgressBar);
107 return d->to;
108}
109
110void QQuickProgressBar::setTo(qreal to)
111{
112 Q_D(QQuickProgressBar);
113 if (qFuzzyCompare(p1: d->to, p2: to))
114 return;
115
116 d->to = to;
117 emit toChanged();
118 emit positionChanged();
119 emit visualPositionChanged();
120 if (isComponentComplete())
121 setValue(d->value);
122}
123
124/*!
125 \qmlproperty real QtQuick.Controls::ProgressBar::value
126
127 This property holds the progress value. The default value is \c 0.0.
128
129 \sa from, to, position
130*/
131qreal QQuickProgressBar::value() const
132{
133 Q_D(const QQuickProgressBar);
134 return d->value;
135}
136
137void QQuickProgressBar::setValue(qreal value)
138{
139 Q_D(QQuickProgressBar);
140 if (isComponentComplete())
141 value = d->from > d->to ? qBound(min: d->to, val: value, max: d->from) : qBound(min: d->from, val: value, max: d->to);
142
143 if (qFuzzyCompare(p1: d->value, p2: value))
144 return;
145
146 d->value = value;
147 emit valueChanged();
148 emit positionChanged();
149 emit visualPositionChanged();
150}
151
152/*!
153 \qmlproperty real QtQuick.Controls::ProgressBar::position
154 \readonly
155
156 This property holds the logical position of the progress.
157
158 The position is expressed as a fraction of the value, in the range
159 \c {0.0 - 1.0}. For visualizing the progress, the right-to-left
160 aware \l visualPosition should be used instead.
161
162 \sa value, visualPosition
163*/
164qreal QQuickProgressBar::position() const
165{
166 Q_D(const QQuickProgressBar);
167 if (qFuzzyCompare(p1: d->from, p2: d->to))
168 return 0;
169 return (d->value - d->from) / (d->to - d->from);
170}
171
172/*!
173 \qmlproperty real QtQuick.Controls::ProgressBar::visualPosition
174 \readonly
175
176 This property holds the visual position of the progress.
177
178 The position is expressed as a fraction of the value, in the range \c {0.0 - 1.0}.
179 When the control is \l {Control::mirrored}{mirrored}, \c visuaPosition is equal
180 to \c {1.0 - position}. This makes \c visualPosition suitable for visualizing
181 the progress, taking right-to-left support into account.
182
183 \sa position, value
184*/
185qreal QQuickProgressBar::visualPosition() const
186{
187 if (isMirrored())
188 return 1.0 - position();
189 return position();
190}
191
192/*!
193 \qmlproperty bool QtQuick.Controls::ProgressBar::indeterminate
194
195 This property holds whether the progress bar is in indeterminate mode.
196 A progress bar in indeterminate mode displays that an operation is in progress, but it
197 doesn't show how much progress has been made.
198
199 \image qtquickcontrols-progressbar-indeterminate.gif
200*/
201bool QQuickProgressBar::isIndeterminate() const
202{
203 Q_D(const QQuickProgressBar);
204 return d->indeterminate;
205}
206
207void QQuickProgressBar::setIndeterminate(bool indeterminate)
208{
209 Q_D(QQuickProgressBar);
210 if (d->indeterminate == indeterminate)
211 return;
212
213 d->indeterminate = indeterminate;
214 emit indeterminateChanged();
215}
216
217void QQuickProgressBar::mirrorChange()
218{
219 QQuickControl::mirrorChange();
220 if (!qFuzzyCompare(p1: position(), p2: qreal(0.5)))
221 emit visualPositionChanged();
222}
223
224void QQuickProgressBar::componentComplete()
225{
226 Q_D(QQuickProgressBar);
227 QQuickControl::componentComplete();
228 setValue(d->value);
229}
230
231#if QT_CONFIG(accessibility)
232QAccessible::Role QQuickProgressBar::accessibleRole() const
233{
234 return QAccessible::ProgressBar;
235}
236#endif
237
238QT_END_NAMESPACE
239
240#include "moc_qquickprogressbar_p.cpp"
241

source code of qtdeclarative/src/quicktemplates/qquickprogressbar.cpp