1/*
2 SPDX-FileCopyrightText: 2017 Marco Martin <notmart@gmail.com>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6#ifndef KWAYLAND_CLIENT_XDGFOREIGN_H
7#define KWAYLAND_CLIENT_XDGFOREIGN_H
8
9#include "surface.h"
10
11#include <QObject>
12
13#include "KWayland/Client/kwaylandclient_export.h"
14
15struct zxdg_exporter_v2;
16struct zxdg_importer_v2;
17struct zxdg_exported_v2;
18struct zxdg_imported_v2;
19
20namespace KWayland
21{
22namespace Client
23{
24class EventQueue;
25class Surface;
26class XdgExported;
27class XdgImported;
28
29/**
30 * @short Wrapper for the zxdg_exporter_v2 interface.
31 *
32 * This class provides a convenient wrapper for the zxdg_exporter_v2 interface.
33 *
34 * To use this class one needs to interact with the Registry. There are two
35 * possible ways to create the XdgExporter interface:
36 * @code
37 * *c = registry->create(name, version);
38 * @endcode
39 *
40 * This creates the XdgExporter and sets it up directly. As an alternative this
41 * can also be done in a more low level way:
42 * @code
43 * *c = new ;
44 * c->setup(registry->bind(name, version));
45 * @endcode
46 *
47 * The XdgExporter can be used as a drop-in replacement for any zxdg_exporter_v2
48 * pointer as it provides matching cast operators.
49 *
50 * @see Registry
51 **/
52class KWAYLANDCLIENT_EXPORT XdgExporter : public QObject
53{
54 Q_OBJECT
55public:
56 ~XdgExporter() override;
57
58 /**
59 * Setup this XdgExporter to manage the @p .
60 * When using Registry::create there is no need to call this
61 * method.
62 **/
63 void setup(zxdg_exporter_v2 *);
64 /**
65 * @returns @c true if managing a zxdg_exporter_v2.
66 **/
67 bool isValid() const;
68 /**
69 * Releases the zxdg_exporter_v2 interface.
70 * After the interface has been released the XdgExporter instance is no
71 * longer valid and can be setup with another zxdg_exporter_v2 interface.
72 **/
73 void release();
74 /**
75 * Destroys the data held by this .
76 * This method is supposed to be used when the connection to the Wayland
77 * server goes away. If the connection is not valid anymore, it's not
78 * possible to call release anymore as that calls into the Wayland
79 * connection and the call would fail. This method cleans up the data, so
80 * that the instance can be deleted or set up to a new zxdg_exporter_v2 interface
81 * once there is a new connection available.
82 *
83 * It is suggested to connect this method to ConnectionThread::connectionDied:
84 * @code
85 * connect(connection, &ConnectionThread::connectionDied, , &::destroy);
86 * @endcode
87 *
88 * @see release
89 **/
90 void destroy();
91
92 /**
93 * Sets the @p queue to use for creating objects with this .
94 **/
95 void setEventQueue(EventQueue *queue);
96 /**
97 * @returns The event queue to use for creating objects with this .
98 **/
99 EventQueue *eventQueue();
100
101 /**
102 * The export request exports the passed surface so that it can later be
103 * imported via XdgImporter::importTopLevel.
104 * A surface may be exported multiple times, and each exported handle may
105 * be used to create an XdgImported multiple times.
106 * @param surface the surface which we want to export an handle.
107 * @param parent the parent in the QObject's hierarchy of the new XdgExported
108 */
109 XdgExported *exportTopLevel(Surface *surface, QObject *parent = nullptr);
110
111 operator zxdg_exporter_v2 *();
112 operator zxdg_exporter_v2 *() const;
113
114Q_SIGNALS:
115 /**
116 * The corresponding global for this interface on the Registry got removed.
117 *
118 * This signal gets only emitted if the XdgExporter got created by
119 * Registry::create
120 **/
121 void removed();
122
123protected:
124 class Private;
125 explicit XdgExporter(Private *p, QObject *parent = nullptr);
126 QScopedPointer<Private> d;
127};
128
129/**
130 * @short Wrapper for the zxdg_importer_v2 interface.
131 *
132 * This class provides a convenient wrapper for the zxdg_importer_v2 interface.
133 *
134 * To use this class one needs to interact with the Registry. There are two
135 * possible ways to create the XdgImporter interface:
136 * @code
137 * *c = registry->create(name, version);
138 * @endcode
139 *
140 * This creates the XdgImporter and sets it up directly. As an alternative this
141 * can also be done in a more low level way:
142 * @code
143 * *c = new ;
144 * c->setup(registry->bind(name, version));
145 * @endcode
146 *
147 * The XdgImporter can be used as a drop-in replacement for any zxdg_importer_v2
148 * pointer as it provides matching cast operators.
149 *
150 * @see Registry
151 **/
152class KWAYLANDCLIENT_EXPORT XdgImporter : public QObject
153{
154 Q_OBJECT
155public:
156 ~XdgImporter() override;
157
158 /**
159 * Setup this XdgImporter to manage the @p .
160 * When using Registry::create there is no need to call this
161 * method.
162 **/
163 void setup(zxdg_importer_v2 *);
164 /**
165 * @returns @c true if managing a zxdg_importer_v2.
166 **/
167 bool isValid() const;
168 /**
169 * Releases the zxdg_importer_v2 interface.
170 * After the interface has been released the XdgImporter instance is no
171 * longer valid and can be setup with another zxdg_importer_v2 interface.
172 **/
173 void release();
174 /**
175 * Destroys the data held by this .
176 * This method is supposed to be used when the connection to the Wayland
177 * server goes away. If the connection is not valid anymore, it's not
178 * possible to call release anymore as that calls into the Wayland
179 * connection and the call would fail. This method cleans up the data, so
180 * that the instance can be deleted or set up to a new zxdg_importer_v2 interface
181 * once there is a new connection available.
182 *
183 * It is suggested to connect this method to ConnectionThread::connectionDied:
184 * @code
185 * connect(connection, &ConnectionThread::connectionDied, , &::destroy);
186 * @endcode
187 *
188 * @see release
189 **/
190 void destroy();
191
192 /**
193 * Sets the @p queue to use for creating objects with this .
194 **/
195 void setEventQueue(EventQueue *queue);
196 /**
197 * @returns The event queue to use for creating objects with this .
198 **/
199 EventQueue *eventQueue();
200
201 /**
202 * Imports a surface from any client given a handle
203 * retrieved by exporting said surface using XdgExporter::exportTopLevel.
204 * When called, a new XdgImported object will be created.
205 * This new object represents the imported surface, and the importing
206 * client can manipulate its relationship using it.
207 *
208 * @param handle the unique handle that represent an exported toplevel surface.
209 * it has to have been generated by the XdgExporter by either this
210 * or some other process (which would have communicated the handle
211 * in some way, such as command line or a DBus call)
212 * @param parent the parent in the QObject's hierarchy of the new XdgImported
213 */
214 XdgImported *importTopLevel(const QString &handle, QObject *parent = nullptr);
215
216 operator zxdg_importer_v2 *();
217 operator zxdg_importer_v2 *() const;
218
219Q_SIGNALS:
220 /**
221 * The corresponding global for this interface on the Registry got removed.
222 *
223 * This signal gets only emitted if the XdgImporter got created by
224 * Registry::create
225 **/
226 void removed();
227
228protected:
229 class Private;
230 explicit XdgImporter(Private *p, QObject *parent = nullptr);
231 QScopedPointer<Private> d;
232};
233
234class KWAYLANDCLIENT_EXPORT XdgExported : public QObject
235{
236 Q_OBJECT
237public:
238 ~XdgExported() override;
239
240 /**
241 * Setup this XdgExported to manage the @p .
242 * When using ::create there is no need to call this
243 * method.
244 **/
245 void setup(zxdg_exported_v2 *);
246 /**
247 * @returns @c true if managing a zxdg_exported_v2.
248 **/
249 bool isValid() const;
250 /**
251 * Releases the zxdg_exported_v2 interface.
252 * After the interface has been released the XdgExported instance is no
253 * longer valid and can be setup with another zxdg_exported_v2 interface.
254 **/
255 void release();
256 /**
257 * Destroys the data held by this .
258 * This method is supposed to be used when the connection to the Wayland
259 * server goes away. If the connection is not valid anymore, it's not
260 * possible to call release anymore as that calls into the Wayland
261 * connection and the call would fail. This method cleans up the data, so
262 * that the instance can be deleted or set up to a new zxdg_exported_v2 interface
263 * once there is a new connection available.
264 *
265 * It is suggested to connect this method to ConnectionThread::connectionDied:
266 * @code
267 * connect(connection, &ConnectionThread::connectionDied, , &::destroy);
268 * @endcode
269 *
270 * @see release
271 **/
272 void destroy();
273
274 /**
275 * @returns The unique handle corresponding tho this exported surface.
276 * Any process can import this toplevel surface provided they know this
277 * unique string.
278 */
279 QString handle() const;
280
281 operator zxdg_exported_v2 *();
282 operator zxdg_exported_v2 *() const;
283
284Q_SIGNALS:
285 /**
286 * Emitted when the exported window is fully initialized.
287 * the handle will be valid at this point
288 **/
289 void done();
290
291protected:
292 friend class XdgExporter;
293 class Private;
294 explicit XdgExported(Private *p, QObject *parent = nullptr);
295 QScopedPointer<Private> d;
296};
297
298class KWAYLANDCLIENT_EXPORT XdgImported : public QObject
299{
300 Q_OBJECT
301public:
302 ~XdgImported() override;
303
304 /**
305 * Setup this XdgImported to manage the @p .
306 * When using ::create there is no need to call this
307 * method.
308 **/
309 void setup(zxdg_imported_v2 *);
310 /**
311 * @returns @c true if managing a zxdg_imported_v2.
312 **/
313 bool isValid() const;
314 /**
315 * Releases the zxdg_imported_v2 interface.
316 * After the interface has been released the XdgImported instance is no
317 * longer valid and can be setup with another zxdg_imported_v2 interface.
318 **/
319 void release();
320 /**
321 * Destroys the data held by this .
322 * This method is supposed to be used when the connection to the Wayland
323 * server goes away. If the connection is not valid anymore, it's not
324 * possible to call release anymore as that calls into the Wayland
325 * connection and the call would fail. This method cleans up the data, so
326 * that the instance can be deleted or set up to a new zxdg_imported_v2 interface
327 * once there is a new connection available.
328 *
329 * It is suggested to connect this method to ConnectionThread::connectionDied:
330 * @code
331 * connect(connection, &ConnectionThread::connectionDied, , &::destroy);
332 * @endcode
333 *
334 * @see release
335 **/
336 void destroy();
337
338 /**
339 * Set the imported surface as the parent of some surface of the client.
340 * The passed surface must be a toplevel xdg_surface.
341 * Calling this function sets up a surface to surface relation with the same
342 * stacking and positioning semantics as XdgShellSurface::setTransientFor
343 *
344 * @param surface the child surface, which must belong to this process.
345 */
346 void setParentOf(Surface *surface);
347
348 operator zxdg_imported_v2 *();
349 operator zxdg_imported_v2 *() const;
350
351Q_SIGNALS:
352 /**
353 * Emitted when the imported surface is not valid anymore,
354 * for instance because it's no longer exported on the other end
355 */
356 void importedDestroyed();
357
358protected:
359 friend class XdgImporter;
360 class Private;
361 explicit XdgImported(Private *p, QObject *parent = nullptr);
362 QScopedPointer<Private> d;
363};
364
365}
366}
367
368#endif
369

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