KWayland

idleinhibit.h
1 /*
2  SPDX-FileCopyrightText: 2017 Martin Flöser <[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_CLIENT_IDLEINHIBIT_H
7 #define KWAYLAND_CLIENT_IDLEINHIBIT_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Client/kwaylandclient_export.h>
12 
13 struct zwp_idle_inhibit_manager_v1;
14 struct zwp_idle_inhibitor_v1;
15 
16 namespace KWayland
17 {
18 namespace Client
19 {
20 class EventQueue;
21 class Surface;
22 class IdleInhibitor;
23 
24 /**
25  * @short Wrapper for the zwp_idle_inhibit_manager_v1 interface.
26  *
27  * This class provides a convenient wrapper for the zwp_idle_inhibit_manager_v1 interface.
28  *
29  * To use this class one needs to interact with the Registry. There are two
30  * possible ways to create the IdleInhibitManager interface:
31  * @code
32  * IdleInhibitManager *c = registry->createIdleInhibitManager(name, version);
33  * @endcode
34  *
35  * This creates the IdleInhibitManager and sets it up directly. As an alternative this
36  * can also be done in a more low level way:
37  * @code
38  * IdleInhibitManager *c = new IdleInhibitManager;
39  * c->setup(registry->bindIdleInhibitManager(name, version));
40  * @endcode
41  *
42  * The IdleInhibitManager can be used as a drop-in replacement for any zwp_idle_inhibit_manager_v1
43  * pointer as it provides matching cast operators.
44  *
45  * @see Registry
46  * @since 5.41
47  **/
48 class KWAYLANDCLIENT_EXPORT IdleInhibitManager : public QObject
49 {
50  Q_OBJECT
51 public:
52  /**
53  * Creates a new IdleInhibitManager.
54  * Note: after constructing the IdleInhibitManager it is not yet valid and one needs
55  * to call setup. In order to get a ready to use IdleInhibitManager prefer using
56  * Registry::createIdleInhibitManager.
57  **/
58  explicit IdleInhibitManager(QObject *parent = nullptr);
59  virtual ~IdleInhibitManager();
60 
61  /**
62  * Setup this IdleInhibitManager to manage the @p idleinhibitmanager.
63  * When using Registry::createIdleInhibitManager there is no need to call this
64  * method.
65  **/
66  void setup(zwp_idle_inhibit_manager_v1 *idleinhibitmanager);
67  /**
68  * @returns @c true if managing a zwp_idle_inhibit_manager_v1.
69  **/
70  bool isValid() const;
71  /**
72  * Releases the zwp_idle_inhibit_manager_v1 interface.
73  * After the interface has been released the IdleInhibitManager instance is no
74  * longer valid and can be setup with another zwp_idle_inhibit_manager_v1 interface.
75  **/
76  void release();
77  /**
78  * Destroys the data held by this IdleInhibitManager.
79  * This method is supposed to be used when the connection to the Wayland
80  * server goes away. If the connection is not valid anymore, it's not
81  * possible to call release anymore as that calls into the Wayland
82  * connection and the call would fail. This method cleans up the data, so
83  * that the instance can be deleted or set up to a new zwp_idle_inhibit_manager_v1 interface
84  * once there is a new connection available.
85  *
86  * It is suggested to connect this method to ConnectionThread::connectionDied:
87  * @code
88  * connect(connection, &ConnectionThread::connectionDied, idleinhibitmanager, &IdleInhibitManager::destroy);
89  * @endcode
90  *
91  * @see release
92  **/
93  void destroy();
94 
95  /**
96  * Sets the @p queue to use for creating objects with this IdleInhibitManager.
97  **/
98  void setEventQueue(EventQueue *queue);
99  /**
100  * @returns The event queue to use for creating objects with this IdleInhibitManager.
101  **/
102  EventQueue *eventQueue();
103 
104  /**
105  * Creates an IdleInhibitor for the given @p surface.
106  * While the IdleInhibitor exists the @p surface is marked to inhibit idle.
107  * @param surface The Surface which should have idle inhibited
108  * @param parent The parent object for the IdleInhibitor
109  * @returns The created IdleInhibitor
110  **/
111  IdleInhibitor *createInhibitor(Surface *surface, QObject *parent = nullptr);
112 
113  operator zwp_idle_inhibit_manager_v1 *();
114  operator zwp_idle_inhibit_manager_v1 *() const;
115 
116 Q_SIGNALS:
117  /**
118  * The corresponding global for this interface on the Registry got removed.
119  *
120  * This signal gets only emitted if the IdleInhibitManager got created by
121  * Registry::createIdleInhibitManager
122  **/
123  void removed();
124 
125 private:
126  class Private;
128 };
129 
130 /**
131  * An IdleInhibitor prevents the Output that the associated Surface is visible on from being
132  * set to a state where it is not visually usable due to lack of user interaction
133  * (e.g. blanked, dimmed, locked, set to power save, etc.) Any screensaver processes are
134  * also blocked from displaying.
135  *
136  * If the Surface is destroyed, unmapped, becomes occluded, loses visibility, or otherwise
137  * becomes not visually relevant for the user, the IdleInhibitor will not be honored by
138  * the compositor; if the Surface subsequently regains visibility the inhibitor takes effect
139  * once again.
140  * Likewise, the IdleInhibitor isn't honored if the system was already idled at the time the
141  * IdleInhibitor was established, although if the system later de-idles and re-idles the
142  * IdleInhibitor will take effect.
143  *
144  * @see IdleInhibitManager
145  * @see Surface
146  * @since 5.41
147  **/
148 class KWAYLANDCLIENT_EXPORT IdleInhibitor : public QObject
149 {
150  Q_OBJECT
151 public:
152  virtual ~IdleInhibitor();
153 
154  /**
155  * Setup this IdleInhibitor to manage the @p idleinhibitor.
156  * When using IdleInhibitManager::createIdleInhibitor there is no need to call this
157  * method.
158  **/
159  void setup(zwp_idle_inhibitor_v1 *idleinhibitor);
160  /**
161  * @returns @c true if managing a zwp_idle_inhibitor_v1.
162  **/
163  bool isValid() const;
164  /**
165  * Releases the zwp_idle_inhibitor_v1 interface.
166  * After the interface has been released the IdleInhibitor instance is no
167  * longer valid and can be setup with another zwp_idle_inhibitor_v1 interface.
168  **/
169  void release();
170  /**
171  * Destroys the data held by this IdleInhibitor.
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 zwp_idle_inhibitor_v1 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, idleinhibitor, &IdleInhibitor::destroy);
182  * @endcode
183  *
184  * @see release
185  **/
186  void destroy();
187 
188  operator zwp_idle_inhibitor_v1 *();
189  operator zwp_idle_inhibitor_v1 *() const;
190 
191 private:
192  friend class IdleInhibitManager;
193  explicit IdleInhibitor(QObject *parent = nullptr);
194  class Private;
196 };
197 
198 }
199 }
200 
201 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the wl_surface interface.
Definition: surface.h:43
An IdleInhibitor prevents the Output that the associated Surface is visible on from being set to a st...
Definition: idleinhibit.h:148
Wrapper for the zwp_idle_inhibit_manager_v1 interface.
Definition: idleinhibit.h:48
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.