File indexing completed on 2024-05-19 15:21:18

0001 /*
0002     SPDX-FileCopyrightText: 2019 Vlad Zahorodnii <vlad.zahorodnii@kde.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.1-or-later
0005 */
0006 
0007 #ifndef KWINDOWSHADOW_H
0008 #define KWINDOWSHADOW_H
0009 
0010 #include "kwindowsystem_export.h"
0011 
0012 #include <QImage>
0013 #include <QMargins>
0014 #include <QSharedPointer>
0015 #include <QWindow>
0016 
0017 class KWindowShadowPrivate;
0018 class KWindowShadowTilePrivate;
0019 
0020 /**
0021  * The KWindowShadowTile class provides a platform-indendent shadow tile representation.
0022  */
0023 class KWINDOWSYSTEM_EXPORT KWindowShadowTile
0024 {
0025 public:
0026     using Ptr = QSharedPointer<KWindowShadowTile>;
0027 
0028     KWindowShadowTile();
0029     ~KWindowShadowTile();
0030 
0031     /**
0032      * Returns the image stored in the KWindowShadowTile.
0033      */
0034     QImage image() const;
0035 
0036     /**
0037      * Sets the image on the KWindowShadowTile.
0038      *
0039      * Notice that once the native platform resources have been allocated for the tile, you are
0040      * not allowed to change the image. In order to do so, you need to create a new tile.
0041      */
0042     void setImage(const QImage &image);
0043 
0044     /**
0045      * Returns @c true if the platform resources associated with the tile have been allocated.
0046      */
0047     bool isCreated() const;
0048 
0049     /**
0050      * Allocates the native platform resources associated with the KWindowShadowTile.
0051      *
0052      * Normally it should not be necessary to call this method as KWindowShadow will implicitly
0053      * call create() on your behalf.
0054      *
0055      * Returns @c true if the creation succeeded, otherwise returns @c false.
0056      */
0057     bool create();
0058 
0059 private:
0060     QScopedPointer<KWindowShadowTilePrivate> d;
0061 
0062     friend class KWindowShadowTilePrivate;
0063 };
0064 
0065 /**
0066  * The KWindowShadow class represents a drop-shadow that is drawn by the compositor.
0067  *
0068  * The KWindowShadow is composed of multiple tiles. The top left tile, the top right tile, the bottom
0069  * left tile, and the bottom right tile are rendered as they are. The top tile and the bottom tile are
0070  * stretched in x direction; the left tile and the right tile are stretched in y direction. Several
0071  * KWindowShadow objects can share shadow tiles to reduce memory usage. You have to specify padding()
0072  * along the shadow tiles. The padding values indicate how much the KWindowShadow sticks outside the
0073  * decorated window.
0074  *
0075  * Once the KWindowShadow is created, you're not allowed to attach or detach any shadow tiles, change
0076  * padding(), or change window(). In order to do so, you have to destroy() the shadow first, update
0077  * relevant properties, and create() the shadow again.
0078  */
0079 class KWINDOWSYSTEM_EXPORT KWindowShadow : public QObject
0080 {
0081     Q_OBJECT
0082 
0083 public:
0084     explicit KWindowShadow(QObject *parent = nullptr);
0085     ~KWindowShadow() override;
0086 
0087     /**
0088      * Returns the left tile attached to the KWindowShadow.
0089      */
0090     KWindowShadowTile::Ptr leftTile() const;
0091 
0092     /**
0093      * Attaches the left @p tile to the KWindowShadow.
0094      */
0095     void setLeftTile(KWindowShadowTile::Ptr tile);
0096 
0097     /**
0098      * Returns the top-left tile attached to the KWindowShadow.
0099      */
0100     KWindowShadowTile::Ptr topLeftTile() const;
0101 
0102     /**
0103      * Attaches the top-left @p tile to the KWindowShadow.
0104      */
0105     void setTopLeftTile(KWindowShadowTile::Ptr tile);
0106 
0107     /**
0108      * Returns the top tile attached to the KWindowShadow.
0109      */
0110     KWindowShadowTile::Ptr topTile() const;
0111 
0112     /**
0113      * Attaches the top @p tile to the KWindowShadow.
0114      */
0115     void setTopTile(KWindowShadowTile::Ptr tile);
0116 
0117     /**
0118      * Returns the top-right tile attached to the KWindowShadow.
0119      */
0120     KWindowShadowTile::Ptr topRightTile() const;
0121 
0122     /**
0123      * Attaches the top-right @p tile to the KWindowShadow.
0124      */
0125     void setTopRightTile(KWindowShadowTile::Ptr tile);
0126 
0127     /**
0128      * Returns the right tile attached to the KWindowShadow.
0129      */
0130     KWindowShadowTile::Ptr rightTile() const;
0131 
0132     /**
0133      * Attaches the right @p tile to the KWindowShadow.
0134      */
0135     void setRightTile(KWindowShadowTile::Ptr tile);
0136 
0137     /**
0138      * Returns the bottom-right tile attached to the KWindowShadow.
0139      */
0140     KWindowShadowTile::Ptr bottomRightTile() const;
0141 
0142     /**
0143      * Attaches the bottom-right tile to the KWindowShadow.
0144      */
0145     void setBottomRightTile(KWindowShadowTile::Ptr tile);
0146 
0147     /**
0148      * Returns the bottom tile attached to the KWindowShadow.
0149      */
0150     KWindowShadowTile::Ptr bottomTile() const;
0151 
0152     /**
0153      * Attaches the bottom @p tile to the KWindowShadow.
0154      */
0155     void setBottomTile(KWindowShadowTile::Ptr tile);
0156 
0157     /**
0158      * Returns the bottom-left tile attached to the KWindowShadow.
0159      */
0160     KWindowShadowTile::Ptr bottomLeftTile() const;
0161 
0162     /**
0163      * Attaches the bottom-left @p tile to the KWindowShadow.
0164      */
0165     void setBottomLeftTile(KWindowShadowTile::Ptr tile);
0166 
0167     /**
0168      * Returns the padding of the KWindowShadow.
0169      *
0170      * The padding values specify the visible extents of the shadow. The top left tile is rendered
0171      * with an offset of -padding().left() and -padding().top().
0172      */
0173     QMargins padding() const;
0174 
0175     /**
0176      * Sets the padding on the KWindowShadow.
0177      *
0178      * If the padding values are smaller than the sizes of the shadow tiles, then the shadow will
0179      * overlap with the window() and will be rendered behind window(). E.g. if all padding values
0180      * are set to 0, then the shadow will be completely occluded by the window().
0181      */
0182     void setPadding(const QMargins &padding);
0183 
0184     /**
0185      * Returns the window behind which the KWindowShadow will be rendered.
0186      */
0187     QWindow *window() const;
0188 
0189     /**
0190      * Sets the window behind which the KWindowShadow will be rendered.
0191      *
0192      * Note that the KWindowShadow does not track the platform surface. If for whatever reason the
0193      * native platform surface is deleted and then created, you must to destroy() the shadow and
0194      * create() it again yourself.
0195      */
0196     void setWindow(QWindow *window);
0197 
0198     /**
0199      * Returns @c true if the platform resources associated with the shadow have been allocated.
0200      */
0201     bool isCreated() const;
0202 
0203     /**
0204      * Allocates the platform resources associated with the KWindowShadow.
0205      *
0206      * Once the native platform resources have been allocated, you're not allowed to attach or
0207      * detach shadow tiles, change the padding or the target window. If you want to do so, you
0208      * must destroy() the shadow, change relevant attributes and call create() again.
0209      *
0210      * Returns @c true if the creation succeeded, otherwise returns @c false.
0211      */
0212     bool create();
0213 
0214     /**
0215      * Releases the platform resources associated with the KWindowShadow.
0216      *
0217      * Calling destroy() after window() had been destroyed will result in a no-op.
0218      */
0219     void destroy();
0220 
0221 private:
0222     QScopedPointer<KWindowShadowPrivate> d;
0223 };
0224 
0225 #endif // KWINDOWSHADOW_H