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 | |
17 | class KWindowShadowPrivate; |
18 | class KWindowShadowTilePrivate; |
19 | |
20 | /*! |
21 | * \class KWindowShadowTile |
22 | * \inmodule KWindowSystem |
23 | * \brief The KWindowShadowTile class provides a platform-indendent shadow tile representation. |
24 | */ |
25 | class KWINDOWSYSTEM_EXPORT KWindowShadowTile |
26 | { |
27 | public: |
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 | |
67 | private: |
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 | */ |
89 | class KWINDOWSYSTEM_EXPORT KWindowShadow : public QObject |
90 | { |
91 | Q_OBJECT |
92 | |
93 | public: |
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 | |
231 | private: |
232 | QScopedPointer<KWindowShadowPrivate> d; |
233 | }; |
234 | |
235 | #endif // KWINDOWSHADOW_H |
236 | |