Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
QTimer Class Reference

\inmodule QtCore More...

#include <qtimer.h>

+ Inheritance diagram for QTimer:
+ Collaboration diagram for QTimer:

Public Slots

void start (int msec)
 Starts or restarts the timer with a timeout interval of msec milliseconds.
 
void start ()
 
void stop ()
 Stops the timer.
 
- Public Slots inherited from QObject
void deleteLater ()
 \threadsafe
 

Signals

void timeout (QPrivateSignal)
 This signal is emitted when the timer times out.
 
- Signals inherited from QObject
void destroyed (QObject *=nullptr)
 This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
 
void objectNameChanged (const QString &objectName, QPrivateSignal)
 This signal is emitted after the object's name has been changed.
 

Public Member Functions

 QTimer (QObject *parent=nullptr)
 Constructs a timer with the given parent.
 
 ~QTimer ()
 Destroys the timer.
 
bool isActive () const
 Returns true if the timer is running; otherwise returns false.
 
QBindable< bool > bindableActive ()
 
int timerId () const
 Returns the ID of the timer if the timer is running; otherwise returns -1.
 
Qt::TimerId id () const
 
void setInterval (int msec)
 
int interval () const
 
QBindable< int > bindableInterval ()
 
int remainingTime () const
 
void setTimerType (Qt::TimerType atype)
 
Qt::TimerType timerType () const
 
QBindable< Qt::TimerTypebindableTimerType ()
 
void setSingleShot (bool singleShot)
 
bool isSingleShot () const
 
QBindable< bool > bindableSingleShot ()
 
template<typename ... Args>
QMetaObject::Connection callOnTimeout (Args &&...args)
 
void setInterval (std::chrono::milliseconds value)
 
std::chrono::milliseconds intervalAsDuration () const
 
std::chrono::milliseconds remainingTimeAsDuration () const
 
void start (std::chrono::milliseconds value)
 
- Public Member Functions inherited from QObject
Q_INVOKABLE QObject (QObject *parent=nullptr)
 Constructs an object with parent object parent.
 
virtual ~QObject ()
 Destroys the object, deleting all its child objects.
 
virtual bool event (QEvent *event)
 This virtual function receives events to an object and should return true if the event e was recognized and processed.
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 Filters events if this object has been installed as an event filter for the watched object.
 
QString objectName () const
 
Q_WEAK_OVERLOAD void setObjectName (const QString &name)
 Sets the object's name to name.
 
void setObjectName (QAnyStringView name)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
QBindable< QStringbindableObjectName ()
 
bool isWidgetType () const
 Returns true if the object is a widget; otherwise returns false.
 
bool isWindowType () const
 Returns true if the object is a window; otherwise returns false.
 
bool isQuickItemType () const
 Returns true if the object is a QQuickItem; otherwise returns false.
 
bool signalsBlocked () const noexcept
 Returns true if signals are blocked; otherwise returns false.
 
bool blockSignals (bool b) noexcept
 If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
 
QThreadthread () const
 Returns the thread in which the object lives.
 
bool moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
 Changes the thread affinity for this object and its children and returns true on success.
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
 
int startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
 
void killTimer (int id)
 Kills the timer with timer identifier, id.
 
void killTimer (Qt::TimerId id)
 
template<typename T >
findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
 
template<typename T >
QList< T > findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.
 
template<typename T >
findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
template<typename T >
QList< T > findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
const QObjectListchildren () const
 Returns a list of child objects.
 
void setParent (QObject *parent)
 Makes the object a child of parent.
 
void installEventFilter (QObject *filterObj)
 Installs an event filter filterObj on this object.
 
void removeEventFilter (QObject *obj)
 Removes an event filter object obj from this object.
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
 
bool disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
 
bool disconnect (const QObject *receiver, const char *member=nullptr) const
 
void dumpObjectTree () const
 Dumps a tree of children to the debug output.
 
void dumpObjectInfo () const
 Dumps information about signal connections, etc.
 
bool setProperty (const char *name, const QVariant &value)
 Sets the value of the object's name property to value.
 
bool setProperty (const char *name, QVariant &&value)
 
QVariant property (const char *name) const
 Returns the value of the object's name property.
 
