1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2020 The Qt Company Ltd. |
4 | ** Contact: https://www.qt.io/licensing/ |
5 | ** |
6 | ** This file is part of the QtCore module of the Qt Toolkit. |
7 | ** |
8 | ** $QT_BEGIN_LICENSE:LGPL$ |
9 | ** Commercial License Usage |
10 | ** Licensees holding valid commercial Qt licenses may use this file in |
11 | ** accordance with the commercial license agreement provided with the |
12 | ** Software or, alternatively, in accordance with the terms contained in |
13 | ** a written agreement between you and The Qt Company. For licensing terms |
14 | ** and conditions see https://www.qt.io/terms-conditions. For further |
15 | ** information use the contact form at https://www.qt.io/contact-us. |
16 | ** |
17 | ** GNU Lesser General Public License Usage |
18 | ** Alternatively, this file may be used under the terms of the GNU Lesser |
19 | ** General Public License version 3 as published by the Free Software |
20 | ** Foundation and appearing in the file LICENSE.LGPL3 included in the |
21 | ** packaging of this file. Please review the following information to |
22 | ** ensure the GNU Lesser General Public License version 3 requirements |
23 | ** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. |
24 | ** |
25 | ** GNU General Public License Usage |
26 | ** Alternatively, this file may be used under the terms of the GNU |
27 | ** General Public License version 2.0 or (at your option) the GNU General |
28 | ** Public license version 3 or any later version approved by the KDE Free |
29 | ** Qt Foundation. The licenses are as published by the Free Software |
30 | ** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 |
31 | ** included in the packaging of this file. Please review the following |
32 | ** information to ensure the GNU General Public License requirements will |
33 | ** be met: https://www.gnu.org/licenses/gpl-2.0.html and |
34 | ** https://www.gnu.org/licenses/gpl-3.0.html. |
35 | ** |
36 | ** $QT_END_LICENSE$ |
37 | ** |
38 | ****************************************************************************/ |
39 | |
40 | #include "qbasictimer.h" |
41 | #include "qabstracteventdispatcher.h" |
42 | #include "qabstracteventdispatcher_p.h" |
43 | |
44 | QT_BEGIN_NAMESPACE |
45 | |
46 | /*! |
47 | \class QBasicTimer |
48 | \inmodule QtCore |
49 | \brief The QBasicTimer class provides timer events for objects. |
50 | |
51 | \ingroup events |
52 | |
53 | This is a fast, lightweight, and low-level class used by Qt |
54 | internally. We recommend using the higher-level QTimer class |
55 | rather than this class if you want to use timers in your |
56 | applications. Note that this timer is a repeating timer that |
57 | will send subsequent timer events unless the stop() function is called. |
58 | |
59 | To use this class, create a QBasicTimer, and call its start() |
60 | function with a timeout interval and with a pointer to a QObject |
61 | subclass. When the timer times out it will send a timer event to |
62 | the QObject subclass. The timer can be stopped at any time using |
63 | stop(). isActive() returns \c true for a timer that is running; |
64 | i.e. it has been started, has not reached the timeout time, and |
65 | has not been stopped. The timer's ID can be retrieved using |
66 | timerId(). |
67 | |
68 | Objects of this class cannot be copied, but can be moved, so you |
69 | can maintain a list of basic timers by holding them in container |
70 | that supports move-only types, e.g. std::vector. |
71 | |
72 | The \l{widgets/wiggly}{Wiggly} example uses QBasicTimer to repaint |
73 | a widget at regular intervals. |
74 | |
75 | \sa QTimer, QTimerEvent, QObject::timerEvent(), Timers, {Wiggly Example} |
76 | */ |
77 | |
78 | |
79 | /*! |
80 | \fn QBasicTimer::QBasicTimer() |
81 | |
82 | Contructs a basic timer. |
83 | |
84 | \sa start() |
85 | */ |
86 | |
87 | /*! |
88 | \fn QBasicTimer::QBasicTimer(QBasicTimer &&other) |
89 | \since 5.14 |
90 | |
91 | Move-constructs a basic timer from \a other, which is left |
92 | \l{isActive()}{inactive}. |
93 | |
94 | \sa isActive(), swap() |
95 | */ |
96 | |
97 | /*! |
98 | \fn QBasicTimer &QBasicTimer::operator=(QBasicTimer &&other) |
99 | \since 5.14 |
100 | |
101 | Move-assigns \a other to this basic timer. The timer |
102 | previously represented by this basic timer is stopped. |
103 | \a other is left as \l{isActive()}{inactive}. |
104 | |
105 | \sa stop(), isActive(), swap() |
106 | */ |
107 | |
108 | /*! |
109 | \fn QBasicTimer::~QBasicTimer() |
110 | |
111 | Destroys the basic timer. |
112 | */ |
113 | |
114 | /*! |
115 | \fn bool QBasicTimer::isActive() const |
116 | |
117 | Returns \c true if the timer is running and has not been stopped; otherwise |
118 | returns \c false. |
119 | |
120 | \sa start(), stop() |
121 | */ |
122 | |
123 | /*! |
124 | \fn QBasicTimer::swap(QBasicTimer &other) |
125 | \fn swap(QBasicTimer &lhs, QBasicTimer &rhs) |
126 | \since 5.14 |
127 | |
128 | Swaps string \a other with this string, or \a lhs with \a rhs. |
129 | This operation is very fast and never fails. |
130 | */ |
131 | |
132 | /*! |
133 | \fn int QBasicTimer::timerId() const |
134 | |
135 | Returns the timer's ID. |
136 | |
137 | \sa QTimerEvent::timerId() |
138 | */ |
139 | |
140 | /*! |
141 | \fn void QBasicTimer::start(int msec, QObject *object) |
142 | |
143 | Starts (or restarts) the timer with a \a msec milliseconds timeout. The |
144 | timer will be a Qt::CoarseTimer. See Qt::TimerType for information on the |
145 | different timer types. |
146 | |
147 | The given \a object will receive timer events. |
148 | |
149 | \sa stop(), isActive(), QObject::timerEvent(), Qt::CoarseTimer |
150 | */ |
151 | void QBasicTimer::start(int msec, QObject *obj) |
152 | { |
153 | start(msec, Qt::CoarseTimer, obj); |
154 | } |
155 | |
156 | /*! |
157 | \overload |
158 | |
159 | Starts (or restarts) the timer with a \a msec milliseconds timeout and the |
160 | given \a timerType. See Qt::TimerType for information on the different |
161 | timer types. |
162 | |
163 | \a obj will receive timer events. |
164 | |
165 | \sa stop(), isActive(), QObject::timerEvent(), Qt::TimerType |
166 | */ |
167 | void QBasicTimer::start(int msec, Qt::TimerType timerType, QObject *obj) |
168 | { |
169 | QAbstractEventDispatcher *eventDispatcher = QAbstractEventDispatcher::instance(); |
170 | if (Q_UNLIKELY(msec < 0)) { |
171 | qWarning("QBasicTimer::start: Timers cannot have negative timeouts" ); |
172 | return; |
173 | } |
174 | if (Q_UNLIKELY(!eventDispatcher)) { |
175 | qWarning("QBasicTimer::start: QBasicTimer can only be used with threads started with QThread" ); |
176 | return; |
177 | } |
178 | if (Q_UNLIKELY(obj && obj->thread() != eventDispatcher->thread())) { |
179 | qWarning("QBasicTimer::start: Timers cannot be started from another thread" ); |
180 | return; |
181 | } |
182 | stop(); |
183 | if (obj) |
184 | id = eventDispatcher->registerTimer(msec, timerType, obj); |
185 | } |
186 | |
187 | /*! |
188 | Stops the timer. |
189 | |
190 | \sa start(), isActive() |
191 | */ |
192 | void QBasicTimer::stop() |
193 | { |
194 | if (id) { |
195 | QAbstractEventDispatcher *eventDispatcher = QAbstractEventDispatcher::instance(); |
196 | if (eventDispatcher && !eventDispatcher->unregisterTimer(id)) { |
197 | qWarning("QBasicTimer::stop: Failed. Possibly trying to stop from a different thread" ); |
198 | return; |
199 | } |
200 | QAbstractEventDispatcherPrivate::releaseTimerId(id); |
201 | } |
202 | id = 0; |
203 | } |
204 | |
205 | QT_END_NAMESPACE |
206 | |