← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to src/corelib/kernel/qtimer.cpp

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-08-24 04:09:09 UTC
  • Revision ID: james.westby@ubuntu.com-20050824040909-xmxe9jfr4a0w5671
Tags: upstream-4.0.0
Import upstream version 4.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/corelib/kernel/qtimer.cpp
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 1992-2005 Trolltech AS. All rights reserved.
 
4
**
 
5
** This file is part of the core module of the Qt Toolkit.
 
6
**
 
7
** This file may be distributed under the terms of the Q Public License
 
8
** as defined by Trolltech AS of Norway and appearing in the file
 
9
** LICENSE.QPL included in the packaging of this file.
 
10
**
 
11
** This file may be distributed and/or modified under the terms of the
 
12
** GNU General Public License version 2 as published by the Free Software
 
13
** Foundation and appearing in the file LICENSE.GPL included in the
 
14
** packaging of this file.
 
15
**
 
16
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
 
17
**   information about Qt Commercial License Agreements.
 
18
** See http://www.trolltech.com/qpl/ for QPL licensing information.
 
19
** See http://www.trolltech.com/gpl/ for GPL licensing information.
 
20
**
 
21
** Contact info@trolltech.com if any conditions of this licensing are
 
22
** not clear to you.
 
23
**
 
24
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 
25
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 
26
**
 
27
****************************************************************************/
 
28
 
 
29
#include "qtimer.h"
 
30
 
 
31
#include "qabstracteventdispatcher.h"
 
32
#include "qcoreapplication.h"
 
33
 
 
34
/*!
 
35
    \class QTimer
 
36
    \brief The QTimer class provides repetitive and single-shot timers.
 
37
 
 
38
    \ingroup time
 
39
    \ingroup events
 
40
    \mainclass
 
41
 
 
42
    The QTimer class provides a high-level programming interface for
 
43
    timers. To use it, create a QTimer, connect its timeout() signal
 
44
    to the appropriate slots, and call start(). From then on it will
 
45
    emit the timeout() signal at constant intervals.
 
46
 
 
47
    Example for a one second (1000 millisecond) timer (from the
 
48
    \l{widgets/analogclock}{Analog Clock} example):
 
49
 
 
50
    \quotefromfile widgets/analogclock/analogclock.cpp
 
51
    \skipto = new QTimer
 
52
    \printline = new
 
53
    \printline connect
 
54
    \printline start(1000)
 
55
 
 
56
    From then on, the \c update() slot is called every second.
 
57
 
 
58
    You can set a timer to time out only once by calling
 
59
    setSingleShot(true). You can also use the static
 
60
    QTimer::singleShot() function to call a slot after a specified
 
61
    interval:
 
62
 
 
63
    \quotefromfile snippets/timers/timers.cpp
 
64
    \skipto singleShot
 
65
    \printline singleShot
 
66
 
 
67
    As a special case, a QTimer with a timeout of 0 will time out as
 
68
    soon as all the events in the window system's event queue have
 
69
    been processed. This can be used to do heavy work while providing
 
70
    a snappy user interface:
 
71
 
 
72
    \skipto ZERO-CASE
 
73
    \skipline ZERO
 
74
    \printline = new QTimer
 
75
    \printline connect
 
76
    \printline start
 
77
 
 
78
    \c processOneThing() will from then on be called repeatedly. It
 
79
    should be written in such a way that it always returns quickly
 
80
    (typically after processing one data item) so that Qt can deliver
 
81
    events to widgets and stop the timer as soon as it has done all
 
82
    its work. This is the traditional way of implementing heavy work
 
83
    in GUI applications; multithreading is now becoming available on
 
84
    more and more platforms, and we expect that zero-milliseconds
 
85
    QTimers will gradually be replaced by \l{QThread}s.
 
86
 
 
87
    Note that QTimer's accuracy depends on the underlying operating
 
88
    system and hardware. Most platforms support an accuracy of 1
 
89
    milliseconds, but Windows 95 and 98 support only 55. If Qt is
 
90
    unable to deliver the requested number of timer clicks, it will
 
91
    silently discard some.
 
92
 
 
93
    An alternative to using QTimer is to call QObject::startTimer()
 
94
    for your object and reimplement the QObject::timerEvent() event
 
95
    handler in your class (which must inherit QObject). The
 
96
    disadvantage is that timerEvent() does not support such
 
97
    high-level features as single-shot timers or signals.
 
98
 
 
99
    Another alternative to using QTimer is to use QBasicTimer. It is
 
100
    typically less cumbersome than using QObject::startTimer()
 
101
    directly. See \l{timers.html}{Timers} for an overview of all
 
102
    three approaches.
 
103
 
 
104
    Some operating systems limit the number of timers that may be
 
105
    used; Qt tries to work around these limitations.
 
106
 
 
107
    \sa QBasicTimer, QTimerEvent, QObject::timerEvent(), Timers
 
108
*/
 
