KWayland

subsurface.h
1 /*
2  SPDX-FileCopyrightText: 2014 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 WAYLAND_SUBSURFACE_H
7 #define WAYLAND_SUBSURFACE_H
8 
9 #include <QObject>
10 #include <QPointer>
11 
12 #include "KWayland/Client/kwaylandclient_export.h"
13 
14 struct wl_subsurface;
15 
16 namespace KWayland
17 {
18 namespace Client
19 {
20 class Surface;
21 
22 /**
23  * @short Wrapper for the wl_subsurface interface.
24  *
25  * This class is a convenient wrapper for the wl_subsurface interface.
26  * To create a SubSurface call SubCompositor::createSubSurface.
27  *
28  * A SubSurface is bound to a Surface and has a parent Surface.
29  * A SubSurface can only be created for a Surface not already used in onther way,
30  * e.g. as a ShellSurface.
31  *
32  * The SubSurface has a position in local coordinates to the parent Surface.
33  * Please note that changing the position is a double buffered state and is only
34  * applied once the parent surface is committed. The same applies for manipulating
35  * the stacking order of the SubSurface's siblings.
36  *
37  * @see SubCompositor
38  * @see Surface
39  **/
40 class KWAYLANDCLIENT_EXPORT SubSurface : public QObject
41 {
42  Q_OBJECT
43 public:
44  explicit SubSurface(QPointer<Surface> surface, QPointer<Surface> parentSurface, QObject *parent = nullptr);
45  ~SubSurface() override;
46 
47  /**
48  * @returns @c true if managing a wl_subsurface.
49  **/
50  bool isValid() const;
51  /**
52  * Setup this SubSurface to manage the @p subsurface.
53  * When using SubCompositor::createSubSurface there is no need to call this
54  * method.
55  **/
56  void setup(wl_subsurface *subsurface);
57  /**
58  * Releases the wl_subsurface interface.
59  * After the interface has been released the SubSurface instance is no
60  * longer valid and can be setup with another wl_subsurface interface.
61  **/
62  void release();
63  /**
64  * Destroys the data held by this SubSurface.
65  * This method is supposed to be used when the connection to the Wayland
66  * server goes away. If the connection is not valid anymore, it's not
67  * possible to call release anymore as that calls into the Wayland
68  * connection and the call would fail. This method cleans up the data, so
69  * that the instance can be deleted or set up to a new wl_subsurface interface
70  * once there is a new connection available.
71  *
72  * @see release
73  **/
74  void destroy();
75 
76  /**
77  * Operation Mode on how the Surface's commit should behave.
78  **/
79  enum class Mode {
80  Synchronized,
81  Desynchronized,
82  };
83 
84  /**
85  * Sets the operation mode to @p mode.
86  * Initially a SubSurface is in Synchronized Mode.
87  **/
88  void setMode(Mode mode);
89  Mode mode() const;
90 
91  /**
92  * Sets the position in relative coordinates to the parent surface to @p pos.
93  *
94  * The change is only applied after the parent Surface got committed.
95  **/
96  void setPosition(const QPoint &pos);
97  QPoint position() const;
98 
99  /**
100  * Raises this SubSurface above all siblings.
101  * This is the same as calling placeAbove with the parent surface
102  * as argument.
103  *
104  * The change is only applied after the parent surface got committed.
105  * @see placeAbove
106  **/
107  void raise();
108  /**
109  * Places the SubSurface above the @p sibling.
110  *
111  * The change is only applied after the parent surface got committed.
112  * @param sibling The SubSurface on top of which this SubSurface should be placed
113  **/
114  void placeAbove(QPointer<SubSurface> sibling);
115  /**
116  * Places the SubSurface above the @p referenceSurface.
117  *
118  * In case @p referenceSurface is the parent surface this SubSurface is
119  * raised to the top of the stacking order. Otherwise it is put directly
120  * above the @p referenceSurface in the stacking order.
121  *
122  * The change is only applied after the parent surface got committed.
123  * @param referenceSurface Either a sibling or parent Surface
124  **/
125  void placeAbove(QPointer<Surface> referenceSurface);
126 
127  /**
128  * Lowers this SubSurface below all siblings.
129  * This is the same as calling placeBelow with the parent surface
130  * as argument.
131  *
132  * The change is only applied after the parent surface got committed.
133  * @see placeBelow
134  **/
135  void lower();
136  /**
137  * Places the SubSurface below the @p sibling.
138  *
139  * The change is only applied after the parent surface got committed.
140  * @param sibling The SubSurface under which the SubSurface should be put
141  **/
142  void placeBelow(QPointer<SubSurface> sibling);
143  /**
144  * Places the SubSurface below the @p referenceSurface.
145  *
146  * In case @p referenceSurface is the parent surface this SubSurface is
147  * lowered to the bottom of the stacking order. Otherwise it is put directly
148  * below the @p referenceSurface in the stacking order.
149  *
150  * The change is only applied after the parent surface got committed.
151  * @param referenceSurface Either a sibling or parent Surface
152  **/
153  void placeBelow(QPointer<Surface> referenceSurface);
154 
155  /**
156  * @returns The Surface for which this SubSurface got created.
157  **/
158  QPointer<Surface> surface() const;
159  /**
160  * @returns The parent Surface of this SubSurface.
161  **/
162  QPointer<Surface> parentSurface() const;
163 
164  static QPointer<SubSurface> get(wl_subsurface *native);
165 
166  operator wl_subsurface *();
167  operator wl_subsurface *() const;
168 
169 private:
170  class Private;
172 };
173 
174 }
175 }
176 
177 #endif
virtual void release(quint64 objid)
Wrapper for the wl_subsurface interface.
Definition: subsurface.h:40
Mode
Operation Mode on how the Surface's commit should behave.
Definition: subsurface.h:79
virtual QVariant get(ScriptableExtension *callerPrincipal, quint64 objId, const QString &propName)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Mar 26 2023 03:55:52 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.