1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtDeclarative module of the Qt Toolkit.

     8 **

     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

    14 ** this package.

    15 **

    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.

    23 **

    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.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "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 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     \since 4.7

    74     \brief The Timer item triggers a handler at a specified interval.

    75 

    76     A timer can be used to trigger an action either once, or repeatedly

    77     at a given interval.

    78 

    79     Here is a timer that shows the current date and time, and updates

    80     the text every 500 milliseconds:

    81 

    82     \qml

    83     Timer {

    84         interval: 500; running: true; repeat: true

    85         onTriggered: time.text = Date().toString()

    86     }

    87     Text {

    88         id: time

    89     }

    90     \endqml

    91 

    92     QDeclarativeTimer is synchronized with the animation timer.  Since the animation

    93     timer is usually set to 60fps, the resolution of QDeclarativeTimer will be

    94     at best 16ms.

    95 

    96     If the Timer is running and one of its properties is changed, the

    97     elapsed time will be reset.  For example, if a Timer with interval of

    98     1000ms has its \e repeat property changed 500ms after starting, the

    99     elapsed time will be reset to 0, and the Timer will be triggered

   100     1000ms later.

   101 

   102     \sa {QtDeclarative}

   103 */

   104 

   105 QDeclarativeTimer::QDeclarativeTimer(QObject *parent)

   106     : QObject(*(new QDeclarativeTimerPrivate), parent)

   107 {

   108     Q_D(QDeclarativeTimer);

   109     connect(&d->pause, SIGNAL(currentLoopChanged(int)), this, SLOT(ticked()));

   110     connect(&d->pause, SIGNAL(finished()), this, SLOT(finished()));

   111     d->pause.setLoopCount(1);

   112     d->pause.setDuration(d->interval);

   113 }

   114 

   115 /*!

   116     \qmlproperty int Timer::interval

   117 

   118     Sets the \a interval between triggers, in milliseconds.

   119 

   120     The default interval is 1000 milliseconds.

   121 */

   122 void QDeclarativeTimer::setInterval(int interval)

   123 {

   124     Q_D(QDeclarativeTimer);

   125     if (interval != d->interval) {

   126         d->interval = interval;

   127         update();

   128         emit intervalChanged();

   129     }

   130 }

   131 

   132 int QDeclarativeTimer::interval() const

   133 {

   134     Q_D(const QDeclarativeTimer);

   135     return d->interval;

   136 }

   137 

   138 /*!

   139     \qmlproperty bool Timer::running

   140 

   141     If set to true, starts the timer; otherwise stops the timer.

   142     For a non-repeating timer, \a running is set to false after the

   143     timer has been triggered.

   144 

   145     \a running defaults to false.

   146 

   147     \sa repeat

   148 */

   149 bool QDeclarativeTimer::isRunning() const

   150 {

   151     Q_D(const QDeclarativeTimer);

   152     return d->running;

   153 }

   154 

   155 void QDeclarativeTimer::setRunning(bool running)

   156 {

   157     Q_D(QDeclarativeTimer);

   158     if (d->running != running) {

   159         d->running = running;

   160         d->firstTick = true;

   161         emit runningChanged();

   162         update();

   163     }

   164 }

   165 

   166 /*!

   167     \qmlproperty bool Timer::repeat

   168 

   169     If \a repeat is true the timer is triggered repeatedly at the

   170     specified interval; otherwise, the timer will trigger once at the

   171     specified interval and then stop (i.e. running will be set to false).

   172 

   173     \a repeat defaults to false.

   174 

   175     \sa running

   176 */

   177 bool QDeclarativeTimer::isRepeating() const

   178 {

   179     Q_D(const QDeclarativeTimer);

   180     return d->repeating;

   181 }

   182 

   183 void QDeclarativeTimer::setRepeating(bool repeating)

   184 {

   185     Q_D(QDeclarativeTimer);

   186     if (repeating != d->repeating) {

   187         d->repeating = repeating;

   188         update();

   189         emit repeatChanged();

   190     }

   191 }

   192 

   193 /*!

   194     \qmlproperty bool Timer::triggeredOnStart

   195 

   196     When a timer is started, the first trigger is usually after the specified

   197     interval has elapsed.  It is sometimes desirable to trigger immediately

   198     when the timer is started; for example, to establish an initial

   199     state.

   200 

   201     If \a triggeredOnStart is true, the timer is triggered immediately

   202     when started, and subsequently at the specified interval. Note that if

   203     \e repeat is set to false, the timer is triggered twice; once on start,

   204     and again at the interval.

   205 

   206     \a triggeredOnStart defaults to false.

   207 

   208     \sa running

   209 */

   210 bool QDeclarativeTimer::triggeredOnStart() const

   211 {

   212     Q_D(const QDeclarativeTimer);

   213     return d->triggeredOnStart;

   214 }

   215 

   216 void QDeclarativeTimer::setTriggeredOnStart(bool triggeredOnStart)

   217 {

   218     Q_D(QDeclarativeTimer);

   219     if (d->triggeredOnStart != triggeredOnStart) {

   220         d->triggeredOnStart = triggeredOnStart;

   221         update();

   222         emit triggeredOnStartChanged();

   223     }

   224 }

   225 

   226 /*!

   227     \qmlmethod Timer::start()

   228     \brief Starts the timer.

   229 

   230     If the timer is already running, calling this method has no effect.  The

   231     \c running property will be true following a call to \c start().

   232 */

   233 void QDeclarativeTimer::start()

   234 {

   235     setRunning(true);

   236 }

   237 

   238 /*!

   239     \qmlmethod Timer::stop()

   240     \brief Stops the timer.

   241 

   242     If the timer is not running, calling this method has no effect.  The

   243     \c running property will be false following a call to \c stop().

   244 */

   245 void QDeclarativeTimer::stop()

   246 {

   247     setRunning(false);

   248 }

   249 

   250 /*!

   251     \qmlmethod Timer::restart()

   252     \brief Restarts the timer.

   253 

   254     If the Timer is not running it will be started, otherwise it will be

   255     stopped, reset to initial state and started.  The \c running property

   256     will be true following a call to \c restart().

   257 */

   258 void QDeclarativeTimer::restart()

   259 {

   260     setRunning(false);

   261     setRunning(true);

   262 }

   263 

   264 void QDeclarativeTimer::update()

   265 {

   266     Q_D(QDeclarativeTimer);

   267     if (d->classBegun && !d->componentComplete)

   268         return;

   269     d->pause.stop();

   270     if (d->running) {

   271         d->pause.setCurrentTime(0);

   272         d->pause.setLoopCount(d->repeating ? -1 : 1);

   273         d->pause.setDuration(d->interval);

   274         d->pause.start();

   275         if (d->triggeredOnStart && d->firstTick) {

   276             QCoreApplication::removePostedEvents(this, QEvent::MetaCall);

   277             QMetaObject::invokeMethod(this, "ticked", Qt::QueuedConnection);

   278         }

   279     }

   280 }

   281 

   282 void QDeclarativeTimer::classBegin()

   283 {

   284     Q_D(QDeclarativeTimer);

   285     d->classBegun = true;

   286 }

   287 

   288 void QDeclarativeTimer::componentComplete()

   289 {

   290     Q_D(QDeclarativeTimer);

   291     d->componentComplete = true;

   292     update();

   293 }

   294 

   295 /*!

   296     \qmlsignal Timer::onTriggered()

   297 

   298     This handler is called when the Timer is triggered.

   299 */

   300 void QDeclarativeTimer::ticked()

   301 {

   302     Q_D(QDeclarativeTimer);

   303     if (d->running && (d->pause.currentTime() > 0 || (d->triggeredOnStart && d->firstTick)))

   304         emit triggered();

   305     d->firstTick = false;

   306 }

   307 

   308 void QDeclarativeTimer::finished()

   309 {

   310     Q_D(QDeclarativeTimer);

   311     if (d->repeating || !d->running)

   312         return;

   313     emit triggered();

   314     d->running = false;

   315     d->firstTick = false;

   316     emit runningChanged();

   317 }

   318 

   319 QT_END_NAMESPACE