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

source code of kidletime/src/kidletime.h