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

source code of kwindowsystem/src/kwindowshadow.h