File indexing completed on 2024-05-05 05:29:53
0001 /* 0002 * SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org> 0003 * 0004 * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL 0005 */ 0006 #pragma once 0007 0008 #include "decorationshadow.h" 0009 #include <kdecoration2/kdecoration2_export.h> 0010 0011 #include <QMargins> 0012 #include <QObject> 0013 #include <QRect> 0014 0015 class QHoverEvent; 0016 class QMouseEvent; 0017 class QPainter; 0018 class QWheelEvent; 0019 0020 /** 0021 * @brief Framework for creating window decorations. 0022 * 0023 **/ 0024 namespace KDecoration2 0025 { 0026 class DecorationPrivate; 0027 class DecoratedClient; 0028 class DecorationButton; 0029 class DecorationSettings; 0030 0031 /** 0032 * @brief Base class for the Decoration. 0033 * 0034 * To provide a Decoration one needs to inherit from this class. The framework will instantiate 0035 * an instance of the inherited class for each DecoratedClient. 0036 * 0037 * The main tasks of the Decoration is to provide borders around the DecoratedClient. For this 0038 * the Deocration provides border sizes: those should be adjusted depending on the state of the 0039 * DecoratedClient. E.g. commonly a maximized DecoratedClient does not have borders on the side, 0040 * only the title bar. 0041 * 0042 * Whenever the visual representation of the Decoration changes the slot @link Decoration::update @endlink 0043 * should be invoked to request a repaint. The framework will in return invoke the 0044 * @link Decoration::paint @endlink method. This method needs to be implemented by inheriting 0045 * classes. 0046 * 0047 * A Decoration commonly provides buttons for interaction. E.g. a close button to close the 0048 * DecoratedClient. For such actions the Decoration provides slots which should be connected to 0049 * the clicked signals of the buttons. For convenience the framework provides the @link DecorationButton @endlink 0050 * and the @link DecorationButtonGroup @endlink for easier layout. It is not required to use those, 0051 * if one uses different ways to represent the actions one needs to filter the events accordingly. 0052 * 0053 * @see DecoratedClient 0054 * @see DecorationButton 0055 * @see DecorationButtonGroup 0056 **/ 0057 class KDECORATIONS2_EXPORT Decoration : public QObject 0058 { 0059 Q_OBJECT 0060 Q_PROPERTY(QMargins borders READ borders NOTIFY bordersChanged) 0061 Q_PROPERTY(int borderLeft READ borderLeft NOTIFY bordersChanged) 0062 Q_PROPERTY(int borderRight READ borderRight NOTIFY bordersChanged) 0063 Q_PROPERTY(int borderTop READ borderTop NOTIFY bordersChanged) 0064 Q_PROPERTY(int borderBottom READ borderBottom NOTIFY bordersChanged) 0065 Q_PROPERTY(QMargins resizeOnlyBorders READ resizeOnlyBorders NOTIFY resizeOnlyBordersChanged) 0066 Q_PROPERTY(int resizeOnlyBorderLeft READ resizeOnlyBorderLeft NOTIFY resizeOnlyBordersChanged) 0067 Q_PROPERTY(int resizeOnlyBorderRight READ resizeOnlyBorderRight NOTIFY resizeOnlyBordersChanged) 0068 Q_PROPERTY(int resizeOnlyBorderTop READ resizeOnlyBorderTop NOTIFY resizeOnlyBordersChanged) 0069 Q_PROPERTY(int resizeOnlyBorderBottom READ resizeOnlyBorderBottom NOTIFY resizeOnlyBordersChanged) 0070 /** 0071 * This property denotes the part of the Decoration which is currently under the mouse pointer. 0072 * It gets automatically updated whenever a QMouseEvent or QHoverEvent gets processed. 0073 **/ 0074 Q_PROPERTY(Qt::WindowFrameSection sectionUnderMouse READ sectionUnderMouse NOTIFY sectionUnderMouseChanged) 0075 /** 0076 * The titleBar is the area inside the Decoration containing all controls (e.g. Buttons) 0077 * and the caption. The titleBar is the main interaction area, while all other areas of the 0078 * Decoration are normally used as resize areas. 0079 **/ 0080 Q_PROPERTY(QRect titleBar READ titleBar NOTIFY titleBarChanged) 0081 /** 0082 * Whether the Decoration is fully opaque. By default a Decoration is considered to 0083 * use the alpha channel and this property has the value @c false. But for e.g. a maximized 0084 * DecoratedClient it is possible that the Decoration is fully opaque. In this case the 0085 * Decoration should set this property to @c true. 0086 **/ 0087 Q_PROPERTY(bool opaque READ isOpaque NOTIFY opaqueChanged) 0088 public: 0089 ~Decoration() override; 0090 0091 /** 0092 * The DecoratedClient for this Decoration. 0093 **/ 0094 DecoratedClient *client() const; 0095 0096 QMargins borders() const; 0097 int borderLeft() const; 0098 int borderRight() const; 0099 int borderTop() const; 0100 int borderBottom() const; 0101 QMargins resizeOnlyBorders() const; 0102 int resizeOnlyBorderLeft() const; 0103 int resizeOnlyBorderRight() const; 0104 int resizeOnlyBorderTop() const; 0105 int resizeOnlyBorderBottom() const; 0106 Qt::WindowFrameSection sectionUnderMouse() const; 0107 QRect titleBar() const; 0108 bool isOpaque() const; 0109 0110 /** 0111 * DecorationShadow for this Decoration. It is recommended that multiple Decorations share 0112 * the same DecorationShadow. E.g one DecorationShadow for all inactive Decorations and one 0113 * for the active Decoration. 0114 **/ 0115 std::shared_ptr<DecorationShadow> shadow() const; 0116 0117 /** 0118 * The decoration's geometry in local coordinates. 0119 * 0120 * Basically the size of the DecoratedClient combined with the borders. 0121 **/ 0122 QRect rect() const; 0123 QSize size() const; 0124 0125 /** 0126 * The decoration's blur region in local coordinates 0127 */ 0128 QRegion blurRegion() const; 0129 0130 /** 0131 * Invoked by the framework to set the Settings for this Decoration before 0132 * init is invoked. 0133 * @internal 0134 **/ 0135 void setSettings(const std::shared_ptr<DecorationSettings> &settings); 0136 /** 0137 * @returns The DecorationSettings used for this Decoration. 0138 **/ 0139 std::shared_ptr<DecorationSettings> settings() const; 0140 0141 /** 0142 * Implement this method in inheriting classes to provide the rendering. 0143 * 0144 * The @p painter is set up to paint on an internal QPaintDevice. The painting is 0145 * implicitly double buffered. 0146 * 0147 * @param painter The painter which needs to be used for rendering 0148 * @param repaintArea The region which needs to be repainted. 0149 **/ 0150 virtual void paint(QPainter *painter, const QRect &repaintArea) = 0; 0151 0152 bool event(QEvent *event) override; 0153 0154 public Q_SLOTS: 0155 void requestClose(); 0156 void requestToggleMaximization(Qt::MouseButtons buttons); 0157 void requestMinimize(); 0158 void requestContextHelp(); 0159 void requestToggleOnAllDesktops(); 0160 void requestToggleShade(); 0161 void requestToggleKeepAbove(); 0162 void requestToggleKeepBelow(); 0163 0164 #if KDECORATIONS2_ENABLE_DEPRECATED_SINCE(5, 21) 0165 /** 0166 * @deprecated 0167 * @see requestShowWindowMenu(const QRect &rect) 0168 */ 0169 KDECORATIONS2_DEPRECATED_VERSION(5, 21, "Use Decoration::requestShowWindowMenu(QRect)") 0170 void requestShowWindowMenu(); 0171 #endif 0172 0173 /** 0174 * @param rect the location at which to show the window menu 0175 */ 0176 void requestShowWindowMenu(const QRect &rect); 0177 void requestShowToolTip(const QString &text); 0178 void requestHideToolTip(); 0179 0180 void showApplicationMenu(int actionId); 0181 void requestShowApplicationMenu(const QRect &rect, int actionId); 0182 0183 void update(const QRect &rect); 0184 void update(); 0185 0186 /** 0187 * This method gets invoked from the framework once the Decoration is created and 0188 * completely setup. 0189 * 0190 * An inheriting class should override this method and perform all initialization in 0191 * this method instead of the constructor. 0192 * 0193 * @return true if initialization has been successful, 0194 * false otherwise (for example, a QML component could not be loaded) 0195 **/ 0196 virtual bool init() = 0; 0197 0198 Q_SIGNALS: 0199 void blurRegionChanged(); 0200 void bordersChanged(); 0201 void resizeOnlyBordersChanged(); 0202 void sectionUnderMouseChanged(Qt::WindowFrameSection); 0203 void titleBarChanged(); 0204 void opaqueChanged(bool); 0205 void shadowChanged(const std::shared_ptr<DecorationShadow> &shadow); 0206 void damaged(const QRegion ®ion); 0207 0208 protected: 0209 /** 0210 * Constructor for the Decoration. 0211 * 0212 * The @p args are used by the decoration framework to pass meta information 0213 * to the Decoration. An inheriting class is supposed to pass the args to the 0214 * parent class. 0215 * 0216 * @param parent The parent of the Decoration 0217 * @param args Additional arguments passed in from the framework 0218 **/ 0219 explicit Decoration(QObject *parent, const QVariantList &args); 0220 void setBorders(const QMargins &borders); 0221 void setResizeOnlyBorders(const QMargins &borders); 0222 void setBlurRegion(const QRegion ®ion); 0223 /** 0224 * An implementation has to invoke this method whenever the area 0225 * containing the controls and caption changes. 0226 * @param rect The new geometry of the titleBar in Decoration coordinates 0227 **/ 0228 void setTitleBar(const QRect &rect); 0229 void setOpaque(bool opaque); 0230 void setShadow(const std::shared_ptr<DecorationShadow> &shadow); 0231 0232 virtual void hoverEnterEvent(QHoverEvent *event); 0233 virtual void hoverLeaveEvent(QHoverEvent *event); 0234 virtual void hoverMoveEvent(QHoverEvent *event); 0235 virtual void mouseMoveEvent(QMouseEvent *event); 0236 virtual void mousePressEvent(QMouseEvent *event); 0237 virtual void mouseReleaseEvent(QMouseEvent *event); 0238 virtual void wheelEvent(QWheelEvent *event); 0239 0240 private: 0241 friend class DecorationButton; 0242 class Private; 0243 std::unique_ptr<Private> d; 0244 }; 0245 0246 } // namespace 0247 0248 Q_DECLARE_METATYPE(KDecoration2::Decoration *)