109
 
 
110
 
 
111
static const int INV_TIMER = -1;                // invalid timer id
 
112
 
 
113
/*!
 
114
    Constructs a timer with the given \a parent.
 
115
*/
 
116
 
 
117
QTimer::QTimer(QObject *parent)
 
118
    : QObject(parent), id(INV_TIMER), inter(0), del(0), single(0), nulltimer(0)
 
119
{
 
120
}
 
121
 
 
122
 
 
123
#ifdef QT3_SUPPORT
 
124
/*!
 
125
    Constructs a timer called \a name, with a \a parent.
 
126
*/
 
127
 
 
128
QTimer::QTimer(QObject *parent, const char *name)
 
129
    : QObject(parent), id(INV_TIMER), single(0), nulltimer(0)
 
130
{
 
131
    setObjectName(QString::fromAscii(name));
 
132
}
 
133
#endif
 
134
 
 
135
/*!
 
136
    Destroys the timer.
 
137
*/
 
138
 
 
139
QTimer::~QTimer()
 
140
{
 
141
    if (id != INV_TIMER)                        // stop running timer
 
142
        stop();
 
143
}
 
144
 
 
145
 
 
146
/*!
 
147
    \fn void QTimer::timeout()
 
148
 
 
149
    This signal is emitted when the timer times out.
 
150
 
 
151
    \sa interval, start(), stop()
 
152
*/
 
153
 
 
154
/*!
 
155
    \fn bool QTimer::isActive() const
 
156
 
 
157
    Returns true if the timer is running (pending); otherwise returns
 
158
    false.
 
159
*/
 
160
 
 
161
/*!
 
162
    \fn int QTimer::timerId() const
 
163
 
 
164
    Returns the ID of the timer if the timer is running; otherwise returns
 
165
    -1.
 
166
*/
 
167
 
 
168
 
 
169
/*! \overload
 
170
 
 
171
    Starts or restarts the timer with the timeout specified in \l interval.
 
172
 
 
173
    If \l singleShot is true, the timer will be activated only once.
 
174
*/
 
175
void QTimer::start()
 
176
{
 
177
    if (id != INV_TIMER)                        // stop running timer
 
178
        stop();
 
179
    nulltimer = (!inter && single);
 
180
    id = QObject::startTimer(inter);
 
181
}
 
182
 
 
183
/*!
 
184
    Starts or restarts the timer with a timeout interval of \a msec
 
185
    milliseconds.
 
186
*/
 
187
void QTimer::start(int msec)
 
188
{
 
189
    setInterval(msec);
 
190
    start();
 
191
}
 
192
 
 
193
 
 
194
#ifdef QT3_SUPPORT
 
195
/*! \overload
 
196
 
 
197
Call setSingleShot(\a sshot) and start(\a msec) instead.
 
198
*/
 
199
 
 
200
int QTimer::start(int msec, bool sshot)
 
201
{
 
202
    if (id >=0 && nulltimer && !msec && sshot)
 
203
        return id;
 
204
    stop();
 
205
    setInterval(msec);
 
206
    setSingleShot(sshot);
 
207
    start();
 
208
    return timerId();
 
209
}
 
210
#endif
 
211
 
 
212
 
 
213
/*!
 
214
    Stops the timer.
 
215
 
 
216
    \sa start()
 
217
*/
 
218
 
 
219
void QTimer::stop()
 
220
{
 
221
    if (id != INV_TIMER) {
 
222
        QObject::killTimer(id);
 
223
        id = INV_TIMER;
 
224
    }
 
225
}
 
