KDecoration3

decoration.h
1/*
2 * SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org>
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 <kdecoration3/kdecoration3_export.h>
10
11#include <QMarginsF>
12#include <QObject>
13#include <QRectF>
14#include <QSharedDataPointer>
15
16class QHoverEvent;
17class QMouseEvent;
18class QPainter;
19class QWheelEvent;
20
21/**
22 * @brief Framework for creating window decorations.
23 *
24 **/
25namespace KDecoration3
26{
27class DecorationPrivate;
28class DecoratedWindow;
29class DecorationButton;
30class DecorationSettings;
31class DecorationStateData;
32
33/**
34 * \brief Decoration state.
35 *
36 * The DecorationState type represents double bufferred state associated with a decoration.
37 *
38 * \note Sub-classes of DecorationState must override the clone() function.
39 */
40class KDECORATIONS3_EXPORT DecorationState
41{
42public:
44 DecorationState(const DecorationState &other);
45 virtual ~DecorationState();
46
47 virtual std::shared_ptr<DecorationState> clone() const;
48
49 QMarginsF borders() const;
50 void setBorders(const QMarginsF &margins);
51
52private:
54};
55
56/**
57 * @brief Base class for the Decoration.
58 *
59 * To provide a Decoration one needs to inherit from this class. The framework will instantiate
60 * an instance of the inherited class for each DecoratedWindow.
61 *
62 * The main tasks of the Decoration is to provide borders around the DecoratedWindow. For this
63 * the Deocration provides border sizes: those should be adjusted depending on the state of the
64 * DecoratedWindow. E.g. commonly a maximized DecoratedWindow does not have borders on the side,
65 * only the title bar.
66 *
67 * Whenever the visual representation of the Decoration changes the slot @link Decoration::update @endlink
68 * should be invoked to request a repaint. The framework will in return invoke the
69 * @link Decoration::paint @endlink method. This method needs to be implemented by inheriting
70 * classes.
71 *
72 * A Decoration commonly provides buttons for interaction. E.g. a close button to close the
73 * DecoratedWindow. For such actions the Decoration provides slots which should be connected to
74 * the clicked signals of the buttons. For convenience the framework provides the @link DecorationButton @endlink
75 * and the @link DecorationButtonGroup @endlink for easier layout. It is not required to use those,
76 * if one uses different ways to represent the actions one needs to filter the events accordingly.
77 *
78 * @see DecoratedWindow
79 * @see DecorationButton
80 * @see DecorationButtonGroup
81 **/
82class KDECORATIONS3_EXPORT Decoration : public QObject
83{
84 Q_OBJECT
85 Q_PROPERTY(QMarginsF borders READ borders NOTIFY bordersChanged)
86 Q_PROPERTY(qreal borderLeft READ borderLeft NOTIFY bordersChanged)
87 Q_PROPERTY(qreal borderRight READ borderRight NOTIFY bordersChanged)
88 Q_PROPERTY(qreal borderTop READ borderTop NOTIFY bordersChanged)
89 Q_PROPERTY(qreal borderBottom READ borderBottom NOTIFY bordersChanged)
90 Q_PROPERTY(QMarginsF resizeOnlyBorders READ resizeOnlyBorders NOTIFY resizeOnlyBordersChanged)
91 Q_PROPERTY(qreal resizeOnlyBorderLeft READ resizeOnlyBorderLeft NOTIFY resizeOnlyBordersChanged)
92 Q_PROPERTY(qreal resizeOnlyBorderRight READ resizeOnlyBorderRight NOTIFY resizeOnlyBordersChanged)
93 Q_PROPERTY(qreal resizeOnlyBorderTop READ resizeOnlyBorderTop NOTIFY resizeOnlyBordersChanged)
94 Q_PROPERTY(qreal resizeOnlyBorderBottom READ resizeOnlyBorderBottom NOTIFY resizeOnlyBordersChanged)
95 /**
96 * This property denotes the part of the Decoration which is currently under the mouse pointer.
97 * It gets automatically updated whenever a QMouseEvent or QHoverEvent gets processed.
98 **/
99 Q_PROPERTY(Qt::WindowFrameSection sectionUnderMouse READ sectionUnderMouse NOTIFY sectionUnderMouseChanged)
100 /**
101 * The titleBar is the area inside the Decoration containing all controls (e.g. Buttons)
102 * and the caption. The titleBar is the main interaction area, while all other areas of the
103 * Decoration are normally used as resize areas.
104 **/
105 Q_PROPERTY(QRectF titleBar READ titleBar NOTIFY titleBarChanged)
106 /**
107 * Whether the Decoration is fully opaque. By default a Decoration is considered to
108 * use the alpha channel and this property has the value @c false. But for e.g. a maximized
109 * DecoratedWindow it is possible that the Decoration is fully opaque. In this case the
110 * Decoration should set this property to @c true.
111 **/
112 Q_PROPERTY(bool opaque READ isOpaque NOTIFY opaqueChanged)
113public:
114 ~Decoration() override;
115
116 /**
117 * The DecoratedWindow for this Decoration.
118 **/
119 DecoratedWindow *window() const;
120
121 QMarginsF borders() const;
122 qreal borderLeft() const;
123 qreal borderRight() const;
124 qreal borderTop() const;
125 qreal borderBottom() const;
126 QMarginsF resizeOnlyBorders() const;
127 qreal resizeOnlyBorderLeft() const;
128 qreal resizeOnlyBorderRight() const;
129 qreal resizeOnlyBorderTop() const;
130 qreal resizeOnlyBorderBottom() const;
131 Qt::WindowFrameSection sectionUnderMouse() const;
132 QRectF titleBar() const;
133 bool isOpaque() const;
134
135 /**
136 * DecorationShadow for this Decoration. It is recommended that multiple Decorations share
137 * the same DecorationShadow. E.g one DecorationShadow for all inactive Decorations and one
138 * for the active Decoration.
139 **/
140 std::shared_ptr<DecorationShadow> shadow() const;
141
142 /**
143 * The decoration's geometry in local coordinates.
144 *
145 * Basically the size of the DecoratedWindow combined with the borders.
146 **/
147 QRectF rect() const;
148 QSizeF size() const;
149
150 /**
151 * The decoration's blur region in local coordinates
152 */
153 QRegion blurRegion() const;
154
155 /**
156 * Invoked by the framework to set the Settings for this Decoration before
157 * init is invoked.
158 * @internal
159 **/
160 void setSettings(const std::shared_ptr<DecorationSettings> &settings);
161 /**
162 * @returns The DecorationSettings used for this Decoration.
163 **/
164 std::shared_ptr<DecorationSettings> settings() const;
165
166 /**
167 * Implement this method in inheriting classes to provide the rendering.
168 *
169 * The @p painter is set up to paint on an internal QPaintDevice. The painting is
170 * implicitly double buffered.
171 *
172 * @param painter The painter which needs to be used for rendering
173 * @param repaintArea The region which needs to be repainted.
174 **/
175 virtual void paint(QPainter *painter, const QRectF &repaintArea) = 0;
176
177 bool event(QEvent *event) override;
178
179 /**
180 * \internal
181 *
182 * Allocates the resources associated with the decoration, for example state containers.
183 *
184 * \note This method gets invoked by the compositor before init(), the decoration implementation
185 * must not call it.
186 */
187 void create();
188
189 /**
190 * \internal
191 *
192 * Make the specified \a state current.
193 *
194 * The decoration maintains a double-buffered state. If a double-buffered property needs
195 * to be changed, the next state will be updated and the nextStateChanged() signal will be
196 * emitted to notify the compositor about it.
197 *
198 * When the next state gets applied is subject to compositor policies. For example, the
199 * compositor may apply the new state immediately, or it can synchronize double-buffered
200 * decoration state with double-buffered toplevel state.
201 *
202 * \sa currentState(), nextState(), createState()
203 */
204 void apply(std::shared_ptr<DecorationState> state);
205
206 /**
207 * Returns the currently applied state.
208 *
209 * \sa apply()
210 */
211 std::shared_ptr<DecorationState> currentState() const;
212
213 /**
214 * Returns the next state, i.e. the state that the decoration implementation wants to be current.
215 *
216 * \sa apply()
217 */
218 std::shared_ptr<DecorationState> nextState() const;
219
220 /**
221 * Notifies the framework that the decoration state has changed. When the new state is applied
222 * is subject to compositor policies. For example, the compositor may re-configure the window
223 * and apply the new state when the window is repainted.
224 */
225 void setState(std::function<void(DecorationState *state)> callback);
226
227public Q_SLOTS:
228 void requestClose();
229 void requestToggleMaximization(Qt::MouseButtons buttons);
230 void requestMinimize();
231 void requestContextHelp();
232 void requestToggleOnAllDesktops();
233 void requestToggleShade();
234 void requestToggleKeepAbove();
235 void requestToggleKeepBelow();
236
237#if KDECORATIONS3_ENABLE_DEPRECATED_SINCE(5, 21)
238 /**
239 * @deprecated
240 * @see requestShowWindowMenu(const QRect &rect)
241 */
242 KDECORATIONS3_DEPRECATED_VERSION(5, 21, "Use Decoration::requestShowWindowMenu(QRect)")
243 void requestShowWindowMenu();
244#endif
245
246 /**
247 * @param rect the location at which to show the window menu
248 */
249 void requestShowWindowMenu(const QRect &rect);
250 void requestShowToolTip(const QString &text);
251 void requestHideToolTip();
252
253 void showApplicationMenu(int actionId);
254 void requestShowApplicationMenu(const QRect &rect, int actionId);
255
256 void update(const QRectF &rect);
257 void update();
258
259 /**
260 * This method gets invoked from the framework once the Decoration is created and
261 * completely setup.
262 *
263 * An inheriting class should override this method and perform all initialization in
264 * this method instead of the constructor.
265 *
266 * @return true if initialization has been successful,
267 * false otherwise (for example, a QML component could not be loaded)
268 **/
269 virtual bool init() = 0;
270
271Q_SIGNALS:
272 void blurRegionChanged();
273 void bordersChanged();
274 void resizeOnlyBordersChanged();
275 void sectionUnderMouseChanged(Qt::WindowFrameSection);
276 void titleBarChanged();
277 void opaqueChanged(bool);
278 void shadowChanged(const std::shared_ptr<DecorationShadow> &shadow);
279 void damaged(const QRegion &region);
280 void currentStateChanged(std::shared_ptr<DecorationState> state);
281 void nextStateChanged(std::shared_ptr<DecorationState> state);
282
283protected:
284 /**
285 * Constructor for the Decoration.
286 *
287 * The @p args are used by the decoration framework to pass meta information
288 * to the Decoration. An inheriting class is supposed to pass the args to the
289 * parent class.
290 *
291 * @param parent The parent of the Decoration
292 * @param args Additional arguments passed in from the framework
293 **/
294 explicit Decoration(QObject *parent, const QVariantList &args);
295 void setBorders(const QMarginsF &borders);
296 void setResizeOnlyBorders(const QMarginsF &borders);
297 void setBlurRegion(const QRegion &region);
298 /**
299 * An implementation has to invoke this method whenever the area
300 * containing the controls and caption changes.
301 * @param rect The new geometry of the titleBar in Decoration coordinates
302 **/
303 void setTitleBar(const QRectF &rect);
304 void setOpaque(bool opaque);
305 void setShadow(const std::shared_ptr<DecorationShadow> &shadow);
306
307 virtual void hoverEnterEvent(QHoverEvent *event);
308 virtual void hoverLeaveEvent(QHoverEvent *event);
309 virtual void hoverMoveEvent(QHoverEvent *event);
310 virtual void mouseMoveEvent(QMouseEvent *event);
311 virtual void mousePressEvent(QMouseEvent *event);
312 virtual void mouseReleaseEvent(QMouseEvent *event);
313 virtual void wheelEvent(QWheelEvent *event);
314
315 /**
316 * Create a state container. The decoration implementation can override this method to attach
317 * its own properties to the decoration state.
318 *
319 * The default implementation simply creates an instance of the DecorationState type.
320 *
321 * \sa currentState(), nextState()
322 */
323 virtual std::shared_ptr<DecorationState> createState();
324
325private:
326 friend class DecorationButton;
327 class Private;
328 std::unique_ptr<Private> d;
329};
330
331} // namespace
332
333Q_DECLARE_METATYPE(KDecoration3::Decoration *)
The Client which gets decorated.
A button to be used in a Decoration.
Common settings for the Decoration.
A wrapper to define the shadow around the Decoration.
Base class for the Decoration.
Definition decoration.h:83
virtual bool init()=0
This method gets invoked from the framework once the Decoration is created and completely setup.
Framework for creating window decorations.
WindowFrameSection
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 16:55:48 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.