1/*
2 SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org>
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
14struct wl_subsurface;
15
16namespace KWayland
17{
18namespace Client
19{
20class 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 **/
40class KWAYLANDCLIENT_EXPORT SubSurface : public QObject
41{
42 Q_OBJECT
43public:
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
169private:
170 class Private;
171 QScopedPointer<Private> d;
172};
173
174}
175}
176
177#endif
178

source code of kwayland/src/client/subsurface.h