File indexing completed on 2024-04-07 11:03:26

0001 /*
0002     SPDX-FileCopyrightText: 2009 Marco Martin <notmart@gmail.com>
0003 
0004     SPDX-License-Identifier: LGPL-2.1-or-later
0005 */
0006 
0007 #ifndef KWINDOWEFFECTS_H
0008 #define KWINDOWEFFECTS_H
0009 
0010 #include "kwindowsystem_export.h"
0011 #include <optional>
0012 
0013 #include <QWidgetList> // for WId, etc.
0014 
0015 #include <QColor>
0016 #include <QRegion>
0017 #include <netwm_def.h>
0018 
0019 /**
0020  * Namespace for common standardized window effects
0021  */
0022 namespace KWindowEffects
0023 {
0024 enum Effect {
0025     Slide = 1,
0026 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
0027     PresentWindows KWINDOWSYSTEM_ENUMERATOR_DEPRECATED_VERSION(5, 82, "Check whether org.kde.KWin.PresentWindows d-bus service is registered") = 3,
0028     PresentWindowsGroup KWINDOWSYSTEM_ENUMERATOR_DEPRECATED_VERSION(5, 82, "Check whether org.kde.KWin.PresentWindows d-bus service is registered") = 4,
0029     HighlightWindows KWINDOWSYSTEM_ENUMERATOR_DEPRECATED_VERSION(5, 82, "Check whether org.kde.KWin.HighlightWindow d-bus service is registered") = 5,
0030 #endif
0031     BlurBehind = 7,
0032 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 67)
0033     Dashboard KWINDOWSYSTEM_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 67, "Support for dashboard windows in KWin was removed long time ago") = 8,
0034 #endif
0035     BackgroundContrast = 9,
0036 };
0037 
0038 enum SlideFromLocation {
0039     NoEdge = 0,
0040     TopEdge,
0041     RightEdge,
0042     BottomEdge,
0043     LeftEdge,
0044 };
0045 /**
0046  * @return if an atom property is available
0047  *
0048  * @param effect the effect we want to check
0049  */
0050 KWINDOWSYSTEM_EXPORT bool isEffectAvailable(Effect effect);
0051 
0052 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
0053 /**
0054  * Mark a window as sliding from screen edge
0055  *
0056  * @param id of the window on which we want to apply the effect
0057  * @param location edge of the screen from which we want the sliding effect.
0058  *               Desktop and Floating won't have effect.
0059  * @param offset distance in pixels from the screen edge defined by location
0060  *
0061  * @deprecated Since 5.82, Use slideWindow(QWindow) overload
0062  */
0063 KWINDOWSYSTEM_EXPORT
0064 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use slideWindow(QWindow) overload")
0065 void slideWindow(WId id, SlideFromLocation location, int offset = -1);
0066 #endif
0067 
0068 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 62)
0069 /**
0070  * Mark a window as sliding from screen edge
0071  * This is an overloaded member function provided for convenience
0072  *
0073  * @param widget QWidget corresponding to the top level window we want to animate
0074  * @param location edge of the screen from which we want the sliding effect.
0075  *               Desktop and Floating won't have effect.
0076  * @deprecated since 5.62, use slideWindow(widget->effectiveWinId(), location);
0077  */
0078 KWINDOWSYSTEM_EXPORT
0079 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 62, "Use KWindowEffects::slideWindow(WId, SlideFromLocation, int)")
0080 void slideWindow(QWidget *widget, SlideFromLocation location);
0081 #endif
0082 
0083 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 81)
0084 /**
0085  * @return dimension of all the windows passed as parameter
0086  *
0087  * @param ids all the windows we want the size
0088  * @deprecated since 5.81, fetch sizes through KWindowSystem instead
0089  */
0090 KWINDOWSYSTEM_EXPORT
0091 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 81, "Fetch sizes through KWindowSystem instead")
0092 QList<QSize> windowSizes(const QList<WId> &ids);
0093 #endif
0094 
0095 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
0096 /**
0097  * Activate the Present Windows effect for the given groups of windows.
0098  *
0099  * @param controller The window which is the controller of this effect. The property
0100  *                   will be set on this window. It will be removed by the effect
0101  * @param ids all the windows which should be presented.
0102  *
0103  * @deprecated Since 5.82, Use org.kde.KWin.PresentWindows d-bus api
0104  */
0105 KWINDOWSYSTEM_EXPORT
0106 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use org.kde.KWin.PresentWindows d-bus api")
0107 void presentWindows(WId controller, const QList<WId> &ids);
0108 #endif
0109 
0110 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
0111 /**
0112  * Activate the Present Windows effect for the windows of the given desktop.
0113  *
0114  * @param controller The window which is the controller of this effect. The property
0115  *                   will be set on this window. It will be removed by the effect
0116  * @param desktop The desktop whose windows should be presented. -1 for all desktops
0117  *
0118  * @deprecated Since 5.82, Use org.kde.KWin.PresentWindows d-bus api
0119  */
0120 KWINDOWSYSTEM_EXPORT
0121 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use org.kde.KWin.PresentWindows d-bus api")
0122 void presentWindows(WId controller, int desktop = NET::OnAllDesktops);
0123 #endif
0124 
0125 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
0126 /**
0127  * Highlight the selected windows, making all the others translucent
0128  *
0129  * @param controller The window which is the controller of this effect. The property
0130  *                   will be set on this window. It will be removed by the effect
0131  * @param ids all the windows which should be highlighted.
0132  *
0133  * @deprecated Since 5.82, Use org.kde.KWin.HighlightWindow d-bus api
0134  */
0135 KWINDOWSYSTEM_EXPORT
0136 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use org.kde.KWin.HighlightWindow d-bus api")
0137 void highlightWindows(WId controller, const QList<WId> &ids);
0138 #endif
0139 
0140 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
0141 /**
0142  * Instructs the window manager to blur the background
0143  * in the specified region behind the given window.
0144  * The given region will overwrite any previous blur-behind region.
0145  * Passing a null region will enable the blur effect for the whole window.
0146  * The region is relative to the top-left corner of the client area.
0147  *
0148  * If @a enable is @c false, blur will be disabled for the whole window
0149  * (@a region is ignored).
0150  *
0151  * Note that you will usually want to set the region to the shape of the window,
0152  * excluding any shadow or halo.
0153  *
0154  * @param window The window for which to enable the blur effect
0155  * @param enable Enable the effect if @c true, disable it if @c false
0156  * @param region The region within the window where the background will be blurred, specified in logical pixels
0157  *
0158  * @deprecated Since 5.82, use enableBlurBehind(QWindow) overload.
0159  */
0160 KWINDOWSYSTEM_EXPORT
0161 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use enableBlurBehind(QWindow) overload")
0162 void enableBlurBehind(WId window, bool enable = true, const QRegion &region = QRegion());
0163 #endif
0164 
0165 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 82)
0166 /**
0167  * Instructs the window manager to modify the color of the background
0168  * in the specified region behind the given window,
0169  * in order to improve the contrast and readability of any text
0170  * in the translucent window.
0171  * The given region will overwrite any previous backgroundcontrast region.
0172  * Passing a null region will enable the blur effect for the whole window.
0173  * The region is relative to the top-left corner of the client area.
0174  *
0175  * If @a enable is @c false, blur will be disabled for the whole window
0176  * (@a region is ignored).
0177  *
0178  * Note that you will usually want to set the region to the shape of the window,
0179  * excluding any shadow or halo.
0180  *
0181  * @param window The window for which to enable the background contrast effect
0182  * @param enable Enable the effect if @c true, disable it if @c false
0183  * @param brightness How to modify the area brightness: from 0 (make it black) to 2 (make it white), 1 leaves it unchanged
0184  * @param region The region within the window where the background will be modified, specified in logical pixels
0185  *
0186  * @deprecated Since 5.82, use enableBackgroundContrast(QWindow) overload.
0187  */
0188 KWINDOWSYSTEM_EXPORT
0189 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 82, "Use enableBackgroundContrast(QWindow) overload")
0190 void enableBackgroundContrast(WId window, bool enable = true, qreal contrast = 1, qreal intensity = 1, qreal saturation = 1, const QRegion &region = QRegion());
0191 #endif
0192 
0193 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 67)
0194 /**
0195  * Instructs the window manager to handle the given window as dashboard window as
0196  * Dashboard windows should be handled differently and may have special effects
0197  * applied to them.
0198  *
0199  * @param window The window for which to enable the blur effect
0200  * @deprecated since 5.67, support for dashboard windows was removed
0201  */
0202 KWINDOWSYSTEM_EXPORT
0203 KWINDOWSYSTEM_DEPRECATED_VERSION(5, 67, "Support for dashboard windows was removed")
0204 void markAsDashboard(WId window);
0205 #endif
0206 
0207 /**
0208  * Instructs the window manager to blur the background
0209  * in the specified region behind the given window.
0210  * The given region will overwrite any previous blur-behind region.
0211  * Passing a null region will enable the blur effect for the whole window.
0212  * The region is relative to the top-left corner of the client area.
0213  *
0214  * If @a enable is @c false, blur will be disabled for the whole window
0215  * (@a region is ignored).
0216  *
0217  * Note that you will usually want to set the region to the shape of the window,
0218  * excluding any shadow or halo.
0219  *
0220  * @param window The window for which to enable the blur effect
0221  * @param enable Enable the effect if @c true, disable it if @c false
0222  * @param region The region within the window where the background will be blurred, specified in logical pixels
0223  *
0224  * @since 5.82
0225  */
0226 KWINDOWSYSTEM_EXPORT void enableBlurBehind(QWindow *window, bool enable = true, const QRegion &region = QRegion());
0227 
0228 /**
0229  * Instructs the window manager to modify the color of the background
0230  * in the specified region behind the given window,
0231  * in order to improve the contrast and readability of any text
0232  * in the translucent window.
0233  * The given region will overwrite any previous backgroundcontrast region.
0234  * Passing a null region will enable the blur effect for the whole window.
0235  * The region is relative to the top-left corner of the client area.
0236  *
0237  * If @a enable is @c false, blur will be disabled for the whole window
0238  * (@a region is ignored).
0239  *
0240  * Note that you will usually want to set the region to the shape of the window,
0241  * excluding any shadow or halo.
0242  *
0243  * @param window The window for which to enable the background contrast effect
0244  * @param enable Enable the effect if @c true, disable it if @c false
0245  * @param brightness How to modify the area brightness: from 0 (make it black) to 2 (make it white), 1 leaves it unchanged
0246  * @param region The region within the window where the background will be modified, specified in logical pixels
0247  *
0248  * @since 5.82
0249  */
0250 KWINDOWSYSTEM_EXPORT void
0251 enableBackgroundContrast(QWindow *window, bool enable = true, qreal contrast = 1, qreal intensity = 1, qreal saturation = 1, const QRegion &region = QRegion());
0252 
0253 /**
0254  * Instructs the window manager to modify the color of the background
0255  * in the specified region behind the given window,
0256  * in order to improve the contrast and readability of any text
0257  * in the translucent window.
0258  * The given region will overwrite any previous backgroundcontrast region.
0259  * Passing a null region will enable the frost effect for the whole window.
0260  * The region is relative to the top-left corner of the client area.
0261  *
0262  * If @a color is null, frost will be disabled for the whole window
0263  * (@a region is ignored).
0264  *
0265  * Note that you will usually want to set the region to the shape of the window,
0266  * excluding any shadow or halo.
0267  *
0268  * @param window The window for which to enable the background frost effect
0269  * @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
0270  * background colour
0271  * @param region The region within the window where the background will be modified, specified in logical pixels
0272  *
0273  * @since 5.86
0274  */
0275 KWINDOWSYSTEM_EXPORT void setBackgroundFrost(QWindow *window, QColor frostColor, const QRegion &region = QRegion());
0276 
0277 /**
0278  * Mark a window as sliding from screen edge
0279  *
0280  * @param id of the window on which we want to apply the effect
0281  * @param location edge of the screen from which we want the sliding effect.
0282  *               Desktop and Floating won't have effect.
0283  * @param offset distance in pixels from the screen edge defined by location
0284  *
0285  * @since 5.82
0286  */
0287 KWINDOWSYSTEM_EXPORT void slideWindow(QWindow *window, SlideFromLocation location, int offset = -1);
0288 }
0289 
0290 #endif