1/*
2 SPDX-FileCopyrightText: 2019 Vlad Zahorodnii <vlad.zahorodnii@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-or-later
5*/
6
7#ifndef KWINDOWSHADOW_H
8#define KWINDOWSHADOW_H
9
10#include "kwindowsystem_export.h"
11
12#include <QImage>
13#include <QMargins>
14#include <QSharedPointer>
15#include <QWindow>
16
17class KWindowShadowPrivate;
18class KWindowShadowTilePrivate;
19
20/**
21 * The KWindowShadowTile class provides a platform-indendent shadow tile representation.
22 */
23class KWINDOWSYSTEM_EXPORT KWindowShadowTile
24{
25public:
26 using Ptr = QSharedPointer<KWindowShadowTile>;
27
28 KWindowShadowTile();
29 ~KWindowShadowTile();
30
31 /**
32 * Returns the image stored in the KWindowShadowTile.
33 */
34 QImage image() const;
35
36 /**
37 * Sets the image on the KWindowShadowTile.
38 *
39 * Notice that once the native platform resources have been allocated for the tile, you are
40 * not allowed to change the image. In order to do so, you need to create a new tile.
41 */
42 void setImage(const QImage &image);
43
44 /**
45 * Returns @c true if the platform resources associated with the tile have been allocated.
46 */
47 bool isCreated() const;
48
49 /**
50 * Allocates the native platform resources associated with the KWindowShadowTile.
51 *
52 * Normally it should not be necessary to call this method as KWindowShadow will implicitly
53 * call create() on your behalf.
54 *
55 * Returns @c true if the creation succeeded, otherwise returns @c false.
56 */
57 bool create();
58
59private:
60 QScopedPointer<KWindowShadowTilePrivate> d;
61
62 friend class KWindowShadowTilePrivate;
63};
64
65/**
66 * The KWindowShadow class represents a drop-shadow that is drawn by the compositor.
67 *
68 * The KWindowShadow is composed of multiple tiles. The top left tile, the top right tile, the bottom
69 * left tile, and the bottom right tile are rendered as they are. The top tile and the bottom tile are
70 * stretched in x direction; the left tile and the right tile are stretched in y direction. Several
71 * KWindowShadow objects can share shadow tiles to reduce memory usage. You have to specify padding()
72 * along the shadow tiles. The padding values indicate how much the KWindowShadow sticks outside the
73 * decorated window.
74 *
75 * Once the KWindowShadow is created, you're not allowed to attach or detach any shadow tiles, change
76 * padding(), or change window(). In order to do so, you have to destroy() the shadow first, update
77 * relevant properties, and create() the shadow again.
78 */
79class KWINDOWSYSTEM_EXPORT KWindowShadow : public QObject
80{
81 Q_OBJECT
82
83public:
84 explicit KWindowShadow(QObject *parent = nullptr);
85 ~KWindowShadow() override;
86
87 /**
88 * Returns the left tile attached to the KWindowShadow.
89 */
90 KWindowShadowTile::Ptr leftTile() const;
91
92 /**
93 * Attaches the left @p tile to the KWindowShadow.
94 */
95 void setLeftTile(KWindowShadowTile::Ptr tile);
96
97 /**
98 * Returns the top-left tile attached to the KWindowShadow.
99 */
100 KWindowShadowTile::Ptr topLeftTile() const;
101
102 /**
103 * Attaches the top-left @p tile to the KWindowShadow.
104 */
105 void setTopLeftTile(KWindowShadowTile::Ptr tile);
106
107 /**
108 * Returns the top tile attached to the KWindowShadow.
109 */
110 KWindowShadowTile::Ptr topTile() const;
111
112 /**
113 * Attaches the top @p tile to the KWindowShadow.
114 */
115 void setTopTile(KWindowShadowTile::Ptr tile);
116
117 /**
118 * Returns the top-right tile attached to the KWindowShadow.
119 */
120 KWindowShadowTile::Ptr topRightTile() const;
121
122 /**
123 * Attaches the top-right @p tile to the KWindowShadow.
124 */
125 void setTopRightTile(KWindowShadowTile::Ptr tile);
126
127 /**
128 * Returns the right tile attached to the KWindowShadow.
129 */
130 KWindowShadowTile::Ptr rightTile() const;
131
132 /**
133 * Attaches the right @p tile to the KWindowShadow.
134 */
135 void setRightTile(KWindowShadowTile::Ptr tile);
136
137 /**
138 * Returns the bottom-right tile attached to the KWindowShadow.
139 */
140 KWindowShadowTile::Ptr bottomRightTile() const;
141
142 /**
143 * Attaches the bottom-right tile to the KWindowShadow.
144 */
145 void setBottomRightTile(KWindowShadowTile::Ptr tile);
146
147 /**
148 * Returns the bottom tile attached to the KWindowShadow.
149 */
150 KWindowShadowTile::Ptr bottomTile() const;
151
152 /**
153 * Attaches the bottom @p tile to the KWindowShadow.
154 */
155 void setBottomTile(KWindowShadowTile::Ptr tile);
156
157 /**
158 * Returns the bottom-left tile attached to the KWindowShadow.
159 */
160 KWindowShadowTile::Ptr bottomLeftTile() const;
161
162 /**
163 * Attaches the bottom-left @p tile to the KWindowShadow.
164 */
165 void setBottomLeftTile(KWindowShadowTile::Ptr tile);
166
167 /**
168 * Returns the padding of the KWindowShadow.
169 *
170 * The padding values specify the visible extents of the shadow. The top left tile is rendered
171 * with an offset of -padding().left() and -padding().top().
172 */
173 QMargins padding() const;
174
175 /**
176 * Sets the padding on the KWindowShadow.
177 *
178 * If the padding values are smaller than the sizes of the shadow tiles, then the shadow will
179 * overlap with the window() and will be rendered behind window(). E.g. if all padding values
180 * are set to 0, then the shadow will be completely occluded by the window().
181 */
182 void setPadding(const QMargins &padding);
183
184 /**
185 * Returns the window behind which the KWindowShadow will be rendered.
186 */
187 QWindow *window() const;
188
189 /**
190 * Sets the window behind which the KWindowShadow will be rendered.
191 *
192 * Note that the KWindowShadow does not track the platform surface. If for whatever reason the
193 * native platform surface is deleted and then created, you must to destroy() the shadow and
194 * create() it again yourself.
195 */
196 void setWindow(QWindow *window);
197
198 /**
199 * Returns @c true if the platform resources associated with the shadow have been allocated.
200 */
201 bool isCreated() const;
202
203 /**
204 * Allocates the platform resources associated with the KWindowShadow.
205 *
206 * Once the native platform resources have been allocated, you're not allowed to attach or
207 * detach shadow tiles, change the padding or the target window. If you want to do so, you
208 * must destroy() the shadow, change relevant attributes and call create() again.
209 *
210 * Returns @c true if the creation succeeded, otherwise returns @c false.
211 */
212 bool create();
213
214 /**
215 * Releases the platform resources associated with the KWindowShadow.
216 *
217 * Calling destroy() after window() had been destroyed will result in a no-op.
218 */
219 void destroy();
220
221private:
222 QScopedPointer<KWindowShadowPrivate> d;
223};
224
225#endif // KWINDOWSHADOW_H
226

source code of kwindowsystem/src/kwindowshadow.h