KWaylandServer

xdgshell_interface.h
1 /*
2  SPDX-FileCopyrightText: 2020 Vlad Zahorodnii <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 
7 #pragma once
8 
9 #include <KWaylandServer/kwaylandserver_export.h>
10 
11 #include <QObject>
12 #include <QSharedDataPointer>
13 
14 struct wl_resource;
15 
16 namespace KWaylandServer
17 {
18 class Display;
19 class OutputInterface;
20 class SeatInterface;
21 class SurfaceInterface;
22 class XdgShellInterfacePrivate;
23 class XdgSurfaceInterfacePrivate;
24 class XdgToplevelInterfacePrivate;
25 class XdgPopupInterfacePrivate;
26 class XdgPositionerData;
27 class XdgToplevelInterface;
28 class XdgPopupInterface;
29 class XdgSurfaceInterface;
30 
31 /**
32  * The XdgShellInterface class represents an extension for destrop-style user interfaces.
33  *
34  * The XdgShellInterface class provides a way for a client to extend a regular Wayland surface
35  * with functionality required to construct user interface elements, e.g. toplevel windows or
36  * menus.
37  *
38  * XdgShellInterface corresponds to the WaylandInterface \c xdg_wm_base.
39  */
40 class KWAYLANDSERVER_EXPORT XdgShellInterface : public QObject
41 {
42  Q_OBJECT
43 
44 public:
45  /**
46  * Constructs an XdgShellInterface object with the given wayland display \a display.
47  */
48  XdgShellInterface(Display *display, QObject *parent = nullptr);
49  /**
50  * Destructs the XdgShellInterface object.
51  */
52  ~XdgShellInterface() override;
53 
54  /**
55  * Returns the wayland display of the XdgShellInterface.
56  */
57  Display *display() const;
58 
59  /**
60  * Sends a ping event to the client with the given xdg-surface \a surface. If the client
61  * replies to the event within a reasonable amount of time, pongReceived signal will be
62  * emitted.
63  */
64  quint32 ping(XdgSurfaceInterface *surface);
65 
66 Q_SIGNALS:
67  /**
68  * This signal is emitted when a new XdgToplevelInterface object is created.
69  */
70  void toplevelCreated(XdgToplevelInterface *toplevel);
71 
72  /**
73  * This signal is emitted when a new XdgPopupInterface object is created.
74  */
75  void popupCreated(XdgPopupInterface *popup);
76 
77  /**
78  * This signal is emitted when the client has responded to a ping event with serial \a serial.
79  */
80  void pongReceived(quint32 serial);
81 
82  /**
83  * @todo Drop this signal.
84  *
85  * This signal is emitted when the client has not responded to a ping event with serial
86  * \a serial within a reasonable amount of time and the compositor gave up on it.
87  */
88  void pingTimeout(quint32 serial);
89 
90  /**
91  * This signal is emitted when the client has not responded to a ping event with serial
92  * \a serial within a reasonable amount of time.
93  */
94  void pingDelayed(quint32 serial);
95 
96 private:
98  friend class XdgShellInterfacePrivate;
99 };
100 
101 /**
102  * The XdgSurfaceInterface class provides a base set of functionality required to construct
103  * user interface elements.
104  *
105  * XdgSurfaceInterface corresponds to the Wayland interface \c xdg_surface.
106  */
107 class KWAYLANDSERVER_EXPORT XdgSurfaceInterface : public QObject
108 {
109  Q_OBJECT
110 
111 public:
112  /**
113  * Constructs an XdgSurfaceInterface for the given \a shell and \a surface.
114  */
115  XdgSurfaceInterface(XdgShellInterface *shell, SurfaceInterface *surface, ::wl_resource *resource);
116  /**
117  * Destructs the XdgSurfaceInterface object.
118  */
119  ~XdgSurfaceInterface() override;
120 
121  /**
122  * Returns the XdgToplevelInterface associated with this XdgSurfaceInterface.
123  *
124  * This method will return \c null if no xdg_toplevel object is associated with this surface.
125  */
126  XdgToplevelInterface *toplevel() const;
127 
128  /**
129  * Returns the XdgPopupInterface associated with this XdgSurfaceInterface.
130  *
131  * This method will return \c null if no xdg_popup object is associated with this surface.
132  */
133  XdgPopupInterface *popup() const;
134 
135  /**
136  * Returns the XdgShellInterface associated with this XdgSurfaceInterface.
137  */
138  XdgShellInterface *shell() const;
139 
140  /**
141  * Returns the SurfaceInterface assigned to this XdgSurfaceInterface.
142  */
143  SurfaceInterface *surface() const;
144 
145  /**
146  * Returns \c true if the surface has been configured; otherwise returns \c false.
147  */
148  bool isConfigured() const;
149 
150  /**
151  * Returns the window geometry of the XdgSurfaceInterface.
152  *
153  * This method will return an invalid QRect if the window geometry is not set by the client.
154  */
155  QRect windowGeometry() const;
156 
157  /**
158  * Returns the XdgSurfaceInterface for the specified wayland resource object \a resource.
159  */
160  static XdgSurfaceInterface *get(::wl_resource *resource);
161 
162 Q_SIGNALS:
163  /**
164  * This signal is emitted when the xdg-surface is about to be destroyed.
165  */
166  void aboutToBeDestroyed();
167 
168  /**
169  * This signal is emitted when a configure event with serial \a serial has been acknowledged.
170  */
171  void configureAcknowledged(quint32 serial);
172 
173  /**
174  * This signal is emitted when the window geometry has been changed.
175  */
176  void windowGeometryChanged(const QRect &rect);
177 
178  /**
179  * This signal is emitted when the surface has been unmapped and its state has been reset.
180  */
181  void resetOccurred();
182 
183 private:
185  friend class XdgSurfaceInterfacePrivate;
186 };
187 
188 /**
189  * The XdgToplevelInterface class represents a surface with window-like functionality such
190  * as maximize, fullscreen, resizing, minimizing, etc.
191  *
192  * XdgToplevelInterface corresponds to the Wayland interface \c xdg_toplevel.
193  */
194 class KWAYLANDSERVER_EXPORT XdgToplevelInterface : public QObject
195 {
196  Q_OBJECT
197 
198 public:
199  enum State {
200  MaximizedHorizontal = 0x1,
201  MaximizedVertical = 0x2,
202  FullScreen = 0x4,
203  Resizing = 0x8,
204  Activated = 0x10,
205  TiledLeft = 0x20,
206  TiledTop = 0x40,
207  TiledRight = 0x80,
208  TiledBottom = 0x100,
209  Maximized = MaximizedHorizontal | MaximizedVertical,
210  };
211  Q_DECLARE_FLAGS(States, State)
212 
213  /**
214  * Constructs an XdgToplevelInterface for the given xdg-surface \a surface.
215  */
216  XdgToplevelInterface(XdgSurfaceInterface *surface, ::wl_resource *resource);
217  /**
218  * Destructs the XdgToplevelInterface object.
219  */
220  ~XdgToplevelInterface() override;
221 
222  /**
223  * Returns the XdgShellInterface for this XdgToplevelInterface.
224  *
225  * This is equivalent to xdgSurface()->shell().
226  */
227  XdgShellInterface *shell() const;
228 
229  /**
230  * Returns the XdgSurfaceInterface associated with the XdgToplevelInterface.
231  */
232  XdgSurfaceInterface *xdgSurface() const;
233 
234  /**
235  * Returns the SurfaceInterface associated with the XdgToplevelInterface.
236  */
237  SurfaceInterface *surface() const;
238 
239  /**
240  * Returns the parent XdgToplevelInterface above which this toplevel is stacked.
241  */
242  XdgToplevelInterface *parentXdgToplevel() const;
243 
244  /**
245  * Returns \c true if the toplevel has been configured; otherwise returns \c false.
246  */
247  bool isConfigured() const;
248 
249  /**
250  * Returns the window title of the toplevel surface.
251  */
252  QString windowTitle() const;
253 
254  /**
255  * Returns the window class of the toplevel surface.
256  */
257  QString windowClass() const;
258 
259  /**
260  * Returns the minimum window geometry size of the toplevel surface.
261  */
262  QSize minimumSize() const;
263 
264  /**
265  * Returns the maximum window geometry size of the toplevel surface.
266  */
267  QSize maximumSize() const;
268 
269  /**
270  * Sends a configure event to the client. \a size specifies the new window geometry size. A size
271  * of zero means the client should decide its own window dimensions.
272  */
273  quint32 sendConfigure(const QSize &size, const States &states);
274 
275  /**
276  * Sends a close event to the client. The client may choose to ignore this request.
277  */
278  void sendClose();
279 
280  /**
281  * Returns the XdgToplevelInterface for the specified wayland resource object \a resource.
282  */
283  static XdgToplevelInterface *get(::wl_resource *resource);
284 
285 Q_SIGNALS:
286  /**
287  * This signal is emitted when the xdg-toplevel is about to be destroyed.
288  */
289  void aboutToBeDestroyed();
290 
291  /**
292  * This signal is emitted when the xdg-toplevel has commited the initial state and wants to
293  * be configured. After initializing the toplevel, you must send a configure event.
294  */
295  void initializeRequested();
296 
297  /**
298  * This signal is emitted when the toplevel has been unmapped and its state has been reset.
299  */
300  void resetOccurred();
301 
302  /**
303  * This signal is emitted when the toplevel's title has been changed.
304  */
305  void windowTitleChanged(const QString &windowTitle);
306 
307  /**
308  * This signal is emitted when the toplevel's application id has been changed.
309  */
310  void windowClassChanged(const QString &windowClass);
311 
312  /**
313  * This signal is emitted when the toplevel has requested the window menu to be shown at
314  * \a pos. The \a seat and the \a serial indicate the user action that triggerred the request.
315  */
316  void windowMenuRequested(KWaylandServer::SeatInterface *seat, const QPoint &pos, quint32 serial);
317 
318  /**
319  * This signal is emitted when the toplevel's minimum size has been changed.
320  */
321  void minimumSizeChanged(const QSize &size);
322 
323  /**
324  * This signal is emitted when the toplevel's maximum size has been changed.
325  */
326  void maximumSizeChanged(const QSize &size);
327 
328  /**
329  * This signal is emitted when the toplevel wants to be interactively moved. The \a seat and
330  * the \a serial indicate the user action in response to which this request has been issued.
331  */
332  void moveRequested(KWaylandServer::SeatInterface *seat, quint32 serial);
333 
334  /**
335  * This signal is emitted when the toplevel wants to be interactively resized along the
336  * specified window edges \a edges. The \a seat and the \a serial indicate the user action
337  * in response to which this request has been issued.
338  */
339  void resizeRequested(KWaylandServer::SeatInterface *seat, Qt::Edges edges, quint32 serial);
340 
341  /**
342  * This signal is emitted when the toplevel surface wants to become maximized.
343  */
344  void maximizeRequested();
345 
346  /**
347  * This signal is emitted when the toplevel surface wants to become unmaximized.
348  */
349  void unmaximizeRequested();
350 
351  /**
352  * This signal is emitted when the toplevel wants to be shown in the full screen mode.
353  */
354  void fullscreenRequested(KWaylandServer::OutputInterface *output);
355 
356  /**
357  * This signal is emitted when the toplevel surface wants to leave the full screen mode.
358  */
359  void unfullscreenRequested();
360 
361  /**
362  * This signal is emitted when the toplevel wants to be iconified.
363  */
364  void minimizeRequested();
365 
366  /**
367  * This signal is emitted when the parent toplevel has changed.
368  */
369  void parentXdgToplevelChanged();
370 
371 private:
373  friend class XdgToplevelInterfacePrivate;
374 };
375 
376 /**
377  * The XdgPositioner class provides a collection of rules for the placement of a popup surface.
378  *
379  * XdgPositioner corresponds to the Wayland interface \c xdg_positioner.
380  */
381 class KWAYLANDSERVER_EXPORT XdgPositioner
382 {
383 public:
384  /**
385  * Constructs an incomplete XdgPositioner object.
386  */
387  XdgPositioner();
388  /**
389  * Constructs a copy of the XdgPositioner object.
390  */
391  XdgPositioner(const XdgPositioner &other);
392  /**
393  * Destructs the XdgPositioner object.
394  */
395  ~XdgPositioner();
396 
397  /**
398  * Assigns the value of \a other to this XdgPositioner object.
399  */
400  XdgPositioner &operator=(const XdgPositioner &other);
401 
402  /**
403  * Returns \c true if the positioner object is complete; otherwise returns \c false.
404  *
405  * An xdg positioner considered complete if it has a valid size and a valid anchor rect.
406  */
407  bool isComplete() const;
408 
409  /**
410  * Returns the set of orientations along which the compositor may slide the popup to ensure
411  * that it is entirely inside the compositor's defined "work area."
412  */
413  Qt::Orientations slideConstraintAdjustments() const;
414 
415  /**
416  * Returns the set of orientations along which the compositor may flip the popup to ensure
417  * that it is entirely inside the compositor's defined "work area."
418  */
419  Qt::Orientations flipConstraintAdjustments() const;
420 
421  /**
422  * Returns the set of orientations along which the compositor can resize the popup to ensure
423  * that it is entirely inside the compositor's defined "work area."
424  */
425  Qt::Orientations resizeConstraintAdjustments() const;
426 
427  /**
428  * Returns the set of edges on the anchor rectangle that the surface should be positioned
429  * around.
430  */
431  Qt::Edges anchorEdges() const;
432 
433  /**
434  * Returns the direction in which the surface should be positioned, relative to the anchor
435  * point of the parent surface.
436  */
437  Qt::Edges gravityEdges() const;
438 
439  /**
440  * Returns the window geometry size of the surface that is to be positioned.
441  */
442  QSize size() const;
443 
444  /**
445  * Returns the anchor rectangle relative to the upper left corner of the window geometry of
446  * the parent surface that the popup should be positioned around.
447  */
448  QRect anchorRect() const;
449 
450  /**
451  * Returns the surface position offset relative to the position of the anchor on the anchor
452  * rectangle and the anchor on the surface.
453  */
454  QPoint offset() const;
455 
456  /**
457  * Returns whether the surface should respond to movements in its parent window.
458  */
459  bool isReactive() const;
460 
461  /**
462  * Returns the parent size to use when positioning the popup.
463  */
464  QSize parentSize() const;
465 
466  /**
467  * Returns the serial of the configure event for the parent window.
468  */
469  quint32 parentConfigure() const;
470 
471  /**
472  * Returns the current state of the xdg positioner object identified by \a resource.
473  */
474  static XdgPositioner get(::wl_resource *resource);
475 
476 private:
479 };
480 
481 /**
482  * The XdgPopupInterface class represents a surface that can be used to implement context menus,
483  * popovers and other similar short-lived user interface elements.
484  *
485  * XdgPopupInterface corresponds to the Wayland interface \c xdg_popup.
486  */
487 class KWAYLANDSERVER_EXPORT XdgPopupInterface : public QObject
488 {
489  Q_OBJECT
490 
491 public:
492  XdgPopupInterface(XdgSurfaceInterface *surface, SurfaceInterface *parentSurface, const XdgPositioner &positioner, ::wl_resource *resource);
493  /**
494  * Destructs the XdgPopupInterface object.
495  */
496  ~XdgPopupInterface() override;
497 
498  XdgShellInterface *shell() const;
499 
500  /**
501  * Returns the parent surface for this popup surface. If the initial state hasn't been
502  * committed yet, this function may return \c null.
503  */
504  SurfaceInterface *parentSurface() const;
505 
506  /**
507  * Returns the XdgSurfaceInterface associated with the XdgPopupInterface.
508  */
509  XdgSurfaceInterface *xdgSurface() const;
510 
511  /**
512  * Returns the SurfaceInterface associated with the XdgPopupInterface.
513  */
514  SurfaceInterface *surface() const;
515 
516  /**
517  * Returns the XdgPositioner assigned to this XdgPopupInterface.
518  */
519  XdgPositioner positioner() const;
520 
521  /**
522  * Returns \c true if the popup has been configured; otherwise returns \c false.
523  */
524  bool isConfigured() const;
525 
526  /**
527  * Sends a configure event to the client and returns the serial number of the event.
528  */
529  quint32 sendConfigure(const QRect &rect);
530 
531  /**
532  * Sends a popup done event to the client.
533  */
534  void sendPopupDone();
535 
536  /**
537  * Sends a popup repositioned event to the client.
538  */
539  void sendRepositioned(quint32 token);
540 
541  /**
542  * Returns the XdgPopupInterface for the specified wayland resource object \a resource.
543  */
544  static XdgPopupInterface *get(::wl_resource *resource);
545 
546 Q_SIGNALS:
547  /**
548  * This signal is emitted when the xdg-popup is about to be destroyed.
549  */
550  void aboutToBeDestroyed();
551 
552  /**
553  * This signal is emitted when the xdg-popup has commited the initial state and wants to
554  * be configured. After initializing the popup, you must send a configure event.
555  */
556  void initializeRequested();
557  void grabRequested(SeatInterface *seat, quint32 serial);
558  void repositionRequested(quint32 token);
559 
560 private:
562  friend class XdgPopupInterfacePrivate;
563 };
564 
565 } // namespace KWaylandServer
566 
567 Q_DECLARE_OPERATORS_FOR_FLAGS(KWaylandServer::XdgToplevelInterface::States)
568 Q_DECLARE_METATYPE(KWaylandServer::XdgToplevelInterface::State)
Represents a Seat on the Wayland Display.
The OutputInterface class represents a screen.
typedef Edges
Class holding the Wayland server display loop.
Definition: display.h:47
The XdgPopupInterface class represents a surface that can be used to implement context menus...
The XdgPositioner class provides a collection of rules for the placement of a popup surface...
The XdgShellInterface class represents an extension for destrop-style user interfaces.
The XdgToplevelInterface class represents a surface with window-like functionality such as maximize...
Resource representing a wl_surface.
typedef Orientations
The XdgSurfaceInterface class provides a base set of functionality required to construct user interfa...
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Oct 25 2021 23:08:44 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.