KWindowSystem

kwindowshadow.h
1 /*
2  SPDX-FileCopyrightText: 2019 Vlad Zahorodnii <[email protected]>
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  * The KWindowShadowTile class provides a platform-indendent shadow tile representation.
22  */
23 class KWINDOWSYSTEM_EXPORT KWindowShadowTile
24 {
25 public:
27 
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 
59 private:
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  */
79 class KWINDOWSYSTEM_EXPORT KWindowShadow : public QObject
80 {
81  Q_OBJECT
82 
83 public:
84  explicit KWindowShadow(QObject *parent = nullptr);
85  ~KWindowShadow();
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 
221 private:
223 };
224 
225 #endif // KWINDOWSHADOW_H
The KWindowShadow class represents a drop-shadow that is drawn by the compositor. ...
Definition: kwindowshadow.h:79
The KWindowShadowTile class provides a platform-indendent shadow tile representation.
Definition: kwindowshadow.h:23
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Oct 21 2021 22:41:51 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.