src/quick/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 "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:
  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     \inqmlmodule QtQuick 2
  74     \ingroup qml-utility-elements
  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
 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 QtQuick2::Timer::interval
 122
 123     Sets the \a interval between triggers, in milliseconds.
 124
 125     The default interval is 1000 milliseconds.
 126 */
 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
 137 int QDeclarativeTimer::interval() const
 138 {
 139     Q_D(const QDeclarativeTimer);
 140     return d->interval;
 141 }
 142
 143 /*!
 144     \qmlproperty bool QtQuick2::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 */
 154 bool QDeclarativeTimer::isRunning() const
 155 {
 156     Q_D(const QDeclarativeTimer);
 157     return d->running;
 158 }
 159
 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 QtQuick2::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 */
 182 bool QDeclarativeTimer::isRepeating() const
 183 {
 184     Q_D(const QDeclarativeTimer);
 185     return d->repeating;
 186 }
 187
 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 QtQuick2::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 */
 215 bool QDeclarativeTimer::triggeredOnStart() const
 216 {
 217     Q_D(const QDeclarativeTimer);
 218     return d->triggeredOnStart;
 219 }
 220
 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 QtQuick2::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 */
 238 void QDeclarativeTimer::start()
 239 {
 240     setRunning(true);
 241 }
 242
 243 /*!
 244     \qmlmethod QtQuick2::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 */
 250 void QDeclarativeTimer::stop()
 251 {
 252     setRunning(false);
 253 }
 254
 255 /*!
 256     \qmlmethod QtQuick2::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 */
 263 void QDeclarativeTimer::restart()
 264 {
 265     setRunning(false);
 266     setRunning(true);
 267 }
 268
 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
 287 void QDeclarativeTimer::classBegin()
 288 {
 289     Q_D(QDeclarativeTimer);
 290     d->classBegun = true;
 291 }
 292
 293 void QDeclarativeTimer::componentComplete()
 294 {
 295     Q_D(QDeclarativeTimer);
 296     d->componentComplete = true;
 297     update();
 298 }
 299
 300 /*!
 301     \qmlsignal QtQuick2::Timer::onTriggered()
 302
 303     This handler is called when the Timer is triggered.
 304 */
 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
 313 void QDeclarativeTimer::finished()
 314 {
 315     Q_D(QDeclarativeTimer);
 316     if (d->repeating || !d->running)
 317         return;
 318     d->running = false;
 319     d->firstTick = false;
 320     emit triggered();
 321     emit runningChanged();
 322 }
 323
 324 QT_END_NAMESPACE