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

KDE's Doxygen guidelines are available online.