Perceptual Color

colorpatch.h
1// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
2// SPDX-License-Identifier: BSD-2-Clause OR MIT
3
4#ifndef COLORPATCH_H
5#define COLORPATCH_H
6
7#include "abstractdiagram.h"
8#include "constpropagatinguniquepointer.h"
9#include "importexport.h"
10#include <qcolor.h>
11#include <qglobal.h>
12#include <qsize.h>
13class QDragEnterEvent;
14class QDropEvent;
15class QMouseEvent;
16class QResizeEvent;
17class QWidget;
18
19#if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
20#include <qtmetamacros.h>
21#else
22#include <qobjectdefs.h>
23#include <qstring.h>
24class QObject;
25#endif
26
27namespace PerceptualColor
28{
29class ColorPatchPrivate;
30
31/** @brief A color display widget.
32 *
33 * This widget simply displays a color. And it provides drag-and-drop support;
34 * it emits also @ref colorChanged on drop events if the color has changed.
35 * Useful for showing a given color. The instantiation and usage is simple.
36 * Example:
37 * @snippet testcolorpatch.cpp ColorPatch Create widget
38 *
39 * @image html ColorPatch.png "ColorPatch" width=50
40 *
41 * This widget is also able to display transparency (the pattern will be
42 * mirrored on right-to-left layouts):
43 *
44 * @image html ColorPatchSemiTransparent.png "ColorPatch with 50% transparency" width=50
45 *
46 * There is also a simple representation
47 * for <tt>QColor::isValid() == false</tt>:
48 *
49 * @image html ColorPatchInvalid.png "ColorPatch with invalid color" width=50
50 *
51 * The default minimum size of this widget is similar to a
52 * <tt>QToolButton</tt>. Depending on your use case, you might
53 * set a bigger minimum size:
54 * @snippet testcolorpatch.cpp ColorPatch Bigger minimum size
55 *
56 * This class’s API is similar to KColorPatch’s API.
57 *
58 * @internal
59 *
60 * @note A similar functionality is available as KColorPatch, but this is
61 * part of KDELibs4Support which is available in KF5 but should not be used
62 * for new code, but only for legacy code. Also, depending on KDELibs4Support
63 * would pull-in another dependency. Furthermore, KColorPatch has support for
64 * drag-and-drop, which is not desirable for our use case. Therefore, with
65 * @ref ColorPatch there is a lightweight alternative (that, by the way,
66 * implements the full API of KColorPatch).
67 *
68 * @note This class intentionally does not reimplement the paint event,
69 * but uses a child QLabel to display the color. QLabel integrates by
70 * default nicely with QStyle: Even round frames that are cutting slightly
71 * the pixmap (like in the Breeze style), are possible. So we rely entirely
72 * on QLabel for the actual display, and only implement @ref sizeHint() and
73 * @ref minimumSizeHint() ourselves. */
75{
76 Q_OBJECT
77
78 /** @brief The color that is displayed
79 *
80 * Default value is an invalid color.
81 *
82 * - If the color is invalid, nothing is displayed. The frame is empty:
83 * Only the default widget background is visible within the frame.
84 * - If the color is valid, the widget frame is filled with this color.
85 * If this color is not fully opaque, the background behind the color
86 * will be a special background pattern (and <em>not</em> the default
87 * widget background).
88 *
89 * @note No color management is applied. The color is used as-is to
90 * paint on the canvas provided by the operation system.
91 *
92 * @sa @ref color() const
93 * @sa @ref setColor()
94 * @sa @ref colorChanged() */
95 Q_PROPERTY(QColor color READ color WRITE setColor NOTIFY colorChanged)
96
97public:
98 Q_INVOKABLE explicit ColorPatch(QWidget *parent = nullptr);
99 virtual ~ColorPatch() noexcept override;
100 /** @brief Getter for property @ref color
101 * @returns the property @ref color */
102 [[nodiscard]] QColor color() const;
103 [[nodiscard]] virtual QSize minimumSizeHint() const override;
104 [[nodiscard]] virtual QSize sizeHint() const override;
105
106public Q_SLOTS:
107 void setColor(const QColor &newColor);
108
109Q_SIGNALS:
110 /** @brief Notify signal for property @ref color.
111 *
112 * @param color the new color */
113 void colorChanged(const QColor &color);
114
115protected:
116 virtual void dragEnterEvent(QDragEnterEvent *event) override;
117 virtual void dropEvent(QDropEvent *event) override;
118 virtual void mouseMoveEvent(QMouseEvent *event) override;
119 virtual void mousePressEvent(QMouseEvent *event) override;
120 virtual void resizeEvent(QResizeEvent *event) override;
121
122private:
123 Q_DISABLE_COPY(ColorPatch)
124
125 /** @internal
126 * @brief Declare the private implementation as friend class.
127 *
128 * This allows the private class to access the protected members and
129 * functions of instances of <em>this</em> class. */
130 friend class ColorPatchPrivate;
131 /** @brief Pointer to implementation (pimpl) */
132 ConstPropagatingUniquePointer<ColorPatchPrivate> d_pointer;
133
134 /** @internal @brief Only for unit tests. */
135 friend class TestColorPatch;
136};
137
138} // namespace PerceptualColor
139
140#endif // COLORPATCH_H
Base class for LCH diagrams.
A color display widget.
Definition colorpatch.h:75
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.