Timers

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" every interval milliseconds, 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.

There is practically no upper limit for the interval value (more than one year is possible). The accuracy depends on the underlying operating system. Windows 95/98 has 55 millisecond (18.2 times per second) accuracy; other systems that we have tested (UNIX X11 and Windows NT) 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:

    QTimer * counter = new QTimer( this );
    connect( counter, SIGNAL(timeout()),
             this, SLOT(updateCaption()) );
    counter->start( 1000 );

The counter timer is made into a child of this widget, so that when this widget is deleted, the timer is deleted too. Next, its timeout signal is connected to the slot that will do the work, and finally it's started.

QTimer also provides a simple one-shot timer API. QButton uses this to show the button being pressed down and then (0.1 seconds later) be released when the keyboard is used to "press" a button, for example:

    QTimer::singleShot( 100, this, SLOT(animateTimeout()) );

0.1 seconds after this line of code is executed, the same button's animateTimeout() slot is called.

Here is an outline of a slightly longer example that combines object communication via signals and slots with a QTimer object. It demonstrates how to use timers to perform intensive calculations in a single-threaded application without blocking the user interface.

    // The Mandelbrot class uses a QTimer to calculate the mandelbrot
    // set one scanline at a time without blocking the CPU. It
    // inherits QObject to use signals and slots. Calling start()
    // starts the calculation. The done() signal is emitted when it
    // has finished. Note that this example is not complete, just an
    // outline.

    class Mandelbrot : public QObject
    {
        Q_OBJECT // required for signals/slots
    public:
        Mandelbrot( QObject *parent=0, const char *name );
        ...
    public slots:
        void start();
    signals:
        void done();
    private slots:
        void calculate();
        private:
        QTimer timer;
        ...
    };

    //
    // Constructs and initializes a Mandelbrot object.
    //

    Mandelbrot::Mandelbrot( QObject *parent=0, const char *name )
    : QObject( parent, name )
    {
        connect( &timer, SIGNAL(timeout()), SLOT(calculate()) );
        ...
    }

    //
    // Starts the calculation task. The internal calculate() slot
    // will be activated every 10 milliseconds.
    //

    void Mandelbrot::start()
    {
        if ( !timer.isActive() ) // not already running
            timer.start( 10 );   // timeout every 10 ms
    }

    //
    // Calculates one scanline at a time.
    // Emits the done() signal when finished.
    //

    void Mandelbrot::calculate()
    {
        ...                // perform the calculation for a scanline
        if ( finished ) {  // no more scanlines
            timer.stop();
            emit done();
        }
    }