1 | /* This file is part of the KDE libraries |
2 | * SPDX-FileCopyrightText: 2009 Dario Freddi <drf at kde.org> |
3 | * SPDX-FileCopyrightText: 2021 Harald Sitter <sitter@kde.org> |
4 | * |
5 | * SPDX-License-Identifier: LGPL-2.1-or-later |
6 | */ |
7 | |
8 | #ifndef KIDLETIME_H |
9 | #define KIDLETIME_H |
10 | |
11 | #include <QHash> |
12 | #include <QObject> |
13 | #include <kidletime_export.h> |
14 | #include <memory> |
15 | |
16 | #if __has_include(<chrono>) |
17 | #include <chrono> |
18 | #endif |
19 | |
20 | class KIdleTimePrivate; |
21 | |
22 | /*! |
23 | * \class KIdleTime |
24 | * \inmodule KIdleTime |
25 | * |
26 | * \brief KIdleTime is a singleton reporting information on idle time. |
27 | * |
28 | * It is useful not |
29 | * only for finding out about the current idle time of the PC, but also for getting |
30 | * notified upon idle time events, such as custom timeouts, or user activity. |
31 | * |
32 | * \note All the intervals and times in this library are in milliseconds, unless |
33 | * specified otherwise. |
34 | * |
35 | * \since 4.4 |
36 | */ |
37 | class KIDLETIME_EXPORT KIdleTime : public QObject |
38 | { |
39 | Q_OBJECT |
40 | Q_DECLARE_PRIVATE(KIdleTime) |
41 | Q_DISABLE_COPY(KIdleTime) |
42 | |
43 | public: |
44 | /*! |
45 | * Returns the singleton instance. Use this method to access KIdleTime. |
46 | */ |
47 | static KIdleTime *instance(); |
48 | |
49 | ~KIdleTime() override; |
50 | |
51 | /*! |
52 | * Retrieves the idle time of the system, in milliseconds |
53 | */ |
54 | int idleTime() const; |
55 | |
56 | /*! |
57 | * Returns the list of timeout identifiers associated with their duration, in milliseconds, |
58 | * the library is currently listening to. |
59 | * |
60 | * \sa addIdleTimeout() |
61 | * \sa removeIdleTimeout() |
62 | * \sa timeoutReached() |
63 | */ |
64 | QHash<int, int> idleTimeouts() const; |
65 | |
66 | /*! |
67 | * Attempts to simulate user activity. This implies that after calling this |
68 | * method, the idle time of the system will become 0 and eventually resumingFromIdle() |
69 | * will be triggered. |
70 | * |
71 | * \sa resumingFromIdle() |
72 | */ |
73 | void simulateUserActivity(); |
74 | |
75 | public Q_SLOTS: |
76 | /*! |
77 | * Adds a new timeout to catch. When calling this method, after the system will be idle for |
78 | * \a msec milliseconds, the signal timeoutReached() will be triggered. Please note that until you will |
79 | * call removeIdleTimeout() or removeAllIdleTimeouts(), the signal will be triggered every |
80 | * time the system will be idle for \a msec milliseconds. This function also returns an unique |
81 | * token for the timeout just added to allow easier identification. |
82 | * |
83 | * \a msec the time, in milliseconds, after which the signal will be triggered. |
84 | * |
85 | * Returns an unique identifier for the timeout being added, that will be streamed by timeoutReached(). |
86 | * |
87 | * \sa removeIdleTimeout() |
88 | * \sa removeAllIdleTimeouts() |
89 | * \sa timeoutReached() |
90 | */ |
91 | int addIdleTimeout(int msec); |
92 | |
93 | #if __has_include(<chrono>) |
94 | /*! |
95 | * Convenience overload supporting C++ chrono types. May also be used with chrono literals. |
96 | * \since 5.83 |
97 | */ |
98 | int addIdleTimeout(std::chrono::milliseconds msec) |
99 | { |
100 | return addIdleTimeout(msec: int(msec.count())); |
101 | } |
102 | #endif |
103 | |
104 | /*! |
105 | * Stops catching the idle timeout identified by the token \a identifier, |
106 | * if it was registered earlier with addIdleTimeout. |
107 | * Otherwise does nothing. |
108 | * |
109 | * \a identifier the token returned from addIdleTimeout of the timeout you want to stop listening to |
110 | */ |
111 | void removeIdleTimeout(int identifier); |
112 | |
113 | /*! |
114 | * Stops catching every set timeout (if any). This means that after calling this method, the signal |
115 | * timeoutReached() won't be called again until you will add another timeout. |
116 | * |
117 | * \sa timeoutReached() |
118 | * \sa addIdleTimeout() |
119 | */ |
120 | void removeAllIdleTimeouts(); |
121 | |
122 | /*! |
123 | * Catches the next resume from idle event. This means that whenever user activity will be registered, or |
124 | * simulateUserActivity() is called, the signal resumingFromIdle() will be triggered. |
125 | * |
126 | * Please note that this method will trigger the signal just for the very first resume event after the call: |
127 | * this means you explicitly have to request to track every single resume event you are interested in. |
128 | * |
129 | * \note This behavior is due to the fact that a resume event happens whenever the user sends an input to the |
130 | * system. This would lead to a massive amount of signals being delivered when the PC is being used. |
131 | * Moreover, you are usually interested in catching just significant resume events, such as the ones after |
132 | * a significant period of inactivity. For tracking user input, you can use the more efficient methods provided |
133 | * by Qt. The purpose of this library is just monitoring the activity of the user. |
134 | * |
135 | * \sa resumingFromIdle() |
136 | * \sa simulateUserActivity() |
137 | * |
138 | */ |
139 | void catchNextResumeEvent(); |
140 | |
141 | /*! |
142 | * Stops listening for resume event. This function serves for canceling catchNextResumeEvent(), as it |
143 | * will have effect just when catchNextResumeEvent() has been called and resumingFromIdle() not |
144 | * yet triggered. |
145 | * |
146 | * \sa resumingFromIdle() |
147 | * \sa catchNextResumeEvent() |
148 | * |
149 | */ |
150 | void stopCatchingResumeEvent(); |
151 | |
152 | Q_SIGNALS: |
153 | /*! |
154 | * Triggered, if KIdleTime is catching resume events, when the system resumes from an idle state. This means |
155 | * that either simulateUserActivity() was called or the user sent an input to the system. |
156 | * |
157 | * \sa catchNextResumeEvent() |
158 | */ |
159 | void resumingFromIdle(); |
160 | |
161 | /*! |
162 | * Triggered when the system has been idle for x milliseconds, identified by the previously set |
163 | * timeout. |
164 | * |
165 | * This signal is triggered whenever each timeout previously registered with addIdleTimeout(int) |
166 | * is reached. It is guaranteed that \a msec will exactly correspond to the identified timeout. |
167 | * |
168 | * \a identifier the identifier of the timeout the system has reached. |
169 | * |
170 | * \a msec the time, in milliseconds, the system has been idle for. |
171 | * |
172 | * \sa addIdleTimeout() |
173 | * \sa removeIdleTimeout() |
174 | */ |
175 | void timeoutReached(int identifier, int msec); // clazy:exclude=overloaded-signal |
176 | |
177 | private: |
178 | KIDLETIME_NO_EXPORT KIdleTime(); |
179 | |
180 | std::unique_ptr<KIdleTimePrivate> const d_ptr; |
181 | }; |
182 | |
183 | #endif /* KIDLETIME_H */ |
184 | |