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:
Ahmad Samir 2024-09-02 22:24:10 +03:00 committed by Qt Cherry-pick Bot
parent 799f6bf43f
commit 567eae56e7
4 changed files with 35 additions and 24 deletions

View File

@ -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.
*/

View File

@ -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.

View File

@ -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.

View 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]