KDecoration2

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

KDE's Doxygen guidelines are available online.