src/qtquick1/util/qdeclarativetimer.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtDeclarative module of the Qt Toolkit.
   7 **
   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.
  16 **
  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.
  20 **
  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.
  28 **
  29 ** Other Usage
  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.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "QtQuick1/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
  55
  56 class QDeclarative1TimerPrivate : public QObjectPrivate
  57 {
  58     Q_DECLARE_PUBLIC(QDeclarative1Timer)
  59 public:
  60     QDeclarative1TimerPrivate()
  61         : interval(1000), running(false), repeating(false), triggeredOnStart(false)
  62         , classBegun(false), componentComplete(false), firstTick(true) {}
  63     int interval;
  64     QPauseAnimation pause;
  65     bool running : 1;
  66     bool repeating : 1;
  67     bool triggeredOnStart : 1;
  68     bool classBegun : 1;
  69     bool componentComplete : 1;
  70     bool firstTick : 1;
  71 };
  72
  73 /*!
  74     \qmlclass Timer QDeclarative1Timer
  75     \inqmlmodule QtQuick 1
  76     \ingroup qml-utility-elements
  77     \since QtQuick 1.0
  78     \brief The Timer item triggers a handler at a specified interval.
  79
  80     A Timer can be used to trigger an action either once, or repeatedly
  81     at a given interval.
  82
  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.
  86
  87     \qml
  88     import QtQuick 1.0
  89
  90     Item {
  91         Timer {
  92             interval: 500; running: true; repeat: true
  93             onTriggered: time.text = Date().toString()
  94         }
  95
  96         Text { id: time }
  97     }
  98     \endqml
  99
 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
 102     at best 16ms.
 103
 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
 108     1000ms later.
 109
 110     \sa {declarative/toys/clocks}{Clocks example}
 111 */
 112
 113 QDeclarative1Timer::QDeclarative1Timer(QObject *parent)
 114     : QObject(*(new QDeclarative1TimerPrivate), parent)
 115 {
 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);
 121 }
 122
 123 /*!
 124     \qmlproperty int QtQuick1::Timer::interval
 125
 126     Sets the \a interval between triggers, in milliseconds.
 127
 128     The default interval is 1000 milliseconds.
 129 */
 130 void QDeclarative1Timer::setInterval(int interval)
 131 {
 132     Q_D(QDeclarative1Timer);
 133     if (interval != d->interval) {
 134         d->interval = interval;
 135         update();
 136         emit intervalChanged();
 137     }
 138 }
 139
 140 int QDeclarative1Timer::interval() const
 141 {
 142     Q_D(const QDeclarative1Timer);
 143     return d->interval;
 144 }
 145
 146 /*!
 147     \qmlproperty bool QtQuick1::Timer::running
 148
 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.
 152
 153     \a running defaults to false.
 154
 155     \sa repeat
 156 */
 157 bool QDeclarative1Timer::isRunning() const
 158 {
 159     Q_D(const QDeclarative1Timer);
 160     return d->running;
 161 }
 162
 163 void QDeclarative1Timer::setRunning(bool running)
 164 {
 165     Q_D(QDeclarative1Timer);
 166     if (d->running != running) {
 167         d->running = running;
 168         d->firstTick = true;
 169         emit runningChanged();
 170         update();
 171     }
 172 }
 173
 174 /*!
 175     \qmlproperty bool QtQuick1::Timer::repeat
 176
 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).
 180
 181     \a repeat defaults to false.
 182
 183     \sa running
 184 */
 185 bool QDeclarative1Timer::isRepeating() const
 186 {
 187     Q_D(const QDeclarative1Timer);
 188     return d->repeating;
 189 }
 190
 191 void QDeclarative1Timer::setRepeating(bool repeating)
 192 {
 193     Q_D(QDeclarative1Timer);
 194     if (repeating != d->repeating) {
 195         d->repeating = repeating;
 196         update();
 197         emit repeatChanged();
 198     }
 199 }
 200
 201 /*!
 202     \qmlproperty bool QtQuick1::Timer::triggeredOnStart
 203
 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
 207     state.
 208
 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.
 213
 214     \a triggeredOnStart defaults to false.
 215
 216     \sa running
 217 */
 218 bool QDeclarative1Timer::triggeredOnStart() const
 219 {
 220     Q_D(const QDeclarative1Timer);
 221     return d->triggeredOnStart;
 222 }
 223
 224 void QDeclarative1Timer::setTriggeredOnStart(bool triggeredOnStart)
 225 {
 226     Q_D(QDeclarative1Timer);
 227     if (d->triggeredOnStart != triggeredOnStart) {
 228         d->triggeredOnStart = triggeredOnStart;
 229         update();
 230         emit triggeredOnStartChanged();
 231     }
 232 }
 233
 234 /*!
 235     \qmlmethod QtQuick1::Timer::start()
 236     \brief Starts the timer.
 237
 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().
 240 */
 241 void QDeclarative1Timer::start()
 242 {
 243     setRunning(true);
 244 }
 245
 246 /*!
 247     \qmlmethod QtQuick1::Timer::stop()
 248     \brief Stops the timer.
 249
 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().
 252 */
 253 void QDeclarative1Timer::stop()
 254 {
 255     setRunning(false);
 256 }
 257
 258 /*!
 259     \qmlmethod QtQuick1::Timer::restart()
 260     \brief Restarts the timer.
 261
 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().
 265 */
 266 void QDeclarative1Timer::restart()
 267 {
 268     setRunning(false);
 269     setRunning(true);
 270 }
 271
 272 void QDeclarative1Timer::update()
 273 {
 274     Q_D(QDeclarative1Timer);
 275     if (d->classBegun && !d->componentComplete)
 276         return;
 277     d->pause.stop();
 278     if (d->running) {
 279         d->pause.setCurrentTime(0);
 280         d->pause.setLoopCount(d->repeating ? -1 : 1);
 281         d->pause.setDuration(d->interval);
 282         d->pause.start();
 283         if (d->triggeredOnStart && d->firstTick) {
 284             QCoreApplication::removePostedEvents(this, QEvent::MetaCall);
 285             QMetaObject::invokeMethod(this, "ticked", Qt::QueuedConnection);
 286         }
 287     }
 288 }
 289
 290 void QDeclarative1Timer::classBegin()
 291 {
 292     Q_D(QDeclarative1Timer);
 293     d->classBegun = true;
 294 }
 295
 296 void QDeclarative1Timer::componentComplete()
 297 {
 298     Q_D(QDeclarative1Timer);
 299     d->componentComplete = true;
 300     update();
 301 }
 302
 303 /*!
 304     \qmlsignal QtQuick1::Timer::onTriggered()
 305
 306     This handler is called when the Timer is triggered.
 307 */
 308 void QDeclarative1Timer::ticked()
 309 {
 310     Q_D(QDeclarative1Timer);
 311     if (d->running && (d->pause.currentTime() > 0 || (d->triggeredOnStart && d->firstTick)))
 312         emit triggered();
 313     d->firstTick = false;
 314 }
 315
 316 void QDeclarative1Timer::finished()
 317 {
 318     Q_D(QDeclarative1Timer);
 319     if (d->repeating || !d->running)
 320         return;
 321     emit triggered();
 322     d->running = false;
 323     d->firstTick = false;
 324     emit runningChanged();
 325 }
 326
 327
 328
 329 QT_END_NAMESPACE