KWayland

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

KDE's Doxygen guidelines are available online.