1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: http://www.qt-project.org/
7 ** This file is part of the QtDeclarative module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qdeclarativetimer_p.h"
44 #include <QtCore/qcoreapplication.h>
45 #include <QtCore/qpauseanimation.h>
48 #include <private/qobject_p.h>
54 class QDeclarativeTimerPrivate : public QObjectPrivate
56 Q_DECLARE_PUBLIC(QDeclarativeTimer)
58 QDeclarativeTimerPrivate()
59 : interval(1000), running(false), repeating(false), triggeredOnStart(false)
60 , classBegun(false), componentComplete(false), firstTick(true) {}
62 QPauseAnimation pause;
65 bool triggeredOnStart : 1;
67 bool componentComplete : 1;
72 \qmlclass Timer QDeclarativeTimer
73 \inqmlmodule QtQuick 2
74 \ingroup qml-utility-elements
75 \brief The Timer item triggers a handler at a specified interval.
77 A Timer can be used to trigger an action either once, or repeatedly
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.
89 interval: 500; running: true; repeat: true
90 onTriggered: time.text = Date().toString()
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
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
107 \sa {declarative/toys/clocks}{Clocks example}
110 QDeclarativeTimer::QDeclarativeTimer(QObject *parent)
111 : QObject(*(new QDeclarativeTimerPrivate), parent)
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);
121 \qmlproperty int QtQuick2::Timer::interval
123 Sets the \a interval between triggers, in milliseconds.
125 The default interval is 1000 milliseconds.
127 void QDeclarativeTimer::setInterval(int interval)
129 Q_D(QDeclarativeTimer);
130 if (interval != d->interval) {
131 d->interval = interval;
133 emit intervalChanged();
137 int QDeclarativeTimer::interval() const
139 Q_D(const QDeclarativeTimer);
144 \qmlproperty bool QtQuick2::Timer::running
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.
150 \a running defaults to false.
154 bool QDeclarativeTimer::isRunning() const
156 Q_D(const QDeclarativeTimer);
160 void QDeclarativeTimer::setRunning(bool running)
162 Q_D(QDeclarativeTimer);
163 if (d->running != running) {
164 d->running = running;
166 emit runningChanged();
172 \qmlproperty bool QtQuick2::Timer::repeat
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).
178 \a repeat defaults to false.
182 bool QDeclarativeTimer::isRepeating() const
184 Q_D(const QDeclarativeTimer);
188 void QDeclarativeTimer::setRepeating(bool repeating)
190 Q_D(QDeclarativeTimer);
191 if (repeating != d->repeating) {
192 d->repeating = repeating;
194 emit repeatChanged();
199 \qmlproperty bool QtQuick2::Timer::triggeredOnStart
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
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.
211 \a triggeredOnStart defaults to false.
215 bool QDeclarativeTimer::triggeredOnStart() const
217 Q_D(const QDeclarativeTimer);
218 return d->triggeredOnStart;
221 void QDeclarativeTimer::setTriggeredOnStart(bool triggeredOnStart)
223 Q_D(QDeclarativeTimer);
224 if (d->triggeredOnStart != triggeredOnStart) {
225 d->triggeredOnStart = triggeredOnStart;
227 emit triggeredOnStartChanged();
232 \qmlmethod QtQuick2::Timer::start()
233 \brief Starts the timer.
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().
238 void QDeclarativeTimer::start()
244 \qmlmethod QtQuick2::Timer::stop()
245 \brief Stops the timer.
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().
250 void QDeclarativeTimer::stop()
256 \qmlmethod QtQuick2::Timer::restart()
257 \brief Restarts the timer.
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().
263 void QDeclarativeTimer::restart()
269 void QDeclarativeTimer::update()
271 Q_D(QDeclarativeTimer);
272 if (d->classBegun && !d->componentComplete)
276 d->pause.setCurrentTime(0);
277 d->pause.setLoopCount(d->repeating ? -1 : 1);
278 d->pause.setDuration(d->interval);
280 if (d->triggeredOnStart && d->firstTick) {
281 QCoreApplication::removePostedEvents(this, QEvent::MetaCall);
282 QMetaObject::invokeMethod(this, "ticked", Qt::QueuedConnection);
287 void QDeclarativeTimer::classBegin()
289 Q_D(QDeclarativeTimer);
290 d->classBegun = true;
293 void QDeclarativeTimer::componentComplete()
295 Q_D(QDeclarativeTimer);
296 d->componentComplete = true;
301 \qmlsignal QtQuick2::Timer::onTriggered()
303 This handler is called when the Timer is triggered.
305 void QDeclarativeTimer::ticked()
307 Q_D(QDeclarativeTimer);
308 if (d->running && (d->pause.currentTime() > 0 || (d->triggeredOnStart && d->firstTick)))
310 d->firstTick = false;
313 void QDeclarativeTimer::finished()
315 Q_D(QDeclarativeTimer);
316 if (d->repeating || !d->running)
319 d->firstTick = false;
321 emit runningChanged();