KWayland

dpms.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_CLIENT_DPMS_H
7 #define KWAYLAND_CLIENT_DPMS_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Client/kwaylandclient_export.h>
12 
13 struct org_kde_kwin_dpms;
14 struct org_kde_kwin_dpms_manager;
15 
16 namespace KWayland
17 {
18 namespace Client
19 {
20 class EventQueue;
21 class Dpms;
22 class Output;
23 
24 /**
25  * @short This class is a factory for Dpms instances.
26  *
27  * It is a convenience wrapper for the org_kde_kwin_dpms_manager interface.
28  *
29  * To use this class one needs to interact with the Registry. There are two
30  * possible ways to create the DpmsManager interface:
31  * @code
32  * DpmsManager *m = registry->createDpmsManager(name, version);
33  * @endcode
34  *
35  * This creates the DpmsManager and sets it up directly. As an alternative this
36  * can also be done in a more low level way:
37  * @code
38  * DpmsManager *m = new DpmsManager;
39  * m->setup(registry->bindDpmsManager(name, version));
40  * @endcode
41  *
42  * The DpmsManager can be used as a drop-in replacement for any org_kde_kwin_dpms_manager
43  * pointer as it provides matching cast operators.
44  *
45  * @see Registry, Dpms
46  * @since 5.5
47  **/
48 class KWAYLANDCLIENT_EXPORT DpmsManager : public QObject
49 {
50  Q_OBJECT
51 public:
52  /**
53  * Creates a new DpmsManager.
54  * Note: after constructing the DpmsManager it is not yet valid and one needs
55  * to call setup. In order to get a ready to use DpmsManager prefer using
56  * Registry::createDpmsManager.
57  **/
58  explicit DpmsManager(QObject *parent = nullptr);
59  virtual ~DpmsManager();
60 
61  /**
62  * @returns @c true if managing a org_kde_kwin_dpms_manager.
63  **/
64  bool isValid() const;
65  /**
66  * Setup this DpmsManager to manage the @p manager.
67  * When using Registry::createDpmsManager there is no need to call this
68  * method.
69  **/
70  void setup(org_kde_kwin_dpms_manager *manager);
71  /**
72  * Releases the org_kde_kwin_dpms_manager interface.
73  * After the interface has been released the DpmsManager instance is no
74  * longer valid and can be setup with another org_kde_kwin_dpms_manager interface.
75  **/
76  void release();
77  /**
78  * Destroys the data held by this DpmsManager.
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 org_kde_kwin_dpms_manager interface
84  * once there is a new connection available.
85  *
86  * This method is automatically invoked when the Registry which created this
87  * DPMS gets destroyed.
88  *
89  * @see release
90  **/
91  void destroy();
92 
93  /**
94  * Sets the @p queue to use for creating a Dpms.
95  **/
96  void setEventQueue(EventQueue *queue);
97  /**
98  * @returns The event queue to use for creating a Dpms.
99  **/
100  EventQueue *eventQueue();
101 
102  Dpms *getDpms(Output *output, QObject *parent = nullptr);
103 
104  operator org_kde_kwin_dpms_manager *();
105  operator org_kde_kwin_dpms_manager *() const;
106 
107 Q_SIGNALS:
108  /**
109  * The corresponding global for this interface on the Registry got removed.
110  *
111  * This signal gets only emitted if the DpmsManager got created by
112  * Registry::createDpmsManager
113  **/
114  void removed();
115 
116 private:
117  class Private;
119 };
120 
121 /**
122  * @short Power management for monitors.
123  *
124  * Display Power Management Signaling allows power management for monitors.
125  * This class is a convenient wrapper for the org_kde_kwin_dpms interface.
126  * To create a Dpms call DpmsManager::getDpms.
127  *
128  * @see DpmsManager
129  **/
130 class KWAYLANDCLIENT_EXPORT Dpms : public QObject
131 {
132  Q_OBJECT
133 public:
134  virtual ~Dpms();
135 
136  enum class Mode {
137  On,
138  Standby,
139  Suspend,
140  Off,
141  };
142 
143  /**
144  * Setup this Dpms to manage the @p dpms.
145  * When using DpmsManager::createDpms there is no need to call this
146  * method.
147  **/
148  void setup(org_kde_kwin_dpms *dpms);
149  /**
150  * Releases the org_kde_kwin_dpms interface.
151  * After the interface has been released the Dpms instance is no
152  * longer valid and can be setup with another org_kde_kwin_dpms interface.
153  **/
154  void release();
155  /**
156  * Destroys the data held by this Dpms.
157  * This method is supposed to be used when the connection to the Wayland
158  * server goes away. If the connection is not valid anymore, it's not
159  * possible to call release anymore as that calls into the Wayland
160  * connection and the call would fail. This method cleans up the data, so
161  * that the instance can be deleted or set up to a new org_kde_kwin_dpms interface
162  * once there is a new connection available.
163  *
164  * It is suggested to connect this method to ConnectionThread::connectionDied:
165  * @code
166  * connect(connection, &ConnectionThread::connectionDied, source, &Dpms::destroy);
167  * @endcode
168  *
169  * @see release
170  **/
171  void destroy();
172  /**
173  * @returns @c true if managing a org_kde_kwin_dpms.
174  **/
175  bool isValid() const;
176 
177  /**
178  * @returns the Output for which this Dpms got created
179  **/
180  QPointer<Output> output() const;
181 
182  /**
183  * Whether Dpms is supported for the Output.
184  * Initially set to @c false.
185  * @returns whether Dpms is supported for the Output.
186  * @see supportedChanged
187  **/
188  bool isSupported() const;
189  /**
190  * The current Dpms mode.
191  * Initially set to @c Mode::On.
192  * @returns the current Dpms mode of the Output
193  * @see modeChanged
194  **/
195  Mode mode() const;
196 
197  /**
198  * Request to change the Output into Dpms @p mode.
199  * The Wayland compositor is not obliged to honor the request.
200  * If the mode changes the client is notified and @link modeChanged @endlink gets emitted.
201  * @param mode The requested Dpms mode.
202  **/
203  void requestMode(Mode mode);
204 
205  operator org_kde_kwin_dpms *();
206  operator org_kde_kwin_dpms *() const;
207 
208 Q_SIGNALS:
209  /**
210  * Emitted if the supported state on the Output changes.
211  * @see isSupported
212  **/
213  void supportedChanged();
214  /**
215  * Emitted if the Dpms mode on the Output changes.
216  * @see mode
217  **/
218  void modeChanged();
219 
220 private:
221  friend class DpmsManager;
222  explicit Dpms(const QPointer<Output> &o, QObject *parent = nullptr);
223  class Private;
225 };
226 
227 }
228 }
229 
230 Q_DECLARE_METATYPE(KWayland::Client::Dpms::Mode)
231 
232 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the wl_output interface.
Definition: output.h:54
QCA_EXPORT bool isSupported(const char *features, const QString &provider=QString())
This class is a factory for Dpms instances.
Definition: dpms.h:48
Power management for monitors.
Definition: dpms.h:130
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Oct 25 2021 22:52:23 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.