QList< QByteArraydynamicPropertyNames () const
 
QBindingStoragebindingStorage ()
 
const QBindingStoragebindingStorage () const
 
QObjectparent () const
 Returns a pointer to the parent object.
 
bool inherits (const char *classname) const
 Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false.
 

Static Public Member Functions

static void singleShot (int msec, const QObject *receiver, const char *member)
 \reentrant
 
static void singleShot (int msec, Qt::TimerType timerType, const QObject *receiver, const char *member)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. \reentrant.
 
template<typename Duration , typename Functor >
static void singleShot (Duration interval, const typename QtPrivate::ContextTypeForFunctor< Functor >::ContextType *receiver, Functor &&slot)
 
template<typename Duration , typename Functor >
static void singleShot (Duration interval, Qt::TimerType timerType, const typename QtPrivate::ContextTypeForFunctor< Functor >::ContextType *receiver, Functor &&slot)
 
template<typename Duration , typename Functor >
static void singleShot (Duration interval, Functor &&slot)
 
template<typename Duration , typename Functor >
static void singleShot (Duration interval, Qt::TimerType timerType, Functor &&slot)
 
static void singleShot (std::chrono::nanoseconds value, const QObject *receiver, const char *member)
 
static void singleShot (std::chrono::nanoseconds interval, Qt::TimerType timerType, const QObject *receiver, const char *member)
 
- Static Public Member Functions inherited from QObject
static QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
 \threadsafe
 
static QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
 
static bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
 \threadsafe
 
static bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
 
static bool disconnect (const QMetaObject::Connection &)
 Disconnect a connection.
 
template<typename Func1 , typename Func2 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
 
template<typename Func1 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)
 

Protected Member Functions

void timerEvent (QTimerEvent *) override
 \reimp
 
- Protected Member Functions inherited from QObject
QObjectsender () const
 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.
 
int senderSignalIndex () const
 
int receivers (const char *signal) const
 Returns the number of receivers connected to the signal.
 
bool isSignalConnected (const QMetaMethod &signal) const
 
virtual void childEvent (QChildEvent *event)
 This event handler can be reimplemented in a subclass to receive child events.
 
virtual void customEvent (QEvent *event)
 This event handler can be reimplemented in a subclass to receive custom events.
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
 QObject (QObjectPrivate &dd, QObject *parent=nullptr)
 

Properties

bool singleShot
 whether the timer is a single-shot timer
 
int interval
 the timeout interval in milliseconds
 
int remainingTime
 the remaining time in milliseconds
 
Qt::TimerType timerType
 controls the accuracy of the timer
 
bool active
 
- Properties inherited from QObject
QString objectName
 the name of this object
 

Friends

class QChronoTimer
 

Additional Inherited Members

- Protected Attributes inherited from QObject
QScopedPointer< QObjectDatad_ptr
 

Detailed Description

\inmodule QtCore

The QTimer class provides repetitive and single-shot timers.

The QTimer class provides a high-level programming interface for timers. To use it, create a QTimer, connect its timeout() signal to the appropriate slots, and call start(). From then on, it will emit the timeout() signal at constant intervals.

Example for a one second (1000 millisecond) timer (from the \l{widgets/analogclock}{Analog Clock} example):

From then on, the update() slot is called every second.

You can set a timer to time out only once by calling setSingleShot(true). You can also use the static QTimer::singleShot() function to call a slot after a specified interval:

QTimer::singleShot(200, this, &Foo::updateCaption);

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.

As a special case, a QTimer with a timeout of 0 will time out as soon as possible, though the ordering between zero timers and other sources of events is unspecified. Zero timers can be used to do some work while still providing a snappy user interface:

QTimer *timer = new QTimer(this);
connect(timer, &QTimer::timeout, this, &Foo::processOneThing);

From then on, processOneThing() will be called repeatedly. It should be written in such a way that it always returns quickly (typically after processing one data item) so that Qt can deliver events to the user interface and stop the timer as soon as it has done all its work. This is the traditional way of implementing heavy work in GUI applications, but as multithreading is nowadays becoming available on more and more platforms, we expect that zero-millisecond QTimer objects will gradually be replaced by \l{QThread}s.

