1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtDeclarative module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "QtQuick1/private/qdeclarativetimer_p.h"
44 #include <QtCore/qcoreapplication.h>
45 #include <QtCore/qpauseanimation.h>
48 #include <private/qobject_p.h>
56 class QDeclarative1TimerPrivate : public QObjectPrivate
58 Q_DECLARE_PUBLIC(QDeclarative1Timer)
60 QDeclarative1TimerPrivate()
61 : interval(1000), running(false), repeating(false), triggeredOnStart(false)
62 , classBegun(false), componentComplete(false), firstTick(true) {}
64 QPauseAnimation pause;
67 bool triggeredOnStart : 1;
69 bool componentComplete : 1;
74 \qmlclass Timer QDeclarative1Timer
75 \inqmlmodule QtQuick 1
76 \ingroup qml-utility-elements
78 \brief The Timer item triggers a handler at a specified interval.
80 A Timer can be used to trigger an action either once, or repeatedly
83 Here is a Timer that shows the current date and time, and updates
84 the text every 500 milliseconds. It uses the JavaScript \c Date
85 object to access the current time.
92 interval: 500; running: true; repeat: true
93 onTriggered: time.text = Date().toString()
100 The Timer element is synchronized with the animation timer. Since the animation
101 timer is usually set to 60fps, the resolution of Timer will be
104 If the Timer is running and one of its properties is changed, the
105 elapsed time will be reset. For example, if a Timer with interval of
106 1000ms has its \e repeat property changed 500ms after starting, the
107 elapsed time will be reset to 0, and the Timer will be triggered
110 \sa {declarative/toys/clocks}{Clocks example}
113 QDeclarative1Timer::QDeclarative1Timer(QObject *parent)
114 : QObject(*(new QDeclarative1TimerPrivate), parent)
116 Q_D(QDeclarative1Timer);
117 connect(&d->pause, SIGNAL(currentLoopChanged(int)), this, SLOT(ticked()));
118 connect(&d->pause, SIGNAL(finished()), this, SLOT(finished()));
119 d->pause.setLoopCount(1);
120 d->pause.setDuration(d->interval);
124 \qmlproperty int QtQuick1::Timer::interval
126 Sets the \a interval between triggers, in milliseconds.
128 The default interval is 1000 milliseconds.
130 void QDeclarative1Timer::setInterval(int interval)
132 Q_D(QDeclarative1Timer);
133 if (interval != d->interval) {
134 d->interval = interval;
136 emit intervalChanged();
140 int QDeclarative1Timer::interval() const
142 Q_D(const QDeclarative1Timer);
147 \qmlproperty bool QtQuick1::Timer::running
149 If set to true, starts the timer; otherwise stops the timer.
150 For a non-repeating timer, \a running is set to false after the
151 timer has been triggered.
153 \a running defaults to false.
157 bool QDeclarative1Timer::isRunning() const
159 Q_D(const QDeclarative1Timer);
163 void QDeclarative1Timer::setRunning(bool running)
165 Q_D(QDeclarative1Timer);
166 if (d->running != running) {
167 d->running = running;
169 emit runningChanged();
175 \qmlproperty bool QtQuick1::Timer::repeat
177 If \a repeat is true the timer is triggered repeatedly at the
178 specified interval; otherwise, the timer will trigger once at the
179 specified interval and then stop (i.e. running will be set to false).
181 \a repeat defaults to false.
185 bool QDeclarative1Timer::isRepeating() const
187 Q_D(const QDeclarative1Timer);
191 void QDeclarative1Timer::setRepeating(bool repeating)
193 Q_D(QDeclarative1Timer);
194 if (repeating != d->repeating) {
195 d->repeating = repeating;
197 emit repeatChanged();
202 \qmlproperty bool QtQuick1::Timer::triggeredOnStart
204 When a timer is started, the first trigger is usually after the specified
205 interval has elapsed. It is sometimes desirable to trigger immediately
206 when the timer is started; for example, to establish an initial
209 If \a triggeredOnStart is true, the timer is triggered immediately
210 when started, and subsequently at the specified interval. Note that if
211 \e repeat is set to false, the timer is triggered twice; once on start,
212 and again at the interval.
214 \a triggeredOnStart defaults to false.
218 bool QDeclarative1Timer::triggeredOnStart() const
220 Q_D(const QDeclarative1Timer);
221 return d->triggeredOnStart;
224 void QDeclarative1Timer::setTriggeredOnStart(bool triggeredOnStart)
226 Q_D(QDeclarative1Timer);
227 if (d->triggeredOnStart != triggeredOnStart) {
228 d->triggeredOnStart = triggeredOnStart;
230 emit triggeredOnStartChanged();
235 \qmlmethod QtQuick1::Timer::start()
236 \brief Starts the timer.
238 If the timer is already running, calling this method has no effect. The
239 \c running property will be true following a call to \c start().
241 void QDeclarative1Timer::start()
247 \qmlmethod QtQuick1::Timer::stop()
248 \brief Stops the timer.
250 If the timer is not running, calling this method has no effect. The
251 \c running property will be false following a call to \c stop().
253 void QDeclarative1Timer::stop()
259 \qmlmethod QtQuick1::Timer::restart()
260 \brief Restarts the timer.
262 If the Timer is not running it will be started, otherwise it will be
263 stopped, reset to initial state and started. The \c running property
264 will be true following a call to \c restart().
266 void QDeclarative1Timer::restart()
272 void QDeclarative1Timer::update()
274 Q_D(QDeclarative1Timer);
275 if (d->classBegun && !d->componentComplete)
279 d->pause.setCurrentTime(0);
280 d->pause.setLoopCount(d->repeating ? -1 : 1);
281 d->pause.setDuration(d->interval);
283 if (d->triggeredOnStart && d->firstTick) {
284 QCoreApplication::removePostedEvents(this, QEvent::MetaCall);
285 QMetaObject::invokeMethod(this, "ticked", Qt::QueuedConnection);
290 void QDeclarative1Timer::classBegin()
292 Q_D(QDeclarative1Timer);
293 d->classBegun = true;
296 void QDeclarative1Timer::componentComplete()
298 Q_D(QDeclarative1Timer);
299 d->componentComplete = true;
304 \qmlsignal QtQuick1::Timer::onTriggered()
306 This handler is called when the Timer is triggered.
308 void QDeclarative1Timer::ticked()
310 Q_D(QDeclarative1Timer);
311 if (d->running && (d->pause.currentTime() > 0 || (d->triggeredOnStart && d->firstTick)))
313 d->firstTick = false;
316 void QDeclarative1Timer::finished()
318 Q_D(QDeclarative1Timer);
319 if (d->repeating || !d->running)
323 d->firstTick = false;
324 emit runningChanged();