KWayland

xdgoutput.h
1 /*
2  SPDX-FileCopyrightText: 2018 David Edmundson <[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_XDGOUTPUT_H
7 #define KWAYLAND_CLIENT_XDGOUTPUT_H
8 
9 #include <QObject>
10 #include <QPoint>
11 #include <QSize>
12 
13 #include <KWayland/Client/kwaylandclient_export.h>
14 
15 struct zxdg_output_manager_v1;
16 struct zxdg_output_v1;
17 
18 namespace KWayland
19 {
20 namespace Client
21 {
22 class EventQueue;
23 class XdgOutput;
24 class Output;
25 
26 /**
27  * @short Wrapper for the zxdg_output_manager_v1 interface.
28  *
29  * This class provides a convenient wrapper for the zxdg_output_manager_v1 interface.
30  *
31  * This provides the logical size of the output. This is useful in case it doesn't match the
32  * pixelSize / outputScale.
33  *
34  * To use this class one needs to interact with the Registry. There are two
35  * possible ways to create the XdgOutputManager interface:
36  * @code
37  * XdgOutputManager *c = registry->createXdgOutputManager(name, version);
38  * @endcode
39  *
40  * This creates the XdgOutputManager and sets it up directly. As an alternative this
41  * can also be done in a more low level way:
42  * @code
43  * XdgOutputManager *c = new XdgOutputManager;
44  * c->setup(registry->bindXdgOutputManager(name, version));
45  * @endcode
46  *
47  * The XdgOutputManager can be used as a drop-in replacement for any zxdg_output_manager_v1
48  * pointer as it provides matching cast operators.
49  *
50  * @since 5.47
51  *
52  * @see Registry
53  **/
54 class KWAYLANDCLIENT_EXPORT XdgOutputManager : public QObject
55 {
56  Q_OBJECT
57 public:
58  /**
59  * Creates a new XdgOutputManager.
60  * Note: after constructing the XdgOutputManager it is not yet valid and one needs
61  * to call setup. In order to get a ready to use XdgOutputManager prefer using
62  * Registry::createXdgOutputManager.
63  **/
64  explicit XdgOutputManager(QObject *parent = nullptr);
65  virtual ~XdgOutputManager();
66 
67  /**
68  * Setup this XdgOutputManager to manage the @p xdgoutputmanager.
69  * When using Registry::createXdgOutputManager there is no need to call this
70  * method.
71  **/
72  void setup(zxdg_output_manager_v1 *xdgoutputmanager);
73  /**
74  * @returns @c true if managing a zxdg_output_manager_v1.
75  **/
76  bool isValid() const;
77  /**
78  * Releases the zxdg_output_manager_v1 interface.
79  * After the interface has been released the XdgOutputManager instance is no
80  * longer valid and can be setup with another zxdg_output_manager_v1 interface.
81  **/
82  void release();
83  /**
84  * Destroys the data held by this XdgOutputManager.
85  * This method is supposed to be used when the connection to the Wayland
86  * server goes away. If the connection is not valid anymore, it's not
87  * possible to call release anymore as that calls into the Wayland
88  * connection and the call would fail. This method cleans up the data, so
89  * that the instance can be deleted or set up to a new zxdg_output_manager_v1 interface
90  * once there is a new connection available.
91  *
92  * It is suggested to connect this method to ConnectionThread::connectionDied:
93  * @code
94  * connect(connection, &ConnectionThread::connectionDied, xdgoutputmanager, &XdgOutputManager::destroy);
95  * @endcode
96  *
97  * @see release
98  **/
99  void destroy();
100 
101  /**
102  * Sets the @p queue to use for creating objects with this XdgOutputManager.
103  **/
104  void setEventQueue(EventQueue *queue);
105  /**
106  * @returns The event queue to use for creating objects with this XdgOutputManager.
107  **/
108  EventQueue *eventQueue();
109 
110  XdgOutput *getXdgOutput(Output *output, QObject *parent = nullptr);
111 
112  operator zxdg_output_manager_v1 *();
113  operator zxdg_output_manager_v1 *() const;
114 
115 Q_SIGNALS:
116  /**
117  * The corresponding global for this interface on the Registry got removed.
118  *
119  * This signal gets only emitted if the XdgOutputManager got created by
120  * Registry::createXdgOutputManager
121  **/
122  void removed();
123 
124 private:
125  class Private;
127 };
128 
129 /**
130  * @short Wrapper for the zxdg_output_v1 interface.
131  *
132  * This class provides a convenient wrapper for the zxdg_output_v1 interface.
133  *
134  * The XdgOutputManager can be used as a drop-in replacement for any zxdg_output_v1
135  * pointer as it provides matching cast operators.
136  *
137  * This protocol provides a potentially more correct size and position of the screen
138  * than Output with respect to scaling.
139  *
140  * @see Registry
141  **/
142 
143 class KWAYLANDCLIENT_EXPORT XdgOutput : public QObject
144 {
145  Q_OBJECT
146 public:
147  virtual ~XdgOutput();
148 
149  /**
150  * Setup this XdgOutput to manage the @p xdgoutput.
151  * When using XdgOutputManager::createXdgOutput there is no need to call this
152  * method.
153  **/
154  void setup(zxdg_output_v1 *xdgoutput);
155  /**
156  * @returns @c true if managing a zxdg_output_v1.
157  **/
158  bool isValid() const;
159  /**
160  * Releases the zxdg_output_v1 interface.
161  * After the interface has been released the XdgOutput instance is no
162  * longer valid and can be setup with another zxdg_output_v1 interface.
163  **/
164  void release();
165  /**
166  * Destroys the data held by this XdgOutput.
167  * This method is supposed to be used when the connection to the Wayland
168  * server goes away. If the connection is not valid anymore, it's not
169  * possible to call release anymore as that calls into the Wayland
170  * connection and the call would fail. This method cleans up the data, so
171  * that the instance can be deleted or set up to a new zxdg_output_v1 interface
172  * once there is a new connection available.
173  *
174  * It is suggested to connect this method to ConnectionThread::connectionDied:
175  * @code
176  * connect(connection, &ConnectionThread::connectionDied, xdgoutput, &XdgOutput::destroy);
177  * @endcode
178  *
179  * @see release
180  **/
181  void destroy();
182 
183  operator zxdg_output_v1 *();
184  operator zxdg_output_v1 *() const;
185 
186  /**
187  * The top left position of the output in compositor coordinates
188  */
189  QPoint logicalPosition() const;
190 
191  /**
192  * The size of the output in compositor coordinates
193  * (i.e pixel size / output scale)
194  */
195  QSize logicalSize() const;
196 
197  /**
198  * A consistent unique name for this monitor
199  * @since 5.XDGOUTPUT
200  */
201  QString name() const;
202 
203  /**
204  * A longer human readable description
205  * @since 5.XDGOUTPUT
206  */
207  QString description() const;
208 
209 Q_SIGNALS:
210  /**
211  * Emitted when any of the attributes have changed
212  */
213  void changed();
214 
215 private:
216  friend class XdgOutputManager;
217  explicit XdgOutput(QObject *parent = nullptr);
218  class Private;
220 };
221 
222 }
223 }
224 
225 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the wl_output interface.
Definition: output.h:54
Wrapper for the zxdg_output_v1 interface.
Definition: xdgoutput.h:143
Wrapper for the zxdg_output_manager_v1 interface.
Definition: xdgoutput.h:54
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Aug 3 2021 22:50:50 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.