Definition at line 19 of file qtimer.h.

Constructor & Destructor Documentation

◆ QTimer()

QTimer::QTimer ( QObject * parent = nullptr)
explicit

Constructs a timer with the given parent.

Definition at line 123 of file qtimer.cpp.

◆ ~QTimer()

QTimer::~QTimer ( )

Destroys the timer.

Definition at line 134 of file qtimer.cpp.

Member Function Documentation

◆ bindableActive()

QBindable< bool > QTimer::bindableActive ( )

Definition at line 167 of file qtimer.cpp.

◆ bindableInterval()

QBindable< int > QTimer::bindableInterval ( )

Definition at line 645 of file qtimer.cpp.

◆ bindableSingleShot()

QBindable< bool > QTimer::bindableSingleShot ( )

Definition at line 590 of file qtimer.cpp.

◆ bindableTimerType()

QBindable< Qt::TimerType > QTimer::bindableTimerType ( )

Definition at line 691 of file qtimer.cpp.

◆ callOnTimeout()

template<typename ... Args>
QMetaObject::Connection QTimer::callOnTimeout ( Args &&... args)
inline
Since
5.12

Creates a connection from the timer's timeout() signal to slot. Returns a handle to the connection.

This method is provided for convenience. It's equivalent to calling:

static QMetaObject::Connection connect(const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
\threadsafe
Definition qobject.cpp:2960
void timeout(QPrivateSignal)
This signal is emitted when the timer times out.
@ DirectConnection
QTimer * timer
[3]
Note
This overload is not available when {QT_NO_CONTEXTLESS_CONNECT} is defined, instead use the callOnTimeout() overload that takes a context object.
See also
QObject::connect(), timeout()

Definition at line 101 of file qtimer.h.

◆ id()

Qt::TimerId QTimer::id ( ) const
Since
6.8 Returns a Qt::TimerId representing the timer ID if the timer is running; otherwise returns Qt::TimerId::Invalid.
See also
Qt::TimerId

Definition at line 191 of file qtimer.cpp.

◆ interval()

int QTimer::interval ( ) const

Definition at line 640 of file qtimer.cpp.

◆ intervalAsDuration()

std::chrono::milliseconds QTimer::intervalAsDuration ( ) const
inline
Since
5.8

Returns the interval of this timer as a std::chrono::milliseconds object.

See also
interval

Definition at line 120 of file qtimer.h.

◆ isActive()

bool QTimer::isActive ( ) const

Returns true if the timer is running; otherwise returns false.

Definition at line 162 of file qtimer.cpp.

◆ isSingleShot()

bool QTimer::isSingleShot ( ) const

Definition at line 585 of file qtimer.cpp.

◆ remainingTime()

int QTimer::remainingTime ( ) const

Definition at line 661 of file qtimer.cpp.

◆ remainingTimeAsDuration()

std::chrono::milliseconds QTimer::remainingTimeAsDuration ( ) const
inline
Since
5.8

Returns the time remaining in this timer object as a std::chrono::milliseconds object. If this timer is due or overdue, the returned value is std::chrono::milliseconds::zero(). If the remaining time could not be found or the timer is not running, this function returns a negative duration.

See also
remainingTime()

Definition at line 125 of file qtimer.h.

◆ setInterval() [1/2]

void QTimer::setInterval ( int msec)

Definition at line 609 of file qtimer.cpp.

◆ setInterval() [2/2]

void QTimer::setInterval ( std::chrono::milliseconds value)

Definition at line 614 of file qtimer.cpp.

◆ setSingleShot()

void QTimer::setSingleShot ( bool singleShot)

Definition at line 580 of file qtimer.cpp.

◆ setTimerType()

void QTimer::setTimerType ( Qt::TimerType atype)

Definition at line 681 of file qtimer.cpp.

◆ singleShot() [1/8]

template<typename Duration , typename Functor >
static void QTimer::singleShot ( Duration interval,
const typename QtPrivate::ContextTypeForFunctor< Functor >::ContextType * receiver,
Functor && slot )
inlinestatic

Definition at line 65 of file qtimer.h.

◆ singleShot() [2/8]

template<typename Duration , typename Functor >
static void QTimer::singleShot ( Duration interval,
Functor && slot )
inlinestatic

Definition at line 84 of file qtimer.h.

◆ singleShot() [3/8]

template<typename Duration , typename Functor >
static void QTimer::singleShot ( Duration interval,
Qt::TimerType timerType,
const typename QtPrivate::ContextTypeForFunctor< Functor >::ContextType * receiver,
Functor && slot )
inlinestatic

Definition at line 72 of file qtimer.h.

◆ singleShot() [4/8]

template<typename Duration , typename Functor >
static void QTimer::singleShot ( Duration interval,
Qt::TimerType timerType,
Functor && functor )
inlinestatic
Since
5.4

\reentrant This static function calls functor after interval.

It is very convenient to use this function because you do not need to bother with a \l{QObject::timerEvent()}{timerEvent} or create a local QTimer object.

If context is specified, then the functor will be called only if the context object has not been destroyed before the interval occurs. The functor will then be run the thread of context. The context's thread must have a running Qt event loop.

If functor is a member function of context, then the function will be called on the object.

The interval parameter can be an int (interpreted as a millisecond count) or a std::chrono type that implicitly converts to nanoseconds.

Note
In Qt versions prior to 6.8, the chrono overloads took chrono::milliseconds, not chrono::nanoseconds. The compiler will automatically convert for you, but the conversion may overflow for extremely large milliseconds counts.
See also
start()

Definition at line 89 of file qtimer.h.

◆ singleShot() [5/8]

static void QTimer::singleShot ( int msec,
const QObject * receiver,
const char * member )
static

\reentrant

Deprecated
[6.8] Use the chrono overloads. This static function calls a slot after a given time interval.

It is very convenient to use this function because you do not need to bother with a \l{QObject::timerEvent()}{timerEvent} or create a local QTimer object.

Example:

#include <QApplication>
#include <QTimer>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
...
return app.exec();
}

