1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the QtDeclarative module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
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 http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** As a special exception, The Qt Company gives you certain additional
27 ** rights. These rights are described in The Qt Company LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** GNU General Public License Usage
31 ** Alternatively, this file may be used under the terms of the GNU
32 ** General Public License version 3.0 as published by the Free Software
33 ** Foundation and appearing in the file LICENSE.GPL included in the
34 ** packaging of this file. Please review the following information to
35 ** ensure the GNU General Public License version 3.0 requirements will be
36 ** met: http://www.gnu.org/copyleft/gpl.html.
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #include "private/qdeclarativetimer_p.h"
43
44 #include <QtCore/qcoreapplication.h>
45 #include <QtCore/qpauseanimation.h>
46 #include <qdebug.h>
47
48 #include <private/qobject_p.h>
49
50 QT_BEGIN_NAMESPACE
51
52
53
54 class QDeclarativeTimerPrivate : public QObjectPrivate
55 {
56 Q_DECLARE_PUBLIC(QDeclarativeTimer)
57 public:
QDeclarativeTimerPrivate()58 QDeclarativeTimerPrivate()
59 : interval(1000), running(false), repeating(false), triggeredOnStart(false)
60 , classBegun(false), componentComplete(false), firstTick(true) {}
61 int interval;
62 QPauseAnimation pause;
63 bool running : 1;
64 bool repeating : 1;
65 bool triggeredOnStart : 1;
66 bool classBegun : 1;
67 bool componentComplete : 1;
68 bool firstTick : 1;
69 };
70
71 /*!
72 \qmlclass Timer QDeclarativeTimer
73 \ingroup qml-utility-elements
74 \since 4.7
75 \brief The Timer item triggers a handler at a specified interval.
76
77 A Timer can be used to trigger an action either once, or repeatedly
78 at a given interval.
79
80 Here is a Timer that shows the current date and time, and updates
81 the text every 500 milliseconds. It uses the JavaScript \c Date
82 object to access the current time.
83
84 \qml
85 import QtQuick 1.0
86
87 Item {
88 Timer {
89 interval: 500; running: true; repeat: true
90 onTriggered: time.text = Date().toString()
91 }
92
93 Text { id: time }
94 }
95 \endqml
96
97 The Timer element is synchronized with the animation timer. Since the animation
98 timer is usually set to 60fps, the resolution of Timer will be
99 at best 16ms.
100
101 If the Timer is running and one of its properties is changed, the
102 elapsed time will be reset. For example, if a Timer with interval of
103 1000ms has its \e repeat property changed 500ms after starting, the
104 elapsed time will be reset to 0, and the Timer will be triggered
105 1000ms later.
106
107 \sa {declarative/toys/clocks}{Clocks example}
108 */
109
QDeclarativeTimer(QObject * parent)110 QDeclarativeTimer::QDeclarativeTimer(QObject *parent)
111 : QObject(*(new QDeclarativeTimerPrivate), parent)
112 {
113 Q_D(QDeclarativeTimer);
114 connect(&d->pause, SIGNAL(currentLoopChanged(int)), this, SLOT(ticked()));
115 connect(&d->pause, SIGNAL(finished()), this, SLOT(finished()));
116 d->pause.setLoopCount(1);
117 d->pause.setDuration(d->interval);
118 }
119
120 /*!
121 \qmlproperty int Timer::interval
122
123 Sets the \a interval between triggers, in milliseconds.
124
125 The default interval is 1000 milliseconds.
126 */
setInterval(int interval)127 void QDeclarativeTimer::setInterval(int interval)
128 {
129 Q_D(QDeclarativeTimer);
130 if (interval != d->interval) {
131 d->interval = interval;
132 update();
133 emit intervalChanged();
134 }
135 }
136
interval() const137 int QDeclarativeTimer::interval() const
138 {
139 Q_D(const QDeclarativeTimer);
140 return d->interval;
141 }
142
143 /*!
144 \qmlproperty bool Timer::running
145
146 If set to true, starts the timer; otherwise stops the timer.
147 For a non-repeating timer, \a running is set to false after the
148 timer has been triggered.
149
150 \a running defaults to false.
151
152 \sa repeat
153 */
isRunning() const154 bool QDeclarativeTimer::isRunning() const
155 {
156 Q_D(const QDeclarativeTimer);
157 return d->running;
158 }
159
setRunning(bool running)160 void QDeclarativeTimer::setRunning(bool running)
161 {
162 Q_D(QDeclarativeTimer);
163 if (d->running != running) {
164 d->running = running;
165 d->firstTick = true;
166 emit runningChanged();
167 update();
168 }
169 }
170
171 /*!
172 \qmlproperty bool Timer::repeat
173
174 If \a repeat is true the timer is triggered repeatedly at the
175 specified interval; otherwise, the timer will trigger once at the
176 specified interval and then stop (i.e. running will be set to false).
177
178 \a repeat defaults to false.
179
180 \sa running
181 */
isRepeating() const182 bool QDeclarativeTimer::isRepeating() const
183 {
184 Q_D(const QDeclarativeTimer);
185 return d->repeating;
186 }
187
setRepeating(bool repeating)188 void QDeclarativeTimer::setRepeating(bool repeating)
189 {
190 Q_D(QDeclarativeTimer);
191 if (repeating != d->repeating) {
192 d->repeating = repeating;
193 update();
194 emit repeatChanged();
195 }
196 }
197
198 /*!
199 \qmlproperty bool Timer::triggeredOnStart
200
201 When a timer is started, the first trigger is usually after the specified
202 interval has elapsed. It is sometimes desirable to trigger immediately
203 when the timer is started; for example, to establish an initial
204 state.
205
206 If \a triggeredOnStart is true, the timer is triggered immediately
207 when started, and subsequently at the specified interval. Note that if
208 \e repeat is set to false, the timer is triggered twice; once on start,
209 and again at the interval.
210
211 \a triggeredOnStart defaults to false.
212
213 \sa running
214 */
triggeredOnStart() const215 bool QDeclarativeTimer::triggeredOnStart() const
216 {
217 Q_D(const QDeclarativeTimer);
218 return d->triggeredOnStart;
219 }
220
setTriggeredOnStart(bool triggeredOnStart)221 void QDeclarativeTimer::setTriggeredOnStart(bool triggeredOnStart)
222 {
223 Q_D(QDeclarativeTimer);
224 if (d->triggeredOnStart != triggeredOnStart) {
225 d->triggeredOnStart = triggeredOnStart;
226 update();
227 emit triggeredOnStartChanged();
228 }
229 }
230
231 /*!
232 \qmlmethod Timer::start()
233 \brief Starts the timer.
234
235 If the timer is already running, calling this method has no effect. The
236 \c running property will be true following a call to \c start().
237 */
start()238 void QDeclarativeTimer::start()
239 {
240 setRunning(true);
241 }
242
243 /*!
244 \qmlmethod Timer::stop()
245 \brief Stops the timer.
246
247 If the timer is not running, calling this method has no effect. The
248 \c running property will be false following a call to \c stop().
249 */
stop()250 void QDeclarativeTimer::stop()
251 {
252 setRunning(false);
253 }
254
255 /*!
256 \qmlmethod Timer::restart()
257 \brief Restarts the timer.
258
259 If the Timer is not running it will be started, otherwise it will be
260 stopped, reset to initial state and started. The \c running property
261 will be true following a call to \c restart().
262 */
restart()263 void QDeclarativeTimer::restart()
264 {
265 setRunning(false);
266 setRunning(true);
267 }
268
update()269 void QDeclarativeTimer::update()
270 {
271 Q_D(QDeclarativeTimer);
272 if (d->classBegun && !d->componentComplete)
273 return;
274 d->pause.stop();
275 if (d->running) {
276 d->pause.setCurrentTime(0);
277 d->pause.setLoopCount(d->repeating ? -1 : 1);
278 d->pause.setDuration(d->interval);
279 d->pause.start();
280 if (d->triggeredOnStart && d->firstTick) {
281 QCoreApplication::removePostedEvents(this, QEvent::MetaCall);
282 QMetaObject::invokeMethod(this, "ticked", Qt::QueuedConnection);
283 }
284 }
285 }
286
classBegin()287 void QDeclarativeTimer::classBegin()
288 {
289 Q_D(QDeclarativeTimer);
290 d->classBegun = true;
291 }
292
componentComplete()293 void QDeclarativeTimer::componentComplete()
294 {
295 Q_D(QDeclarativeTimer);
296 d->componentComplete = true;
297 update();
298 }
299
300 /*!
301 \qmlsignal Timer::onTriggered()
302
303 This handler is called when the Timer is triggered.
304 */
ticked()305 void QDeclarativeTimer::ticked()
306 {
307 Q_D(QDeclarativeTimer);
308 if (d->running && (d->pause.currentTime() > 0 || (d->triggeredOnStart && d->firstTick)))
309 emit triggered();
310 d->firstTick = false;
311 }
312
finished()313 void QDeclarativeTimer::finished()
314 {
315 Q_D(QDeclarativeTimer);
316 if (d->repeating || !d->running)
317 return;
318 emit triggered();
319 d->running = false;
320 d->firstTick = false;
321 emit runningChanged();
322 }
323
324 QT_END_NAMESPACE
325