docs: promote QBasicTimer usage by making it more visible
Deduplicate some API docs. Mention that it's a RAII class, to make it more appealing to users. Copied the "RAII" note and link from QSemaphoreReleaser's API docs. Change-Id: I53ced6eb7c2ab55ffc04e70c250b5f5639406911 Reviewed-by: Marc Mutz <marc.mutz@qt.io> (cherry picked from commit e1fdfe9da8ccdeed9af602897232a513884b0515) Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This commit is contained in:
parent
799f6bf43f
commit
567eae56e7
@ -15,6 +15,15 @@
|
||||
regular intervals until you explicitly call QObject::killTimer()
|
||||
with that timer ID.
|
||||
|
||||
Instead of handling timer IDs directly, you can use \l QBasicTimer.
|
||||
QBasicTimer is a value-class,
|
||||
\l{http://en.cppreference.com/w/cpp/language/raii}{RAII} wrapper around
|
||||
a timer ID. You start the timer with \l{QBasicTimer::start()}, and stop
|
||||
it with \l{QBasicTimer::stop()} (the latter is also called upon destruction).
|
||||
To use QBasicTimer, you must reimplement \l{QObject::timerEvent()}{timerEvent()}
|
||||
in your class (which must be a sub-class of QObject), and handle the
|
||||
timer event there.
|
||||
|
||||
For this mechanism to work, the application must run in an event
|
||||
loop. You cat start an event loop with QApplication::exec(). When a
|
||||
timer fires, the application sends a QTimerEvent, and the flow of
|
||||
@ -87,10 +96,4 @@
|
||||
|
||||
Every second, QChronoTimer 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.
|
||||
*/
|
||||
|
@ -97,15 +97,7 @@ QT_BEGIN_NAMESPACE
|
||||
std::numeric_limits<int>::max()). If you only need millisecond resolution
|
||||
and ±24 days range, you can continue to use the classical QTimer class
|
||||
|
||||
An alternative to using QChronoTimer is to call QObject::startTimer()
|
||||
for your object and reimplement the QObject::timerEvent() event handler
|
||||
in your class (which must be a sub-class of QObject). The disadvantage
|
||||
is that timerEvent() does not support such high-level features as
|
||||
single-shot timers or signals.
|
||||
|
||||
Another alternative is QBasicTimer. It is typically less cumbersome
|
||||
than using QObject::startTimer() directly. See \l{Timers} for an
|
||||
overview of all three approaches.
|
||||
\include timers-common.qdocinc q-chrono-timer-alternatives
|
||||
|
||||
Some operating systems limit the number of timers that may be used;
|
||||
Qt does its best to work around these limitations.
|
||||
|
@ -104,15 +104,7 @@ QT_BEGIN_NAMESPACE
|
||||
\c std::numeric_limits<int>::max()). If you only need millisecond
|
||||
resolution and ±24 days range, you can continue to use QTimer.
|
||||
|
||||
Another alternative is to call QObject::startTimer()
|
||||
for your object and reimplement the QObject::timerEvent() event
|
||||
handler in your class (which must inherit QObject). The
|
||||
disadvantage is that timerEvent() does not support such
|
||||
high-level features as single-shot timers or signals.
|
||||
|
||||
Another alternative is QBasicTimer. It is typically less
|
||||
cumbersome than using QObject::startTimer()
|
||||
directly. See \l{Timers} for an overview of all three approaches.
|
||||
\include timers-common.qdocinc q-chrono-timer-alternatives
|
||||
|
||||
Some operating systems limit the number of timers that may be
|
||||
used; Qt tries to work around these limitations.
|
||||
|
24
src/corelib/kernel/timers-common.qdocinc
Normal file
24
src/corelib/kernel/timers-common.qdocinc
Normal file
@ -0,0 +1,24 @@
|
||||
// Copyright (C) 2024 Ahmad Samir <a.samirh78@gmail.com>
|
||||
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
|
||||
|
||||
//! [q-chrono-timer-alternatives]
|
||||
Another alternative is reimplementing the QObject::timerEvent() method
|
||||
in your class (which must be a sub-class of QObject), and using one of
|
||||
the following approaches:
|
||||
|
||||
\list
|
||||
\li Using QBasicTimer, a lightweight value-class wrapping a timer
|
||||
ID. You can start the timer with QBasicTimer::start() and stop it with
|
||||
QBasicTimer::stop(). You can handle the event in your reimplemneted
|
||||
timerEvent().
|
||||
|
||||
\li A more low-level method is manipulating the timer IDs directly.
|
||||
To start the timer call QObject::startTimer(), storing the returned
|
||||
ID. To stop the timer call QObject::killTimer(). You can handle the event
|
||||
in your reimplemented timerEvent(). This approach is typically more
|
||||
cumbersome than using QBasicTimer.
|
||||
\endlist
|
||||
|
||||
A disadvantage of using timerEvent() is that some high-level features,
|
||||
such as single-shot timers and signals, aren't supported.
|
||||
//! [q-chrono-timer-alternatives]
|
Loading…
x
Reference in New Issue
Block a user