1 /* 2 SPDX-FileCopyrightText: 2009 Marco Martin <notmart@gmail.com> 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 ®ion = 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 ®ion = 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 ®ion = 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 ®ion = 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 ®ion = 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 291