This sample program automatically terminates after 10 minutes (600,000 milliseconds).

The receiver is the receiving object and the member is the slot. The time interval is msec milliseconds.

See also
start()
Deprecated
[6.8] Use the chrono overloads. This static function calls a slot after a given time interval.

It is very convenient to use this function because you do not need to bother with a \l{QObject::timerEvent()}{timerEvent} or create a local QTimer object.

Example:

#include <QApplication>
#include <QTimer>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
...
return app.exec();
}

This sample program automatically terminates after 10 minutes (600,000 milliseconds).

The receiver is the receiving object and the member is the slot. The time interval is msec milliseconds.

See also
start()

◆ singleShot() [6/8]

static void QTimer::singleShot ( int msec,
Qt::TimerType timerType,
const QObject * receiver,
const char * member )
static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. \reentrant.

Deprecated
[6.8] Use the chrono overloads. This static function calls a slot after a given time interval.

It is very convenient to use this function because you do not need to bother with a \l{QObject::timerEvent()}{timerEvent} or create a local QTimer object.

The receiver is the receiving object and the member is the slot. The time interval is msec milliseconds. The timerType affects the accuracy of the timer.

See also
start()
Deprecated
[6.8] Use the chrono overloads. This static function calls a slot after a given time interval.

It is very convenient to use this function because you do not need to bother with a \l{QObject::timerEvent()}{timerEvent} or create a local QTimer object.

The receiver is the receiving object and the member is the slot. The time interval is msec milliseconds. The timerType affects the accuracy of the timer.

See also
start()

◆ singleShot() [7/8]

void QTimer::singleShot ( std::chrono::nanoseconds nsec,
Qt::TimerType timerType,
const QObject * receiver,
const char * member )
static
\fn void QTimer::singleShot(std::chrono::nanoseconds nsec, const QObject *receiver, const char *member)
\since 5.8
\overload
\reentrant

This static function calls a slot after a given time interval.

It is very convenient to use this function because you do not need
to bother with a \l{QObject::timerEvent()}{timerEvent} or
create a local QTimer object.

The \a receiver is the receiving object and the \a member is the slot. The
time interval is given in the duration object \a nsec.

! [qtimer-ns-overflow]

