KDecoration3

decorationbutton.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 "decorationdefines.h"
9#include <kdecoration3/kdecoration3_export.h>
10
11#include <QObject>
12#include <QRect>
13
14class QHoverEvent;
15class QMouseEvent;
16class QPainter;
17class QWheelEvent;
18
19namespace KDecoration3
20{
21class DecorationButtonPrivate;
22class Decoration;
23
24/**
25 * @brief A button to be used in a Decoration.
26 *
27 * The DecorationButton is a simple Button which can be used (but doesn't have to) in a Decoration.
28 * It takes care of the input handling and triggers the correct state change methods on the
29 * Decoration.
30 *
31 * This simplifies the handling of DecorationButtons. A Decoration implementation just needs to
32 * subclass DecorationButton and implement the paint method. Everything else is handled by the
33 * DecorationButton.
34 *
35 * For positioning the DecorationButtons it's recommended to use a DecorationButtonGroup.
36 *
37 * @see Decoration
38 * @see DecorationButtonGroup
39 **/
40class KDECORATIONS3_EXPORT DecorationButton : public QObject
41{
42 Q_OBJECT
43 /**
44 * Whether the DecorationButton is visible. By default this is @c true, OnAllDesktops and
45 * QuickHelp depend on the DecoratedWindow's state.
46 **/
47 Q_PROPERTY(bool visible READ isVisible WRITE setVisible NOTIFY visibilityChanged)
48 /**
49 * Whether the DecorationButton is currently pressed.
50 **/
51 Q_PROPERTY(bool pressed READ isPressed NOTIFY pressedChanged)
52 /**
53 * Whether the DecorationButton is currently hovered.
54 **/
55 Q_PROPERTY(bool hovered READ isHovered NOTIFY hoveredChanged)
56 /**
57 * Whether the DecorationButton is enabled. Only an enabled button accepts hover and mouse
58 * press events.
59 **/
60 Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledChanged)
61 /**
62 * Whether the DecorationButton can be checked. This is used for state aware DecorationButtons
63 * like Maximize, Shade, KeepAbove, KeepBelow and OnAllDesktops.
64 **/
65 Q_PROPERTY(bool checkable READ isCheckable WRITE setCheckable NOTIFY checkableChanged)
66 /**
67 * Whether the DecorationButton is checked. A DecorationButton can only be checked if the
68 * DecorationButton is checkable. Note: the checked state is not changed by clicking the
69 * DecorationButton. It gets changed if the DecoratedWindow changes it's state, though.
70 **/
71 Q_PROPERTY(bool checked READ isChecked WRITE setChecked NOTIFY checkedChanged)
72 /**
73 * The geometry of the DecorationButton in Decoration-local coordinates.
74 **/
75 Q_PROPERTY(QRectF geometry READ geometry NOTIFY geometryChanged)
76 /**
77 * The mouse buttons the DecorationButton accepts. By default the Qt::LeftButton gets accepted,
78 * for some types more buttons are accepted.
79 **/
80 Q_PROPERTY(Qt::MouseButtons acceptedButtons READ acceptedButtons WRITE setAcceptedButtons NOTIFY acceptedButtonsChanged)
81public:
82 ~DecorationButton() override;
83
84 QRectF geometry() const;
85 QSizeF size() const;
86 void setGeometry(const QRectF &geometry);
87
88 bool isVisible() const;
89 bool isPressed() const;
90 bool isHovered() const;
91 bool isEnabled() const;
92 bool isChecked() const;
93 bool isCheckable() const;
94 DecorationButtonType type() const;
95
96 /**
97 * Returns @c true if @p pos is inside of the button, otherwise returns @c false.
98 **/
99 bool contains(const QPointF &pos) const;
100
101 Qt::MouseButtons acceptedButtons() const;
102 void setAcceptedButtons(Qt::MouseButtons buttons);
103
104 /**
105 * Invoked for painting this DecorationButtons. Implementing sub-classes need to implement
106 * this method. The coordinate system of the QPainter is set to Decoration coordinates.
107 *
108 * This method will be invoked from the rendering thread.
109 *
110 * @param painter The QPainter to paint this DecorationButton.
111 * @param repaintArea The area which is going to be repainted in Decoration coordinates
112 **/
113 virtual void paint(QPainter *painter, const QRectF &repaintArea) = 0;
114
115 Decoration *decoration() const;
116
117 bool event(QEvent *event) override;
118
119public Q_SLOTS:
120 void setEnabled(bool enabled);
121 void setCheckable(bool checkable);
122 void setChecked(bool checked);
123 void setVisible(bool visible);
124
125 /**
126 * Schedules a repaint of the DecorationButton.
127 * Calling update will eventually result in paint being invoked.
128 *
129 * @param rect The area to repaint in Decoration local coordinates, a null QRect updates the complete geometry
130 * @see paint
131 **/
132 void update(const QRectF &rect);
133 /**
134 * Schedules a repaint of the DecorationButton.
135 *
136 * Overloaded method for convenience.
137 **/
138 void update();
139
140Q_SIGNALS:
141 void clicked(Qt::MouseButton);
142 void pressed();
143 void released();
144 void pointerEntered();
145 void pointerLeft();
146 void doubleClicked();
147
148 void pressedChanged(bool);
149 void hoveredChanged(bool);
150 void enabledChanged(bool);
151 void checkableChanged(bool);
152 void checkedChanged(bool);
153 void geometryChanged(const QRectF &);
154 void acceptedButtonsChanged(Qt::MouseButtons);
155 void visibilityChanged(bool);
156
157protected:
158 explicit DecorationButton(DecorationButtonType type, Decoration *decoration, QObject *parent = nullptr);
159
160 virtual void hoverEnterEvent(QHoverEvent *event);
161 virtual void hoverLeaveEvent(QHoverEvent *event);
162 virtual void hoverMoveEvent(QHoverEvent *event);
163 virtual void mouseMoveEvent(QMouseEvent *event);
164 virtual void mousePressEvent(QMouseEvent *event);
165 virtual void mouseReleaseEvent(QMouseEvent *event);
166 virtual void wheelEvent(QWheelEvent *event);
167
168private:
169 class Private;
170 std::unique_ptr<Private> d;
171};
172
173} // namespace
174
175#ifndef K_DOXYGEN
176size_t KDECORATIONS3_EXPORT qHash(const KDecoration3::DecorationButtonType &type, size_t seed = 0);
177#endif
178
179Q_DECLARE_METATYPE(KDecoration3::DecorationButtonType)
A button to be used in a Decoration.
Base class for the Decoration.
Definition decoration.h:83
Framework for creating window decorations.
DecorationButtonType
The DecorationButtonType is a helper type for the DecorationButton.
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.