--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/howtos/timers.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,137 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page timers.html
+ \title Timers
+ \brief How to use timers in your application.
+
+ \ingroup best-practices
+
+ 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 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 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.
+*/