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 class EventQueue;
25 class Surface;
26 class XdgExported;
27 class 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 interface:
36  * @code
37  * *c = registry->create(name, version);
38  * @endcode
39  *
40  * This creates the 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 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  **/
52 class KWAYLANDCLIENT_EXPORT XdgExporter : public QObject
53 {
54  Q_OBJECT
55 public:
56  virtual ~XdgExporter();
57 
58  /**
59  * Setup this 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 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 
114 Q_SIGNALS:
115  /**
116  * The corresponding global for this interface on the Registry got removed.
117  *
118  * This signal gets only emitted if the got created by
119  * Registry::create
120  **/
121  void removed();
122 
123 protected:
124  class Private;
125  explicit XdgExporter(Private *p, QObject *parent = nullptr);
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 interface:
136  * @code
137  * *c = registry->create(name, version);
138  * @endcode
139  *
140  * This creates the 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 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  **/
152 class KWAYLANDCLIENT_EXPORT XdgImporter : public QObject
153 {
154  Q_OBJECT
155 public:
156  virtual ~XdgImporter();
157 
158  /**
159  * Setup this 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 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 
219 Q_SIGNALS:
220  /**
221  * The corresponding global for this interface on the Registry got removed.
222  *
223  * This signal gets only emitted if the got created by
224  * Registry::create
225  **/
226  void removed();
227 
228 protected:
229  class Private;
230  explicit XdgImporter(Private *p, QObject *parent = nullptr);
232 };
233 
234 class KWAYLANDCLIENT_EXPORT XdgExported : public QObject
235 {
236  Q_OBJECT
237 public:
238  virtual ~XdgExported();
239 
240  /**
241  * Setup this 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 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 
284 Q_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 
291 protected:
292  friend class XdgExporter;
293  class Private;
294  explicit XdgExported(Private *p, QObject *parent = nullptr);
296 };
297 
298 class KWAYLANDCLIENT_EXPORT XdgImported : public QObject
299 {
300  Q_OBJECT
301 public:
302  virtual ~XdgImported();
303 
304  /**
305  * Setup this 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 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 
351 Q_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 
358 protected:
359  friend class XdgImporter;
360  class Private;
361  explicit XdgImported(Private *p, QObject *parent = nullptr);
363 };
364 
365 }
366 }
367 
368 #endif
Wrapper for the zxdg_exporter_v2 interface.
Definition: xdgforeign.h:52
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the zxdg_importer_v2 interface.
Definition: xdgforeign.h:152
Wrapper for the wl_surface interface.
Definition: surface.h:43
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 22:51:10 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.