summaryrefslogtreecommitdiffstats
path: root/doc/src/timers.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/timers.qdoc')
-rw-r--r--doc/src/timers.qdoc136
1 files changed, 136 insertions, 0 deletions
diff --git a/doc/src/timers.qdoc b/doc/src/timers.qdoc
new file mode 100644
index 0000000..4f54343
--- /dev/null
+++ b/doc/src/timers.qdoc
@@ -0,0 +1,136 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page timers.html
+ \title Timers
+ \ingroup architecture
+ \brief How to use timers in your application.
+
+ QObject, the base class of all Qt objects, provides the basic
+ timer support in Qt. With QObject::startTimer(), you start a
+ timer with an interval in milliseconds as argument. The function
+ returns a unique integer timer ID. The timer will now fire at
+ regular intervals until you explicitly call QObject::killTimer()
+ with the timer ID.
+
+ For this mechanism to work, the application must run in an event
+ loop. You start an event loop with QApplication::exec(). When a
+ timer fires, the application sends a QTimerEvent, and the flow of
+ control leaves the event loop until the timer event is processed.
+ This implies that a timer cannot fire while your application is
+ busy doing something else. In other words: the accuracy of timers
+ depends on the granularity of your application.
+
+ In multithreaded applications, you can use the timer mechanism in
+ any thread that has an event loop. To start an event loop from a
+ non-GUI thread, use QThread::exec(). Qt uses the the object's
+ \l{QObject::thread()}{thread affinity} to determine which thread
+ will deliver the QTimerEvent. Because of this, you must start and
+ stop all timers in the object's thread; it is not possible to
+ start timers for objects in another thread.
+
+ The upper limit for the interval value is determined by the number
+ of milliseconds that can be specified in a signed integer
+ (in practice, this is a period of just over 24 days). The accuracy
+ depends on the underlying operating system. Windows 98 has 55
+ millisecond accuracy; other systems that we have tested can handle
+ 1 millisecond intervals.
+
+ The main API for the timer functionality is QTimer. That class
+ provides regular timers that emit a signal when the timer fires, and
+ inherits QObject so that it fits well into the ownership structure
+ of most GUI programs. The normal way of using it is like this:
+
+ \snippet doc/src/snippets/timers/timers.cpp 0
+ \snippet doc/src/snippets/timers/timers.cpp 1
+ \snippet doc/src/snippets/timers/timers.cpp 2
+
+ The QTimer object is made into a child of this widget so that,
+ when this widget is deleted, the timer is deleted too.
+ Next, its \l{QTimer::}{timeout()} signal is connected to the slot
+ that will do the work, it is started with a value of 1000
+ milliseconds, indicating that it will time out every second.
+
+ QTimer also provides a static function for single-shot timers.
+ For example:
+
+ \snippet doc/src/snippets/timers/timers.cpp 3
+
+ 200 milliseconds (0.2 seconds) after this line of code is
+ executed, the \c updateCaption() slot will be called.
+
+ For QTimer to work, you must have an event loop in your
+ application; that is, you must call QCoreApplication::exec()
+ somewhere. Timer events will be delivered only while the event
+ loop is running.
+
+ In multithreaded applications, you can use QTimer in any thread
+ that has an event loop. To start an event loop from a non-GUI
+ thread, use QThread::exec(). Qt uses the the timer's
+ \l{QObject::thread()}{thread affinity} to determine which thread
+ will emit the \l{QTimer::}{timeout()} signal. Because of this, you
+ must start and stop the timer in its thread; it is not possible to
+ start a timer from another thread.
+
+ The \l{widgets/analogclock}{Analog Clock} example shows how to use
+ QTimer to redraw a widget at regular intervals. From \c{AnalogClock}'s
+ implementation:
+
+ \snippet examples/widgets/analogclock/analogclock.cpp 0
+ \snippet examples/widgets/analogclock/analogclock.cpp 2
+ \snippet examples/widgets/analogclock/analogclock.cpp 3
+ \snippet examples/widgets/analogclock/analogclock.cpp 4
+ \snippet examples/widgets/analogclock/analogclock.cpp 5
+ \snippet examples/widgets/analogclock/analogclock.cpp 6
+ \dots
+ \snippet examples/widgets/analogclock/analogclock.cpp 7
+
+ Every second, QTimer will call the QWidget::update() slot to
+ refresh the clock's display.
+
+ If you already have a QObject subclass and want an easy
+ optimization, you can use QBasicTimer instead of QTimer. With
+ QBasicTimer, you must reimplement
+ \l{QObject::timerEvent()}{timerEvent()} in your QObject subclass
+ and handle the timeout there. The \l{widgets/wiggly}{Wiggly}
+ example shows how to use QBasicTimer.
+*/