226
 
 
227
 
 
228
/*!
 
229
    \reimp
 
230
*/
 
231
void QTimer::timerEvent(QTimerEvent *e)
 
232
{
 
233
    if (e->timerId() == id) {
 
234
        if (single)
 
235
            stop();
 
236
        emit timeout();
 
237
    }
 
238
}
 
239
 
 
240
class QSingleShotTimer : public QObject
 
241
{
 
242
    Q_OBJECT
 
243
    int timerId;
 
244
public:
 
245
    ~QSingleShotTimer();
 
246
    QSingleShotTimer(int msec, QObject *r, const char * m);
 
247
signals:
 
248
    void timeout();
 
249
protected:
 
250
    void timerEvent(QTimerEvent *);
 
251
};
 
252
 
 
253
QSingleShotTimer::QSingleShotTimer(int msec, QObject *receiver, const char *member)
 
254
    : QObject(QAbstractEventDispatcher::instance())
 
255
{
 
256
    connect(this, SIGNAL(timeout()), receiver, member);
 
257
    timerId = startTimer(msec);
 
258
}
 
259
 
 
260
QSingleShotTimer::~QSingleShotTimer()
 
261
{
 
262
    if (timerId > 0)
 
263
        killTimer(timerId);
 
264
}
 
265
 
 
266
void QSingleShotTimer::timerEvent(QTimerEvent *)
 
267
{
 
268
    // need to kill the timer _before_ we emit timeout() in case the
 
269
    // slot connected to timeout calls processEvents()
 
270
    if (timerId > 0)
 
271
        killTimer(timerId);
 
272
    timerId = -1;
 
273
    emit timeout();
 
274
    delete this;
 
275
}
 
276
 
 
277
#include "qtimer.moc"
 
278
 
 
279
/*!
 
280
    \reentrant
 
281
    This static function calls a slot after a given time interval.
 
282
 
 
283
    It is very convenient to use this function because you do not need
 
284
    to bother with a \link QObject::timerEvent() timerEvent\endlink or
 
285
    create a local QTimer object.
 
286
 
 
287
    Example:
 
288
    \code
 
289
        #include <QApplication>
 
290
        #include <QTimer>
 
291
 
 
292
        int main(int argc, char *argv[])
 
293
        {
 
294
            QApplication app(argc, argv);
 
295
            QTimer::singleShot(60000, &app, SLOT(quit()));
 
296
            ...
 
297
            return app.exec();
 
298
        }
 
299
    \endcode
 
300
 
 
301
    This sample program automatically terminates after 10 minutes
 
302
    (600000 milliseconds).
 
303
 
 
304
    The \a receiver is the receiving object and the \a member is the
 
305
    slot. The time interval is \a msec milliseconds.
 
306
 
 
307
    \sa start()
 
308
*/
 
309
 
 
310
void QTimer::singleShot(int msec, QObject *receiver, const char *member)
 
311
{
 
312
    if (receiver && member)
 
313
        (void) new QSingleShotTimer(msec, receiver, member);
 
314
}
 
315
 
 
316
/*!
 
317
    \property QTimer::singleShot
 
318
    \brief whether the timer is a single-shot timer
 
319
 
 
320
    A single-shot timer fires only once, non-single-shot timers fire
 
321
    every \l interval milliseconds.
 
322
 
 
323
    \sa interval, singleShot()
 
324
*/
 
325
 
 
326
/*!
 
327
    \property QTimer::interval
 
328
    \brief the timeout interval in milliseconds
 
329
 
 
330
    The default value for this property is 0.  A QTimer with a timeout
 
331
    interval of 0 will time out as soon as all the events in the window
 
332
    system's event queue have been processed.
 
333
 
 
334
    Setting the interval of an active timer changes its timerId().
 
335
 
 
336
    \sa singleShot
 
337
*/
 
338
void QTimer::setInterval(int msec)
 
339
{
 
340
    inter = msec;
 
341
    if (id != INV_TIMER) {                        // create new timer
 
342
        QObject::killTimer(id);                        // restart timer
 
343
        id = QObject::startTimer(msec);
 
344
    }
 
345
}
 
346
 
 
347
/*! \fn void QTimer::changeInterval(int msec)
 
348
 
 
349
   Use setInterval(msec) or start(msec) instead.
 
350
*/