KWayland

xdgshell_interface.h
1 /*
2  SPDX-FileCopyrightText: 2016 Martin Gräßlin <[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_SERVER_XDGSHELL_INTERFACE_H
7 #define KWAYLAND_SERVER_XDGSHELL_INTERFACE_H
8 
9 #include "global.h"
10 #include "resource.h"
11 
12 #include <QSize>
13 
14 #include <KWayland/Server/kwaylandserver_export.h>
15 
16 namespace KWayland
17 {
18 namespace Server
19 {
20 class OutputInterface;
21 class SeatInterface;
22 class SurfaceInterface;
23 class XdgShellPopupInterface;
24 class XdgShellSurfaceInterface;
25 template<typename T>
26 class GenericShellSurface;
27 
28 /**
29  * Enum describing the different InterfaceVersion encapsulated in this implementation.
30  *
31  * @since 5.25
32  **/
34  /**
35  * xdg_shell (unstable v5)
36  **/
37  UnstableV5,
38  /**
39  * zxdg_shell_v6 (unstable v6)
40  * @since 5.39
41  **/
42  UnstableV6,
43  /**
44  xdg_wm_base (stable)
45  @since 5.48
46  */
47  Stable,
48 };
49 
50 /**
51  * Flags describing how a popup should be reposition if constrained
52  * @since 5.39
53  */
55  /**
56  * Slide the popup on the X axis until there is room
57  */
58  SlideX = 1 << 0,
59  /**
60  * Slide the popup on the Y axis until there is room
61  */
62  SlideY = 1 << 1,
63  /**
64  * Invert the anchor and gravity on the X axis
65  */
66  FlipX = 1 << 2,
67  /**
68  * Invert the anchor and gravity on the Y axis
69  */
70  FlipY = 1 << 3,
71  /**
72  * Resize the popup in the X axis
73  */
74  ResizeX = 1 << 4,
75  /**
76  * Resize the popup in the Y axis
77  */
78  ResizeY = 1 << 5,
79 };
80 
82 
83 /**
84  *
85  * @since 5.25
86  **/
87 class KWAYLANDSERVER_EXPORT XdgShellInterface : public Global
88 {
89  Q_OBJECT
90 public:
91  virtual ~XdgShellInterface();
92 
93  /**
94  * @returns The interface version used by this XdgShellInterface
95  **/
96  XdgShellInterfaceVersion interfaceVersion() const;
97 
98  /**
99  * @returns The XdgShellSurfaceInterface for the @p native resource.
100  **/
101  // TODO KF6 make virtual
102  XdgShellSurfaceInterface *getSurface(wl_resource *native);
103 
104  /**
105  * Confirm the client is still alive and responding
106  *
107  * Will result in pong being emitted
108  *
109  * @returns unique identifier for this request
110  * @since 5.39
111  */
112  quint32 ping(XdgShellSurfaceInterface *surface);
113 
114 Q_SIGNALS:
115  void surfaceCreated(KWayland::Server::XdgShellSurfaceInterface *surface);
116 
117  /**
118  * Emitted whenever a new popup got created.
119  *
120  * A popup only gets created in response to an action on the @p seat.
121  *
122  *
123  * @param surface The popup xdg shell surface which got created
124  * @param seat The seat on which an action triggered the popup
125  * @param serial The serial of the action on the seat
126  *
127  * XDGV5 only
128  * Use both xdgPopupCreated and XdgShellPopupInterface::grabbed to cover both XDGV5 and XDGV6
129  **/
130 
131  void popupCreated(KWayland::Server::XdgShellPopupInterface *surface, KWayland::Server::SeatInterface *seat, quint32 serial);
132 
133  /*
134  * Emitted whenever a new popup gets created.
135  *
136  * @param surface The popup xdg shell surface which got created
137  * @since 5.39
138  */
139  void xdgPopupCreated(KWayland::Server::XdgShellPopupInterface *surface);
140 
141  /*
142  * Emitted in response to a ping request
143  *
144  * @param serial unique identifier for the request
145  * @since 5.39
146  */
147  void pongReceived(quint32 serial);
148 
149  /*
150  * Emitted when the application takes more than expected
151  * to answer to a ping, this will always be emitted before
152  * eventuallt pingTimeout gets emitted
153  *
154  * @param serial unique identifier for the request
155  * @since 5.39
156  */
157  void pingDelayed(quint32 serial);
158 
159  /*
160  * Emitted when the application doesn't answer to a ping
161  * and the serve gave up on it
162  *
163  * @param serial unique identifier for the request
164  * @since 5.39
165  */
166  void pingTimeout(quint32 serial);
167 
168 protected:
169  class Private;
170  explicit XdgShellInterface(Private *d, QObject *parent = nullptr);
171 
172 private:
173  Private *d_func() const;
174 };
175 
176 /**
177  *
178  * @since 5.25
179  **/
180 class KWAYLANDSERVER_EXPORT XdgShellSurfaceInterface : public Resource
181 {
182  Q_OBJECT
183 public:
184  virtual ~XdgShellSurfaceInterface();
185 
186  /**
187  * @returns The interface version used by this XdgShellSurfaceInterface
188  **/
189  XdgShellInterfaceVersion interfaceVersion() const;
190 
191  /**
192  * States the Surface can be in
193  **/
194  enum class State {
195  /**
196  * The Surface is maximized.
197  **/
198  Maximized = 1 << 0,
199  /**
200  * The Surface is fullscreen.
201  **/
202  Fullscreen = 1 << 1,
203  /**
204  * The Surface is currently being resized by the Compositor.
205  **/
206  Resizing = 1 << 2,
207  /**
208  * The Surface is considered active. Does not imply keyboard focus.
209  **/
210  Activated = 1 << 3,
211  };
212  Q_DECLARE_FLAGS(States, State)
213 
214  /**
215  * Sends a configure event to the Surface.
216  * This tells the Surface the current @p states it is in and the @p size it should have.
217  * If @p size has width and height at @c 0, the Surface can choose the size.
218  *
219  * The Surface acknowledges the configure event with {@link configureAcknowledged}.
220  *
221  * @param states The states the surface is in
222  * @param size The requested size
223  * @returns The serial of the configure event
224  * @see configureAcknowledged
225  * @see isConfigurePending
226  **/
227  quint32 configure(States states, const QSize &size = QSize(0, 0));
228 
229  /**
230  * @returns @c true if there is a not yet acknowledged configure event.
231  * @see configure
232  * @see configureAcknowledged
233  **/
234  bool isConfigurePending() const;
235 
236  /**
237  * @return The SurfaceInterface this XdgSurfaceV5Interface got created for.
238  **/
239  SurfaceInterface *surface() const;
240 
241  /**
242  * @returns The title of this surface.
243  * @see titleChanged
244  **/
245  QString title() const;
246  QByteArray windowClass() const;
247 
248  /**
249  * @returns Whether this Surface is a transient for another Surface, that is it has a parent.
250  * @see transientFor
251  **/
252  bool isTransient() const;
253  /**
254  * @returns the parent surface if the surface is a transient for another surface
255  * @see isTransient
256  **/
257  QPointer<XdgShellSurfaceInterface> transientFor() const;
258 
259  /**
260  * Request the client to close the window.
261  **/
262  void close();
263 
264  /**
265  * @brief windowGeometry
266  * The geometry of the window within the buffer
267  *
268  * If invalid, the geometry of the buffer should be used instead
269  * @since 5.59
270  */
271  QRect windowGeometry() const;
272 
273  /**
274  * @returns The minimum size for the window specified by the client.
275  * @since 5.65
276  */
277  QSize minimumSize() const;
278 
279  /**
280  * @returns The maximum size for the window specified by the client.
281  * @since 5.65
282  */
283  QSize maximumSize() const;
284 
285 Q_SIGNALS:
286  /**
287  * Emitted whenever the title changes.
288  *
289  * @see title
290  **/
291  void titleChanged(const QString &);
292  /**
293  * Emitted whenever the window class changes.
294  *
295  * @see windowClass
296  **/
297  void windowClassChanged(const QByteArray &);
298  /**
299  * The surface requested a window move.
300  *
301  * @param seat The SeatInterface on which the surface requested the move
302  * @param serial The serial of the implicit mouse grab which triggered the move
303  **/
304  void moveRequested(KWayland::Server::SeatInterface *seat, quint32 serial);
305  /**
306  * The surface requested a window resize.
307  *
308  * @param seat The SeatInterface on which the surface requested the resize
309  * @param serial The serial of the implicit mouse grab which triggered the resize
310  * @param edges A hint which edges are involved in the resize
311  **/
312  void resizeRequested(KWayland::Server::SeatInterface *seat, quint32 serial, Qt::Edges edges);
313  void windowMenuRequested(KWayland::Server::SeatInterface *seat, quint32 serial, const QPoint &surfacePos);
314  /**
315  * The surface requested a change of maximized state.
316  * @param maximized Whether the window wants to be maximized
317  **/
318  void maximizedChanged(bool maximized);
319  /**
320  * The surface requested a change of fullscreen state
321  * @param fullscreen Whether the window wants to be fullscreen
322  * @param output An optional output hint on which the window wants to be fullscreen
323  **/
324  void fullscreenChanged(bool fullscreen, KWayland::Server::OutputInterface *output);
325  /**
326  * The surface requested to be minimized.
327  **/
328  void minimizeRequested();
329  /**
330  * A configure event with @p serial got acknowledged.
331  * @see configure
332  **/
333  void configureAcknowledged(quint32 serial);
334  /**
335  * Emitted whenever the parent surface changes.
336  * @see isTransient
337  * @see transientFor
338  **/
339  void transientForChanged();
340 
341  /**
342  * Emitted whenever the maximum size hint changes
343  * @since 5.39
344  */
345  void maxSizeChanged(const QSize &size);
346 
347  /**
348  * Emitted whenever the minimum size hint changes
349  * @since 5.39
350  */
351  void minSizeChanged(const QSize &size);
352 
353  /**
354  * @brief windowGeometryChanged
355  * @param windowGeometry the newly changed windowGeometry
356  * @since 5.59
357  */
358  void windowGeometryChanged(const QRect &windowGeometry);
359 
360 protected:
361  class Private;
362  explicit XdgShellSurfaceInterface(Private *p);
363 
364 private:
365  Private *d_func() const;
366  friend class GenericShellSurface<XdgShellSurfaceInterface>;
367 };
368 
369 /**
370  *
371  * @since 5.25
372  **/
373 class KWAYLANDSERVER_EXPORT XdgShellPopupInterface : public Resource
374 {
375  Q_OBJECT
376 public:
377  virtual ~XdgShellPopupInterface();
378 
379  /**
380  * @return The SurfaceInterface this XdgShellPopupInterface got created for.
381  **/
382  SurfaceInterface *surface() const;
383 
384  /*
385  * Ask the popup surface to configure itself for the given configuration.
386  *
387  * @arg rect. The position of the surface relative to the transient parent
388  * @since 5.39
389  */
390  quint32 configure(const QRect &rect);
391 
392  /**
393  * @returns the parent surface.
394  * @see transientOffset
395  **/
396  QPointer<SurfaceInterface> transientFor() const;
397 
398  /**
399  * The offset of the Surface in the coordinate system of the SurfaceInterface this surface is a transient for.
400  *
401  * For XDG V6 this returns the point on the anchorRect defined by the anchor edge.
402  *
403  * @returns offset in parent coordinate system.
404  * @see transientFor
405  **/
406  QPoint transientOffset() const;
407 
408  /**
409  * The size of the surface that is to be positioned.
410  *
411  * @since 5.39
412  */
413  QSize initialSize() const;
414 
415  /**
416  * The area this popup should be positioned around
417  * @since 5.39
418  */
419  QRect anchorRect() const;
420 
421  /**
422  * Which edge of the anchor should the popup be positioned around
423  * @since 5.39
424  */
425  Qt::Edges anchorEdge() const;
426 
427  /**
428  * An additional offset that should be applied to the popup from the anchor rect
429  *
430  * @since 5.39
431  */
432  QPoint anchorOffset() const;
433 
434  /**
435  * Specifies in what direction the popup should be positioned around the anchor
436  * i.e if the gravity is "bottom", then then the top of top of the popup will be at the anchor edge
437  * if the gravity is top, then the bottom of the popup will be at the anchor edge
438  *
439  * @since 5.39
440  */
441 
442  // DAVE left + right is illegal, so this is possible a useless return value? Maybe an enum with 9 entries left, topleft, top, ..
443  Qt::Edges gravity() const;
444 
445  /**
446  * Specifies how the compositor should position the popup if it does not fit in the requested position
447  * @since 5.39
448  */
449  PositionerConstraints constraintAdjustments() const;
450 
451  /**
452  * Dismiss this popup. This indicates to the client that it should destroy this popup.
453  * The Compositor can invoke this method when e.g. the user clicked outside the popup
454  * to dismiss it.
455  **/
456  void popupDone();
457 
458  /**
459  * @brief windowGeometryChanged
460  * @param windowGeometry the newly changed geometry of the window contents within the buffer
461  * @since 5.59
462  */
463  QRect windowGeometry() const;
464 
465 Q_SIGNALS:
466  /**
467  * A configure event with @p serial got acknowledged.
468  * Note: XdgV6 only
469  * @see configure
470  * @since 5.39
471  **/
472  void configureAcknowledged(quint32 serial);
473 
474  /**
475  * The client requested that this popup takes an explicit grab
476  *
477  * @param seat The seat on which an action triggered the popup
478  * @param serial The serial of the action on the seat
479  * @since 5.39
480  */
481  void grabRequested(KWayland::Server::SeatInterface *seat, quint32 serial);
482 
483  /**
484  * @brief windowGeometryChanged
485  * @param windowGeometry the newly changed windowGeometry
486  * @since 5.59
487  */
488  void windowGeometryChanged(const QRect &windowGeometry);
489 
490 protected:
491  class Private;
492  explicit XdgShellPopupInterface(Private *p);
493 
494 private:
495  friend class GenericShellSurface<XdgShellPopupInterface>;
496 
497  Private *d_func() const;
498 };
499 
500 Q_DECLARE_OPERATORS_FOR_FLAGS(PositionerConstraints)
501 
502 }
503 }
504 
505 Q_DECLARE_METATYPE(KWayland::Server::XdgShellSurfaceInterface *)
506 Q_DECLARE_METATYPE(KWayland::Server::XdgShellPopupInterface *)
509 
510 #endif
typedef Edges
Slide the popup on the Y axis until there is room.
Global for the wl_output interface.
Represents a Seat on the Wayland Display.
Invert the anchor and gravity on the Y axis.
Resource representing a wl_surface.
XdgShellInterfaceVersion
Enum describing the different InterfaceVersion encapsulated in this implementation.
Base class for all Globals.
Definition: global.h:46
Resize the popup in the Y axis.
Represents a bound Resource.
Definition: resource.h:31
Slide the popup on the X axis until there is room.
Invert the anchor and gravity on the X axis.
Resize the popup in the X axis.
PositionerConstraint
Flags describing how a popup should be reposition if constrained.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 22:51:11 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.