KWindowSystem

kwindoweffects.h
1 /*
2  SPDX-FileCopyrightText: 2009 Marco Martin <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-or-later
5 */
6 
7 #ifndef KWINDOWEFFECTS_H
8 #define KWINDOWEFFECTS_H
9 
10 #include "kwindowsystem_export.h"
11 #include <optional>
12 
13 #include <QWidgetList> // for WId, etc.
14 
15 #include <QColor>
16 #include <QRegion>
17 #include <netwm_def.h>
18 
19 /**
20  * Namespace for common standardized window effects
21  */
22 namespace KWindowEffects
23 {
24 enum Effect {
25  Slide = 1,
26 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
27  PresentWindows KWINDOWSYSTEM_ENUMERATOR_DEPRECATED_VERSION(5, 82, "Check whether org.kde.KWin.PresentWindows d-bus service is registered") = 3,
28  PresentWindowsGroup KWINDOWSYSTEM_ENUMERATOR_DEPRECATED_VERSION(5, 82, "Check whether org.kde.KWin.PresentWindows d-bus service is registered") = 4,
29  HighlightWindows KWINDOWSYSTEM_ENUMERATOR_DEPRECATED_VERSION(5, 82, "Check whether org.kde.KWin.HighlightWindow d-bus service is registered") = 5,
30 #endif
31  BlurBehind = 7,
32 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 67)
33  Dashboard KWINDOWSYSTEM_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 67, "Support for dashboard windows in KWin was removed long time ago") = 8,
34 #endif
35  BackgroundContrast = 9,
36 };
37 
38 enum SlideFromLocation {
39  NoEdge = 0,
40  TopEdge,
41  RightEdge,
42  BottomEdge,
43  LeftEdge,
44 };
45 /**
46  * @return if an atom property is available
47  *
48  * @param effect the effect we want to check
49  */
50 KWINDOWSYSTEM_EXPORT bool isEffectAvailable(Effect effect);
51 
52 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
53 /**
54  * Mark a window as sliding from screen edge
55  *
56  * @param id of the window on which we want to apply the effect
57  * @param location edge of the screen from which we want the sliding effect.
58  * Desktop and Floating won't have effect.
59  * @param offset distance in pixels from the screen edge defined by location
60  *
61  * @deprecated Since 5.82, Use slideWindow(QWindow) overload
62  */
63 KWINDOWSYSTEM_EXPORT
64 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use slideWindow(QWindow) overload")
65 void slideWindow(WId id, SlideFromLocation location, int offset = -1);
66 #endif
67 
68 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 62)
69 /**
70  * Mark a window as sliding from screen edge
71  * This is an overloaded member function provided for convenience
72  *
73  * @param widget QWidget corresponding to the top level window we want to animate
74  * @param location edge of the screen from which we want the sliding effect.
75  * Desktop and Floating won't have effect.
76  * @deprecated since 5.62, use slideWindow(widget->effectiveWinId(), location);
77  */
78 KWINDOWSYSTEM_EXPORT
79 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 62, "Use KWindowEffects::slideWindow(WId, SlideFromLocation, int)")
80 void slideWindow(QWidget *widget, SlideFromLocation location);
81 #endif
82 
83 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 81)
84 /**
85  * @return dimension of all the windows passed as parameter
86  *
87  * @param ids all the windows we want the size
88  * @deprecated since 5.81, fetch sizes through KWindowSystem instead
89  */
90 KWINDOWSYSTEM_EXPORT
91 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 81, "Fetch sizes through KWindowSystem instead")
92 QList<QSize> windowSizes(const QList<WId> &ids);
93 #endif
94 
95 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
96 /**
97  * Activate the Present Windows effect for the given groups of windows.
98  *
99  * @param controller The window which is the controller of this effect. The property
100  * will be set on this window. It will be removed by the effect
101  * @param ids all the windows which should be presented.
102  *
103  * @deprecated Since 5.82, Use org.kde.KWin.PresentWindows d-bus api
104  */
105 KWINDOWSYSTEM_EXPORT
106 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use org.kde.KWin.PresentWindows d-bus api")
107 void presentWindows(WId controller, const QList<WId> &ids);
108 #endif
109 
110 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
111 /**
112  * Activate the Present Windows effect for the windows of the given desktop.
113  *
114  * @param controller The window which is the controller of this effect. The property
115  * will be set on this window. It will be removed by the effect
116  * @param desktop The desktop whose windows should be presented. -1 for all desktops
117  *
118  * @deprecated Since 5.82, Use org.kde.KWin.PresentWindows d-bus api
119  */
120 KWINDOWSYSTEM_EXPORT
121 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use org.kde.KWin.PresentWindows d-bus api")
122 void presentWindows(WId controller, int desktop = NET::OnAllDesktops);
123 #endif
124 
125 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
126 /**
127  * Highlight the selected windows, making all the others translucent
128  *
129  * @param controller The window which is the controller of this effect. The property
130  * will be set on this window. It will be removed by the effect
131  * @param ids all the windows which should be highlighted.
132  *
133  * @deprecated Since 5.82, Use org.kde.KWin.HighlightWindow d-bus api
134  */
135 KWINDOWSYSTEM_EXPORT
136 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use org.kde.KWin.HighlightWindow d-bus api")
137 void highlightWindows(WId controller, const QList<WId> &ids);
138 #endif
139 
140 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
141 /**
142  * Instructs the window manager to blur the background
143  * in the specified region behind the given window.
144  * The given region will overwrite any previous blur-behind region.
145  * Passing a null region will enable the blur effect for the whole window.
146  * The region is relative to the top-left corner of the client area.
147  *
148  * If @a enable is @c false, blur will be disabled for the whole window
149  * (@a region is ignored).
150  *
151  * Note that you will usually want to set the region to the shape of the window,
152  * excluding any shadow or halo.
153  *
154  * @param window The window for which to enable the blur effect
155  * @param enable Enable the effect if @c true, disable it if @c false
156  * @param region The region within the window where the background will be blurred, specified in logical pixels
157  *
158  * @deprecated Since 5.82, use enableBlurBehind(QWindow) overload.
159  */
160 KWINDOWSYSTEM_EXPORT
161 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use enableBlurBehind(QWindow) overload")
162 void enableBlurBehind(WId window, bool enable = true, const QRegion &region = QRegion());
163 #endif
164 
165 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
166 /**
167  * Instructs the window manager to modify the color of the background
168  * in the specified region behind the given window,
169  * in order to improve the contrast and readability of any text
170  * in the translucent window.
171  * The given region will overwrite any previous backgroundcontrast region.
172  * Passing a null region will enable the blur effect for the whole window.
173  * The region is relative to the top-left corner of the client area.
174  *
175  * If @a enable is @c false, blur will be disabled for the whole window
176  * (@a region is ignored).
177  *
178  * Note that you will usually want to set the region to the shape of the window,
179  * excluding any shadow or halo.
180  *
181  * @param window The window for which to enable the background contrast effect
182  * @param enable Enable the effect if @c true, disable it if @c false
183  * @param brightness How to modify the area brightness: from 0 (make it black) to 2 (make it white), 1 leaves it unchanged
184  * @param region The region within the window where the background will be modified, specified in logical pixels
185  *
186  * @deprecated Since 5.82, use enableBackgroundContrast(QWindow) overload.
187  */
188 KWINDOWSYSTEM_EXPORT
189 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use enableBackgroundContrast(QWindow) overload")
190 void enableBackgroundContrast(WId window, bool enable = true, qreal contrast = 1, qreal intensity = 1, qreal saturation = 1, const QRegion &region = QRegion());
191 #endif
192 
193 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 67)
194 /**
195  * Instructs the window manager to handle the given window as dashboard window as
196  * Dashboard windows should be handled differently and may have special effects
197  * applied to them.
198  *
199  * @param window The window for which to enable the blur effect
200  * @deprecated since 5.67, support for dashboard windows was removed
201  */
202 KWINDOWSYSTEM_EXPORT
203 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 67, "Support for dashboard windows was removed")
204 void markAsDashboard(WId window);
205 #endif
206 
207 /**
208  * Instructs the window manager to blur the background
209  * in the specified region behind the given window.
210  * The given region will overwrite any previous blur-behind region.
211  * Passing a null region will enable the blur effect for the whole window.
212  * The region is relative to the top-left corner of the client area.
213  *
214  * If @a enable is @c false, blur will be disabled for the whole window
215  * (@a region is ignored).
216  *
217  * Note that you will usually want to set the region to the shape of the window,
218  * excluding any shadow or halo.
219  *
220  * @param window The window for which to enable the blur effect
221  * @param enable Enable the effect if @c true, disable it if @c false
222  * @param region The region within the window where the background will be blurred, specified in logical pixels
223  *
224  * @since 5.82
225  */
226 KWINDOWSYSTEM_EXPORT void enableBlurBehind(QWindow *window, bool enable = true, const QRegion &region = QRegion());
227 
228 /**
229  * Instructs the window manager to modify the color of the background
230  * in the specified region behind the given window,
231  * in order to improve the contrast and readability of any text
232  * in the translucent window.
233  * The given region will overwrite any previous backgroundcontrast region.
234  * Passing a null region will enable the blur effect for the whole window.
235  * The region is relative to the top-left corner of the client area.
236  *
237  * If @a enable is @c false, blur will be disabled for the whole window
238  * (@a region is ignored).
239  *
240  * Note that you will usually want to set the region to the shape of the window,
241  * excluding any shadow or halo.
242  *
243  * @param window The window for which to enable the background contrast effect
244  * @param enable Enable the effect if @c true, disable it if @c false
245  * @param brightness How to modify the area brightness: from 0 (make it black) to 2 (make it white), 1 leaves it unchanged
246  * @param region The region within the window where the background will be modified, specified in logical pixels
247  *
248  * @since 5.82
249  */
250 KWINDOWSYSTEM_EXPORT void
251 enableBackgroundContrast(QWindow *window, bool enable = true, qreal contrast = 1, qreal intensity = 1, qreal saturation = 1, const QRegion &region = QRegion());
252 
253 /**
254  * Instructs the window manager to modify the color of the background
255  * in the specified region behind the given window,
256  * in order to improve the contrast and readability of any text
257  * in the translucent window.
258  * The given region will overwrite any previous backgroundcontrast region.
259  * Passing a null region will enable the frost effect for the whole window.
260  * The region is relative to the top-left corner of the client area.
261  *
262  * If @a color is null, frost will be disabled for the whole window
263  * (@a region is ignored).
264  *
265  * Note that you will usually want to set the region to the shape of the window,
266  * excluding any shadow or halo.
267  *
268  * @param window The window for which to enable the background frost effect
269  * @param frostColor The color to use as an anchor point for adjusting colors of windows behind the window; usually a translucent version of the window's
270  * background colour
271  * @param region The region within the window where the background will be modified, specified in logical pixels
272  *
273  * @since 5.86
274  */
275 KWINDOWSYSTEM_EXPORT void setBackgroundFrost(QWindow *window, QColor frostColor, const QRegion &region = QRegion());
276 
277 /**
278  * Mark a window as sliding from screen edge
279  *
280  * @param id of the window on which we want to apply the effect
281  * @param location edge of the screen from which we want the sliding effect.
282  * Desktop and Floating won't have effect.
283  * @param offset distance in pixels from the screen edge defined by location
284  *
285  * @since 5.82
286  */
287 KWINDOWSYSTEM_EXPORT void slideWindow(QWindow *window, SlideFromLocation location, int offset = -1);
288 }
289 
290 #endif
void markAsDashboard(WId window)
Instructs the window manager to handle the given window as dashboard window as Dashboard windows shou...
QList< QSize > windowSizes(const QList< WId > &ids)
void enableBlurBehind(WId window, bool enable, const QRegion &region)
Instructs the window manager to blur the background in the specified region behind the given window...
bool isEffectAvailable(Effect effect)
void setBackgroundFrost(QWindow *window, QColor frostColor, const QRegion &region)
Instructs the window manager to modify the color of the background in the specified region behind the...
void slideWindow(QWindow *window, SlideFromLocation location, int offset)
Mark a window as sliding from screen edge.
void presentWindows(WId controller, const QList< WId > &ids)
Activate the Present Windows effect for the given groups of windows.
Base namespace class.
Definition: netwm_def.h:334
Namespace for common standardized window effects.
void highlightWindows(WId controller, const QList< WId > &ids)
Highlight the selected windows, making all the others translucent.
void enableBackgroundContrast(WId window, bool enable, qreal contrast, qreal intensity, qreal saturation, const QRegion &region)
Instructs the window manager to modify the color of the background in the specified region behind the...
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Oct 15 2021 22:41:50 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.