Note
In Qt versions prior to 6.8, this function took chrono::milliseconds, not chrono::nanoseconds. The compiler will automatically convert for you, but the conversion may overflow for extremely large milliseconds counts. ! [qtimer-ns-overflow]
\sa start()
Since
5.8 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. \reentrant

This static function calls a slot after a given time interval.

It is very convenient to use this function because you do not need to bother with a \l{QObject::timerEvent()}{timerEvent} or create a local QTimer object.

The receiver is the receiving object and the member is the slot. The time interval is given in the duration object nsec. The timerType affects the accuracy of the timer.

qtimer-ns-overflow

See also
start()

Definition at line 394 of file qtimer.cpp.

◆ singleShot() [8/8]

static void QTimer::singleShot ( std::chrono::nanoseconds value,
const QObject * receiver,
const char * member )
inlinestatic

Definition at line 138 of file qtimer.h.

◆ start [1/3]

void QTimer::start ( )
slot

Definition at line 209 of file qtimer.cpp.

◆ start [2/3]

void QTimer::start ( int msec)
slot

Starts or restarts the timer with a timeout interval of msec milliseconds.

stop-restart-timer

singleshot-activation This is equivalent to:

void start(int msec)
Starts or restarts the timer with a timeout interval of msec milliseconds.
Definition qtimer.cpp:239
void setInterval(int msec)
Definition qtimer.cpp:609
Note
Keeping the event loop busy with a zero-timer is bound to cause trouble and highly erratic behavior of the UI.

Definition at line 239 of file qtimer.cpp.

◆ start() [3/3]

void QTimer::start ( std::chrono::milliseconds msec)
Since
5.8 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Starts or restarts the timer with a timeout of duration msec milliseconds.

stop-restart-timer

singleshot-activation This is equivalent to:

Definition at line 244 of file qtimer.cpp.

◆ stop

void QTimer::stop ( )
slot

Stops the timer.

See also
start()

Definition at line 265 of file qtimer.cpp.

◆ timeout

void QTimer::timeout ( QPrivateSignal )
signal

This signal is emitted when the timer times out.

See also
interval, start(), stop()

◆ timerEvent()

void QTimer::timerEvent ( QTimerEvent * e)
overrideprotectedvirtual

\reimp

Reimplemented from QObject.

Definition at line 279 of file qtimer.cpp.

◆ timerId()

int QTimer::timerId ( ) const

Returns the ID of the timer if the timer is running; otherwise returns -1.

Definition at line 178 of file qtimer.cpp.

◆ timerType()

Qt::TimerType QTimer::timerType ( ) const

Definition at line 686 of file qtimer.cpp.

Friends And Related Symbol Documentation

◆ QChronoTimer

friend class QChronoTimer
friend

Definition at line 153 of file qtimer.h.

Property Documentation

◆ active

bool QTimer::active
read
Since
4.3

This boolean property is true if the timer is running; otherwise false.

Definition at line 26 of file qtimer.h.

◆ interval

int QTimer::interval
readwrite

the timeout interval in milliseconds

The default value for this property is 0. A QTimer with a timeout interval of 0 will time out as soon as all the events in the window system's event queue have been processed.

Setting the interval of a running timer will change the interval, stop() and then start() the timer, and acquire a new id(). If the timer is not running, only the interval is changed.

See also
singleShot

Definition at line 23 of file qtimer.h.

◆ remainingTime

int QTimer::remainingTime
read

the remaining time in milliseconds

Since
5.0

Returns the timer's remaining value in milliseconds left until the timeout. If the timer is inactive, the returned value will be -1. If the timer is overdue, the returned value will be 0.

See also
interval

Definition at line 24 of file qtimer.h.

◆ singleShot

bool QTimer::singleShot
readwrite

whether the timer is a single-shot timer

A single-shot timer fires only once, non-single-shot timers fire every \l interval milliseconds.

The default value for this property is false.

See also
interval, singleShot()

Definition at line 22 of file qtimer.h.

◆ timerType

Qt::TimerType QTimer::timerType
readwrite

controls the accuracy of the timer

The default value for this property is Qt::CoarseTimer.

See also
Qt::TimerType

Definition at line 25 of file qtimer.h.


The documentation for this class was generated from the following files: