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
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 */
37class KIDLETIME_EXPORT KIdleTime : public QObject
38{
39 Q_OBJECT
40 Q_DECLARE_PRIVATE(KIdleTime)
41 Q_DISABLE_COPY(KIdleTime)
42
43public:
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
75public 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
152Q_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
177private:
178 KIDLETIME_NO_EXPORT KIdleTime();
179
180 std::unique_ptr<KIdleTimePrivate> const d_ptr;
181};
182
183#endif /* KIDLETIME_H */
184

source code of kidletime/src/kidletime.h