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

KDE's Doxygen guidelines are available online.