1/*
2 SPDX-FileCopyrightText: 2017 Martin Flöser <mgraesslin@kde.org>
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
13struct zwp_idle_inhibit_manager_v1;
14struct zwp_idle_inhibitor_v1;
15
16namespace KWayland
17{
18namespace Client
19{
20class EventQueue;
21class Surface;
22class 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 **/
48class KWAYLANDCLIENT_EXPORT IdleInhibitManager : public QObject
49{
50 Q_OBJECT
51public:
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 ~IdleInhibitManager() override;
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
116Q_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
125private:
126 class Private;
127 QScopedPointer<Private> d;
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 **/
148class KWAYLANDCLIENT_EXPORT IdleInhibitor : public QObject
149{
150 Q_OBJECT
151public:
152 ~IdleInhibitor() override;
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
191private:
192 friend class IdleInhibitManager;
193 explicit IdleInhibitor(QObject *parent = nullptr);
194 class Private;
195 QScopedPointer<Private> d;
196};
197
198}
199}
200
201#endif
202

source code of kwayland/src/client/idleinhibit.h