KWayland

idle.h
1 /*
2  SPDX-FileCopyrightText: 2015 Martin Gräßlin <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 #ifndef KWAYLAND_IDLE_H
7 #define KWAYLAND_IDLE_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Client/kwaylandclient_export.h>
12 
13 struct org_kde_kwin_idle;
14 struct org_kde_kwin_idle_timeout;
15 
16 namespace KWayland
17 {
18 namespace Client
19 {
20 class EventQueue;
21 class IdleTimeout;
22 class Seat;
23 
24 /**
25  * @short Wrapper for the org_kde_kwin_idle interface.
26  *
27  * With the help of Idle it is possible to get notified when a Seat is not being
28  * used. E.g. a chat application which wants to set the user automatically to away
29  * if the user did not interact with the Seat for 5 minutes can create an IdleTimeout
30  * to get notified when the Seat has been idle for the given amount of time.
31  *
32  * This class provides a convenient wrapper for the org_kde_kwin_idle interface.
33  *
34  * To use this class one needs to interact with the Registry. There are two
35  * possible ways to create the Idle interface:
36  * @code
37  * Idle *m = registry->createIdle(name, version);
38  * @endcode
39  *
40  * This creates the Idle and sets it up directly. As an alternative this
41  * can also be done in a more low level way:
42  * @code
43  * Idle *m = new Idle;
44  * m->setup(registry->bindIdle(name, version));
45  * @endcode
46  *
47  * The Idle can be used as a drop-in replacement for any org_kde_kwin_idle
48  * pointer as it provides matching cast operators.
49  *
50  * @see Registry
51  **/
52 class KWAYLANDCLIENT_EXPORT Idle : public QObject
53 {
54  Q_OBJECT
55 public:
56  /**
57  * Creates a new Idle.
58  * Note: after constructing the Idle it is not yet valid and one needs
59  * to call setup. In order to get a ready to use Idle prefer using
60  * Registry::createIdle.
61  **/
62  explicit Idle(QObject *parent = nullptr);
63  virtual ~Idle();
64 
65  /**
66  * @returns @c true if managing a org_kde_kwin_idle.
67  **/
68  bool isValid() const;
69  /**
70  * Setup this Idle to manage the @p manager.
71  * When using Registry::createIdle there is no need to call this
72  * method.
73  **/
74  void setup(org_kde_kwin_idle *manager);
75  /**
76  * Releases the org_kde_kwin_idle interface.
77  * After the interface has been released the Idle instance is no
78  * longer valid and can be setup with another org_kde_kwin_idle interface.
79  **/
80  void release();
81  /**
82  * Destroys the data held by this Idle.
83  * This method is supposed to be used when the connection to the Wayland
84  * server goes away. If the connection is not valid anymore, it's not
85  * possible to call release anymore as that calls into the Wayland
86  * connection and the call would fail. This method cleans up the data, so
87  * that the instance can be deleted or set up to a new org_kde_kwin_idle interface
88  * once there is a new connection available.
89  *
90  * This method is automatically invoked when the Registry which created this
91  * Idle gets destroyed.
92  *
93  * @see release
94  **/
95  void destroy();
96 
97  /**
98  * Sets the @p queue to use for creating a IdleTimeout.
99  **/
100  void setEventQueue(EventQueue *queue);
101  /**
102  * @returns The event queue to use for creating a IdleTimeout.
103  **/
104  EventQueue *eventQueue();
105 
106  /**
107  * Creates a new IdleTimeout for the @p seat. If the @p seat has been idle,
108  * that is none of the connected input devices got used for @p msec, the
109  * IdleTimeout will emit the {@link IdleTimeout::idle} signal.
110  *
111  * It is not guaranteed that the signal will be emitted exactly at the given
112  * timeout. A Wayland server might for example have a minimum timeout which is
113  * larger than @p msec.
114  *
115  * @param msec The duration in milliseconds after which an idle timeout should fire
116  * @param seat The Seat on which the user activity should be monitored.
117  **/
118  IdleTimeout *getTimeout(quint32 msecs, Seat *seat, QObject *parent = nullptr);
119 
120  operator org_kde_kwin_idle *();
121  operator org_kde_kwin_idle *() const;
122 
123 Q_SIGNALS:
124  /**
125  * The corresponding global for this interface on the Registry got removed.
126  *
127  * This signal gets only emitted if the Compositor got created by
128  * Registry::createIdle
129  *
130  * @since 5.5
131  **/
132  void removed();
133 
134 private:
135  class Private;
137 };
138 
139 /**
140  * @short Wrapper for the org_kde_kwin_idle_timeout interface.
141  *
142  * This class is a convenient wrapper for the org_kde_kwin_idle_timeout interface.
143  * To create a IdleTimeout call IdleTimeoutManager::getIdleTimeout.
144  *
145  * @see IdleTimeoutManager
146  **/
147 class KWAYLANDCLIENT_EXPORT IdleTimeout : public QObject
148 {
149  Q_OBJECT
150 public:
151  /**
152  * To create an IdleTimeout prefer using {@link Idle::getTimeout} which sets up the
153  * IdleTimeout to be fully functional.
154  **/
155  explicit IdleTimeout(QObject *parent = nullptr);
156  virtual ~IdleTimeout();
157 
158  /**
159  * Setup this IdleTimeout to manage the @p timeout.
160  * When using IdleTimeoutManager::createIdleTimeout there is no need to call this
161  * method.
162  **/
163  void setup(org_kde_kwin_idle_timeout *timeout);
164  /**
165  * Releases the org_kde_kwin_idle_timeout interface.
166  * After the interface has been released the IdleTimeout instance is no
167  * longer valid and can be setup with another org_kde_kwin_idle_timeout interface.
168  **/
169  void release();
170  /**
171  * Destroys the data held by this IdleTimeout.
172  * This method is supposed to be used when the connection to the Wayland
173  * server goes away. If the connection is not valid anymore, it's not
174  * possible to call release anymore as that calls into the Wayland
175  * connection and the call would fail. This method cleans up the data, so
176  * that the instance can be deleted or set up to a new org_kde_kwin_idle_timeout interface
177  * once there is a new connection available.
178  *
179  * It is suggested to connect this method to ConnectionThread::connectionDied:
180  * @code
181  * connect(connection, &ConnectionThread::connectionDied, source, &IdleTimeout::destroy);
182  * @endcode
183  *
184  * @see release
185  **/
186  void destroy();
187  /**
188  * @returns @c true if managing a org_kde_kwin_idle_timeout.
189  **/
190  bool isValid() const;
191 
192  operator org_kde_kwin_idle_timeout *();
193  operator org_kde_kwin_idle_timeout *() const;
194 
195  /**
196  * Simulates user activity. If the IdleTimeout is in idle state this will trigger the
197  * {@link resumeFromIdle} signal. The current idle duration is reset, so the {@link idle}
198  * will only be emitted after a complete idle duration as requested for this IdleTimeout.
199  */
200  void simulateUserActivity();
201 
202 Q_SIGNALS:
203  /**
204  * Emitted when this IdleTimeout triggered. This means the system has been idle for
205  * the duration specified when creating the IdleTimeout.
206  * @see Idle::getTimeout.
207  * @see resumeFromIdle
208  **/
209  void idle();
210  /**
211  * Emitted when the system shows activity again after the idle state was reached.
212  * @see idle
213  **/
214  void resumeFromIdle();
215 
216 private:
217  class Private;
219 };
220 
221 }
222 }
223 
224 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the wl_seat interface.
Definition: seat.h:51
Wrapper for the org_kde_kwin_idle_timeout interface.
Definition: idle.h:147
Wrapper for the org_kde_kwin_idle interface.
Definition: idle.h:52
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Oct 16 2021 22:52:01 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.