KDecoration2

decoration.h
1 /*
2  * SPDX-FileCopyrightText: 2014 Martin Gräßlin <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5  */
6 #pragma once
7 
8 #include "decorationshadow.h"
9 #include <kdecoration2/kdecoration2_export.h>
10 
11 #include <QMargins>
12 #include <QObject>
13 #include <QRect>
14 
15 class QHoverEvent;
16 class QMouseEvent;
17 class QPainter;
18 class QWheelEvent;
19 
20 /**
21  * @brief Framework for creating window decorations.
22  *
23  **/
24 namespace KDecoration2
25 {
26 class DecorationPrivate;
27 class DecoratedClient;
28 class DecorationButton;
29 class DecorationSettings;
30 
31 /**
32  * @brief Base class for the Decoration.
33  *
34  * To provide a Decoration one needs to inherit from this class. The framework will instantiate
35  * an instance of the inherited class for each DecoratedClient.
36  *
37  * The main tasks of the Decoration is to provide borders around the DecoratedClient. For this
38  * the Deocration provides border sizes: those should be adjusted depending on the state of the
39  * DecoratedClient. E.g. commonly a maximized DecoratedClient does not have borders on the side,
40  * only the title bar.
41  *
42  * Whenever the visual representation of the Decoration changes the slot @link Decoration::update @endlink
43  * should be invoked to request a repaint. The framework will in return invoke the
44  * @link Decoration::paint @endlink method. This method needs to be implemented by inheriting
45  * classes.
46  *
47  * A Decoration commonly provides buttons for interaction. E.g. a close button to close the
48  * DecoratedClient. For such actions the Decoration provides slots which should be connected to
49  * the clicked signals of the buttons. For convenience the framework provides the @link DecorationButton @endlink
50  * and the @link DecorationButtonGroup @endlink for easier layout. It is not required to use those,
51  * if one uses different ways to represent the actions one needs to filter the events accordingly.
52  *
53  * @see DecoratedClient
54  * @see DecorationButton
55  * @see DecorationButtonGroup
56  **/
57 class KDECORATIONS2_EXPORT Decoration : public QObject
58 {
59  Q_OBJECT
60  Q_PROPERTY(QMargins borders READ borders NOTIFY bordersChanged)
61  Q_PROPERTY(int borderLeft READ borderLeft NOTIFY bordersChanged)
62  Q_PROPERTY(int borderRight READ borderRight NOTIFY bordersChanged)
63  Q_PROPERTY(int borderTop READ borderTop NOTIFY bordersChanged)
64  Q_PROPERTY(int borderBottom READ borderBottom NOTIFY bordersChanged)
65  Q_PROPERTY(QMargins resizeOnlyBorders READ resizeOnlyBorders NOTIFY resizeOnlyBordersChanged)
66  Q_PROPERTY(int resizeOnlyBorderLeft READ resizeOnlyBorderLeft NOTIFY resizeOnlyBordersChanged)
67  Q_PROPERTY(int resizeOnlyBorderRight READ resizeOnlyBorderRight NOTIFY resizeOnlyBordersChanged)
68  Q_PROPERTY(int resizeOnlyBorderTop READ resizeOnlyBorderTop NOTIFY resizeOnlyBordersChanged)
69  Q_PROPERTY(int resizeOnlyBorderBottom READ resizeOnlyBorderBottom NOTIFY resizeOnlyBordersChanged)
70  /**
71  * This property denotes the part of the Decoration which is currently under the mouse pointer.
72  * It gets automatically updated whenever a QMouseEvent or QHoverEvent gets processed.
73  **/
74  Q_PROPERTY(Qt::WindowFrameSection sectionUnderMouse READ sectionUnderMouse NOTIFY sectionUnderMouseChanged)
75  /**
76  * The titleBar is the area inside the Decoration containing all controls (e.g. Buttons)
77  * and the caption. The titleBar is the main interaction area, while all other areas of the
78  * Decoration are normally used as resize areas.
79  **/
80  Q_PROPERTY(QRect titleBar READ titleBar NOTIFY titleBarChanged)
81  /**
82  * Whether the Decoration is fully opaque. By default a Decoration is considered to
83  * use the alpha channel and this property has the value @c false. But for e.g. a maximized
84  * DecoratedClient it is possible that the Decoration is fully opaque. In this case the
85  * Decoration should set this property to @c true.
86  **/
87  Q_PROPERTY(bool opaque READ isOpaque NOTIFY opaqueChanged)
88 public:
89  ~Decoration() override;
90 
91  /**
92  * The DecoratedClient for this Decoration.
93  **/
94  DecoratedClient *client() const;
95 
96  QMargins borders() const;
97  int borderLeft() const;
98  int borderRight() const;
99  int borderTop() const;
100  int borderBottom() const;
101  QMargins resizeOnlyBorders() const;
102  int resizeOnlyBorderLeft() const;
103  int resizeOnlyBorderRight() const;
104  int resizeOnlyBorderTop() const;
105  int resizeOnlyBorderBottom() const;
106  Qt::WindowFrameSection sectionUnderMouse() const;
107  QRect titleBar() const;
108  bool isOpaque() const;
109 
110  /**
111  * DecorationShadow for this Decoration. It is recommended that multiple Decorations share
112  * the same DecorationShadow. E.g one DecorationShadow for all inactive Decorations and one
113  * for the active Decoration.
114  **/
115  std::shared_ptr<DecorationShadow> shadow() const;
116 
117  /**
118  * The decoration's geometry in local coordinates.
119  *
120  * Basically the size of the DecoratedClient combined with the borders.
121  **/
122  QRect rect() const;
123  QSize size() const;
124 
125  /**
126  * The decoration's blur region in local coordinates
127  */
128  QRegion blurRegion() const;
129 
130  /**
131  * Invoked by the framework to set the Settings for this Decoration before
132  * init is invoked.
133  * @internal
134  **/
135  void setSettings(const std::shared_ptr<DecorationSettings> &settings);
136  /**
137  * @returns The DecorationSettings used for this Decoration.
138  **/
139  std::shared_ptr<DecorationSettings> settings() const;
140 
141  /**
142  * Implement this method in inheriting classes to provide the rendering.
143  *
144  * The @p painter is set up to paint on an internal QPaintDevice. The painting is
145  * implicitly double buffered.
146  *
147  * @param painter The painter which needs to be used for rendering
148  * @param repaintArea The region which needs to be repainted.
149  **/
150  virtual void paint(QPainter *painter, const QRect &repaintArea) = 0;
151 
152  bool event(QEvent *event) override;
153 
154 public Q_SLOTS:
155  void requestClose();
156  void requestToggleMaximization(Qt::MouseButtons buttons);
157  void requestMinimize();
158  void requestContextHelp();
159  void requestToggleOnAllDesktops();
160  void requestToggleShade();
161  void requestToggleKeepAbove();
162  void requestToggleKeepBelow();
163 
164 #if KDECORATIONS2_ENABLE_DEPRECATED_SINCE(5, 21)
165  /**
166  * @deprecated
167  * @see requestShowWindowMenu(const QRect &rect)
168  */
169  KDECORATIONS2_DEPRECATED_VERSION(5, 21, "Use Decoration::requestShowWindowMenu(QRect)")
170  void requestShowWindowMenu();
171 #endif
172 
173  /**
174  * @param rect the location at which to show the window menu
175  */
176  void requestShowWindowMenu(const QRect &rect);
177  void requestShowToolTip(const QString &text);
178  void requestHideToolTip();
179 
180  void showApplicationMenu(int actionId);
181  void requestShowApplicationMenu(const QRect &rect, int actionId);
182 
183  void update(const QRect &rect);
184  void update();
185 
186  /**
187  * This method gets invoked from the framework once the Decoration is created and
188  * completely setup.
189  *
190  * An inheriting class should override this method and perform all initialization in
191  * this method instead of the constructor.
192  *
193  * @return true if initialization has been successful,
194  * false otherwise (for example, a QML component could not be loaded)
195  **/
196  virtual bool init() = 0;
197 
198 Q_SIGNALS:
199  void blurRegionChanged();
200  void bordersChanged();
201  void resizeOnlyBordersChanged();
202  void sectionUnderMouseChanged(Qt::WindowFrameSection);
203  void titleBarChanged();
204  void opaqueChanged(bool);
205  void shadowChanged(const std::shared_ptr<DecorationShadow> &shadow);
206  void damaged(const QRegion &region);
207 
208 protected:
209  /**
210  * Constructor for the Decoration.
211  *
212  * The @p args are used by the decoration framework to pass meta information
213  * to the Decoration. An inheriting class is supposed to pass the args to the
214  * parent class.
215  *
216  * @param parent The parent of the Decoration
217  * @param args Additional arguments passed in from the framework
218  **/
219  explicit Decoration(QObject *parent, const QVariantList &args);
220  void setBorders(const QMargins &borders);
221  void setResizeOnlyBorders(const QMargins &borders);
222  void setBlurRegion(const QRegion &region);
223  /**
224  * An implementation has to invoke this method whenever the area
225  * containing the controls and caption changes.
226  * @param rect The new geometry of the titleBar in Decoration coordinates
227  **/
228  void setTitleBar(const QRect &rect);
229  void setOpaque(bool opaque);
230  void setShadow(const std::shared_ptr<DecorationShadow> &shadow);
231 
232  virtual void hoverEnterEvent(QHoverEvent *event);
233  virtual void hoverLeaveEvent(QHoverEvent *event);
234  virtual void hoverMoveEvent(QHoverEvent *event);
235  virtual void mouseMoveEvent(QMouseEvent *event);
236  virtual void mousePressEvent(QMouseEvent *event);
237  virtual void mouseReleaseEvent(QMouseEvent *event);
238  virtual void wheelEvent(QWheelEvent *event);
239 
240 private:
241  friend class DecorationButton;
242  class Private;
243  std::unique_ptr<Private> d;
244 };
245 
246 } // namespace
247 
248 Q_DECLARE_METATYPE(KDecoration2::Decoration *)
WindowFrameSection
Base class for the Decoration.
Definition: decoration.h:57
A wrapper to define the shadow around the Decoration.
Common settings for the Decoration.
The Client which gets decorated.
Framework for creating window decorations.
A button to be used in a Decoration.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 03:52:27 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.