1/*
2 SPDX-FileCopyrightText: 2018 David Edmundson <kde@davidedmundson.co.uk>
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
15struct zxdg_output_manager_v1;
16struct zxdg_output_v1;
17
18namespace KWayland
19{
20namespace Client
21{
22class EventQueue;
23class XdgOutput;
24class 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 **/
54class KWAYLANDCLIENT_EXPORT XdgOutputManager : public QObject
55{
56 Q_OBJECT
57public:
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 ~XdgOutputManager() override;
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
115Q_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
124private:
125 class Private;
126 QScopedPointer<Private> d;
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
143class KWAYLANDCLIENT_EXPORT XdgOutput : public QObject
144{
145 Q_OBJECT
146public:
147 ~XdgOutput() override;
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
209Q_SIGNALS:
210 /**
211 * Emitted when any of the attributes have changed
212 */
213 void changed();
214
215private:
216 friend class XdgOutputManager;
217 explicit XdgOutput(QObject *parent = nullptr);
218 class Private;
219 QScopedPointer<Private> d;
220};
221
222}
223}
224
225#endif
226

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