Perceptual Color

colorwheel.h
1// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
2// SPDX-License-Identifier: BSD-2-Clause OR MIT
3
4#ifndef COLORWHEEL_H
5#define COLORWHEEL_H
6
7#include "abstractdiagram.h"
8#include "constpropagatinguniquepointer.h"
9#include "importexport.h"
10#include <qglobal.h>
11#include <qsharedpointer.h>
12#include <qsize.h>
13class QKeyEvent;
14class QMouseEvent;
15class QPaintEvent;
16class QResizeEvent;
17class QWheelEvent;
18class QWidget;
19
20#if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
21#include <qtmetamacros.h>
22#else
23#include <qobjectdefs.h>
24#include <qstring.h>
25class QObject;
26#endif
27
28namespace PerceptualColor
29{
30class ColorWheelPrivate;
31
32class RgbColorSpace;
33
34/** @brief A color wheel widget.
35 *
36 * This widget allows the user to choose the hue (as defined in the LCH
37 * color space).
38 *
39 * @image html ColorWheel.png "ColorWheel" width=200
40 *
41 * @note This widget <em>always</em> accepts focus by a mouse click within
42 * the circle. This happens regardless of the <tt>QWidget::focusPolicy</tt>
43 * property:
44 * - If you set the <tt>QWidget::focusPolicy</tt> property to a
45 * value that does not accept focus by mouse click, the focus
46 * will nevertheless be accepted for clicks within the actual circle.
47 * (This is the default behavior.)
48 * - If you set the <tt>QWidget::focusPolicy</tt> property to a
49 * value that accepts focus by mouse click, the focus will not only be
50 * accepted for clicks within the actual circle, but also for clicks
51 * anywhere within the (rectangular) widget.
52 *
53 * @internal
54 *
55 * @todo Add support for Qt::MouseButton::BackButton?
56 * (Typically present on the 'thumb' side of a mouse
57 * with extra buttons. This is NOT the tilt wheel.)
58 * Add support for Qt::MouseButton::ForwardButton?
59 * (Typically present beside the 'Back' button, and
60 * also pressed by the thumb.)
61 *
62 * @todo What when some of the wheel colors are out of gamut? How to handle
63 * that? */
65{
66 Q_OBJECT
67
68 /** @brief The currently selected hue.
69 *
70 * This is the hue angle, as defined in the LCH color model.
71 *
72 *
73 * Measured in degree.
74 *
75 * Valid range: [0°, 360°[. The widget accepts initially also
76 * out-of-range values, but once a user interaction has taken
77 * place, it will hold a normalized value. So
78 * \li 0 gets 0
79 * \li 359.9 gets 359.9
80 * \li 360 gets 0
81 * \li 361.2 gets 1.2
82 * \li 720 gets 0
83 * \li -1 gets 359
84 * \li -1.3 gets 358.7
85 *
86 * @sa READ @ref hue() const
87 * @sa WRITE @ref setHue()
88 * @sa NOTIFY @ref hueChanged()
89 *
90 * @internal
91 *
92 * The value gets normalized according
93 * to @ref PolarPointF::normalizedAngle360() */
94 Q_PROPERTY(qreal hue READ hue WRITE setHue NOTIFY hueChanged USER true)
95
96public:
97 Q_INVOKABLE explicit ColorWheel(const QSharedPointer<PerceptualColor::RgbColorSpace> &colorSpace, QWidget *parent = nullptr);
98 virtual ~ColorWheel() noexcept override;
99 /** @brief Getter for property @ref hue
100 * @returns the property @ref hue */
101 [[nodiscard]] qreal hue() const;
102 [[nodiscard]] virtual QSize minimumSizeHint() const override;
103 [[nodiscard]] virtual QSize sizeHint() const override;
104
105Q_SIGNALS:
106 /** @brief Notify signal for property @ref hue.
107 * @param newHue the new hue */
108 void hueChanged(const qreal newHue);
109
110public Q_SLOTS:
111 void setHue(const qreal newHue);
112
113protected:
114 virtual void keyPressEvent(QKeyEvent *event) override;
115 virtual void mouseMoveEvent(QMouseEvent *event) override;
116 virtual void mousePressEvent(QMouseEvent *event) override;
117 virtual void mouseReleaseEvent(QMouseEvent *event) override;
118 virtual void paintEvent(QPaintEvent *event) override;
119 virtual void resizeEvent(QResizeEvent *event) override;
120 virtual void wheelEvent(QWheelEvent *event) override;
121
122private:
123 Q_DISABLE_COPY(ColorWheel)
124
125 /** @internal
126 *
127 * @brief Declare the private implementation as friend class.
128 *
129 * This allows the private class to access the protected members and
130 * functions of instances of <em>this</em> class. */
131 friend class ColorWheelPrivate;
132 /** @brief Pointer to implementation (pimpl) */
133 ConstPropagatingUniquePointer<ColorWheelPrivate> d_pointer;
134
135 /** @internal @brief Only for unit tests. */
136 friend class TestColorWheel;
137
138 /** @internal
139 * @brief Internal friend declaration.
140 *
141 * This class is used as child class in @ref WheelColorPicker.
142 * There is a tight collaboration. */
143 friend class WheelColorPicker;
144 /** @internal
145 * @brief Internal friend declaration.
146 *
147 * This class is used as child class in @ref WheelColorPicker.
148 * There is a tight collaboration. */
149 friend class WheelColorPickerPrivate;
150};
151
152} // namespace PerceptualColor
153
154#endif // COLORWHEEL_H
Base class for LCH diagrams.
A color wheel widget.
Definition colorwheel.h:65
Complete wheel-based color picker widget.
This file provides support for C++ symbol import and export.
#define PERCEPTUALCOLOR_IMPORTEXPORT
A macro that either exports dynamic library symbols or imports dynamic library symbols or does nothin...
The namespace of this library.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:48:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.