1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 2009 Dario Freddi <drf at kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License version 2 as published by the Free Software Foundation. |
7 | |
8 | This library is distributed in the hope that it will be useful, |
9 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
10 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
11 | Library General Public License for more details. |
12 | |
13 | You should have received a copy of the GNU Library General Public License |
14 | along with this library; see the file COPYING.LIB. If not, write to |
15 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
16 | Boston, MA 02110-1301, USA. |
17 | */ |
18 | |
19 | #ifndef KIDLETIME_H |
20 | #define KIDLETIME_H |
21 | |
22 | #include <QtCore/QObject> |
23 | #include <QtCore/QHash> |
24 | #include <kidletime_export.h> |
25 | class KIdleTimePrivate; |
26 | |
27 | /** |
28 | * KIdleTime is a singleton reporting information on idle time. 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 | * @author Dario Freddi |
36 | * |
37 | * @since 4.4 |
38 | */ |
39 | class KIDLETIME_EXPORT KIdleTime : public QObject |
40 | { |
41 | Q_OBJECT |
42 | Q_DECLARE_PRIVATE(KIdleTime) |
43 | Q_DISABLE_COPY(KIdleTime) |
44 | |
45 | public: |
46 | /** |
47 | * Returns the singleton instance. Use this method to access KIdleTime |
48 | * |
49 | * @returns the instance of KIdleTime |
50 | */ |
51 | static KIdleTime *instance(); |
52 | |
53 | /** |
54 | * The destructor |
55 | */ |
56 | virtual ~KIdleTime(); |
57 | |
58 | /** |
59 | * Retrieves the idle time of the system, in milliseconds |
60 | * |
61 | * @returns the idle time of the system |
62 | */ |
63 | int idleTime() const; |
64 | |
65 | /** |
66 | * Returns the list of timeout identifiers associated with their duration, in milliseconds, |
67 | * the library is currently listening to. |
68 | * |
69 | * @see addIdleTimeout |
70 | * @see removeIdleTimeout |
71 | * @see timeoutReached |
72 | */ |
73 | QHash<int, int> idleTimeouts() const; |
74 | |
75 | /** |
76 | * Attempts to simulate user activity. This implies that after calling this |
77 | * method, the idle time of the system will become 0 and eventually \link resumingFromIdle |
78 | * will be triggered |
79 | * |
80 | * @see resumingFromIdle |
81 | */ |
82 | void simulateUserActivity(); |
83 | |
84 | public Q_SLOTS: |
85 | /** |
86 | * Adds a new timeout to catch. When calling this method, after the system will be idle for |
87 | * \c msec milliseconds, the signal \c timeoutReached will be triggered. Please note that until you will |
88 | * call \c removeIdleTimeout or \c removeAllIdleTimeouts, the signal will be triggered every |
89 | * time the system will be idle for \c msec milliseconds. This function also returns an unique |
90 | * token for the timeout just added to allow easier identification. |
91 | * |
92 | * @param msec the time, in milliseconds, after which the signal will be triggered |
93 | * |
94 | * @returns an unique identifier for the timeout being added, that will be streamed by timeoutReached |
95 | * |
96 | * @see removeIdleTimeout |
97 | * @see removeAllIdleTimeouts |
98 | * @see timeoutReached |
99 | * |
100 | */ |
101 | int addIdleTimeout(int msec); |
102 | |
103 | /** |
104 | * Stops catching the idle timeout identified by the token \c identifier, |
105 | * if it was registered earlier with addIdleTimeout. |
106 | * Otherwise does nothing. |
107 | * |
108 | * @param identifier the token returned from addIdleTimeout of the timeout you want to stop listening to |
109 | */ |
110 | void removeIdleTimeout(int identifier); |
111 | |
112 | /** |
113 | * Stops catching every set timeout (if any). This means that after calling this method, the signal |
114 | * \link timeoutReached won't be called again until you will add another timeout |
115 | * |
116 | * @see timeoutReached |
117 | * @see addIdleTimeout |
118 | */ |
119 | void removeAllIdleTimeouts(); |
120 | |
121 | /** |
122 | * Catches the next resume from idle event. This means that whenever user activity will be registered, or |
123 | * \link simulateUserActivity is called, the signal \link resumingFromIdle will be triggered. |
124 | * <p> |
125 | * Please note that this method will trigger the signal just for the very first resume event after the call: |
126 | * this means you explicitly have to request to track every single resume event you are interested in. |
127 | * |
128 | * @note This behavior is due to the fact that a resume event happens whenever the user sends an input to the |
129 | * system. This would lead to a massive amount of signals being delivered when the PC is being used. |
130 | * Moreover, you are usually interested in catching just significant resume events, such as the ones after |
131 | * a significant period of inactivity. For tracking user input, you can use the more efficient methods provided |
132 | * by Qt. The purpose of this library is just monitoring the activity of the user. |
133 | * |
134 | * @see resumingFromIdle |
135 | * @see simulateUserActivity |
136 | * |
137 | */ |
138 | void catchNextResumeEvent(); |
139 | |
140 | /** |
141 | * Stops listening for resume event. This function serves for canceling \c catchNextResumeEvent, as it |
142 | * will have effect just when \c catchNextResumeEvent has been called and \c resumingFromIdle not |
143 | * yet triggered |
144 | * |
145 | * @see resumingFromIdle |
146 | * @see catchNextResumeEvent |
147 | * |
148 | */ |
149 | void stopCatchingResumeEvent(); |
150 | |
151 | Q_SIGNALS: |
152 | /** |
153 | * Triggered, if KIdleTime is catching resume events, when the system resumes from an idle state. This means |
154 | * that either \link simulateUserActivity was called or the user sent an input to the system. |
155 | * |
156 | * @see catchNextResumeEvent |
157 | */ |
158 | void resumingFromIdle(); |
159 | |
160 | /** |
161 | * Triggered when the system has been idle for x milliseconds, identified by the previously set |
162 | * timeout. |
163 | * <p> |
164 | * This signal is triggered whenever each timeout previously registered with \link addIdleTimeout |
165 | * is reached. |
166 | * |
167 | * @param identifier the identifier of the timeout the system has reached |
168 | * |
169 | * @see addIdleTimeout |
170 | * @see removeIdleTimeout |
171 | */ |
172 | void timeoutReached(int identifier); |
173 | |
174 | /** |
175 | * Overload. Streams the duration as well. It is guaranteed that \c msec will exactly |
176 | * correspond to the timeout registered with \link addIdleTimeout |
177 | * |
178 | * @param msec the time, in milliseconds, the system has been idle for |
179 | * |
180 | * @see addIdleTimeout |
181 | * @see removeIdleTimeout |
182 | */ |
183 | void timeoutReached(int identifier, int msec); |
184 | |
185 | private: |
186 | KIdleTime(); |
187 | |
188 | KIdleTimePrivate * const d_ptr; |
189 | |
190 | Q_PRIVATE_SLOT(d_func(), void _k_resumingFromIdle()) |
191 | Q_PRIVATE_SLOT(d_func(), void _k_timeoutReached(int)) |
192 | |
193 | }; |
194 | |
195 | #endif /* KIDLETIME_H */ |
196 | |