1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtDeclarative module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** No Commercial Usage
11 ** This file contains pre-release code and may not be distributed.
12 ** You may use this file in accordance with the terms and conditions
13 ** contained in the Technology Preview License Agreement accompanying
16 ** GNU Lesser General Public License Usage
17 ** Alternatively, this file may be used under the terms of the GNU Lesser
18 ** General Public License version 2.1 as published by the Free Software
19 ** Foundation and appearing in the file LICENSE.LGPL included in the
20 ** packaging of this file. Please review the following information to
21 ** ensure the GNU Lesser General Public License version 2.1 requirements
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 ** In addition, as a special exception, Nokia gives you certain additional
25 ** rights. These rights are described in the Nokia Qt LGPL Exception
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
42 #include "private/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 \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 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 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 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 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 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 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 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 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)
320 d->firstTick = false;
321 emit runningChanged();