Perceptual Color

rgbcolor.h
1// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
2// SPDX-License-Identifier: BSD-2-Clause OR MIT
3
4#ifndef RGBCOLOR_H
5#define RGBCOLOR_H
6
7#include "genericcolor.h"
8#include <optional>
9#include <qcolor.h>
10#include <qdebug.h>
11
12namespace PerceptualColor
13{
14
15/** @internal
16 *
17 * @brief An RGB color stored in multiple different RGB transformations.
18 *
19 * Unlike <tt>QColor</tt> (which is essentially a C++ <tt>union</tt> of
20 * different color formats, so only one of them is actually saved),
21 * @ref RgbColor <em>actually</em> stores <em>all</em> available color
22 * transformations.
23 *
24 * This data type is just an (ugly) implementation detail of @ref ColorDialog.
25 * For simplicity, data members are accessible directly, without write
26 * protection. Usage: Create instances of this class with one of the static
27 * factory functions, and assign them to <tt>const</tt> variables. The factory
28 * functions guarantee that all data members have correct values representing
29 * the <em>same</em> color.
30 *
31 * Changes to some values of some color formats under certain
32 * circumstances do not change the color:
33 * - HSL saturation: When the color is either black (L = 0%) or
34 * white (L = 100%).
35 * - HSV/HSB saturation: When the color is black (V/B = 0%).
36 *
37 * The color conversion of this class provides meaningful and predictable
38 * <em>HSL-saturation</em> and <em>HSV-saturation</em> values.
39 *
40 * This data type can be passed to QDebug thanks to
41 * @ref operator<<(QDebug dbg, const PerceptualColor::RgbColor &value)
42 *
43 * @sa @ref AbsoluteColor */
44class RgbColor final
45{
46public:
47 [[nodiscard]] static RgbColor fromHsl(const GenericColor &color);
48 [[nodiscard]] static RgbColor fromHsv(const GenericColor &color);
49 [[nodiscard]] static RgbColor fromHwb(const GenericColor &color);
50 [[nodiscard]] static RgbColor fromRgb255(const GenericColor &color, std::optional<double> hue = std::optional<double>());
51 [[nodiscard]] static RgbColor fromRgbQColor(const QColor &color);
52
53 /** @brief Constructor for an uninitialized object.
54 *
55 * This constructor is quite useless except for declaring variables
56 * of this type. Use the static functions to get an actual color object.
57 *
58 * @warning As the data members are uninitialized, this implies that the
59 * count of <tt>QList</tt> items is not correct! */
60 RgbColor();
61 /** @brief Default copy constructor
62 * @param other the object to copy */
63 RgbColor(const RgbColor &other) = default;
64 /** @brief Default copy assignment operator
65 * @param other the object to copy
66 * @returns The default implementation’s return value. */
67 RgbColor &operator=(const RgbColor &other) = default;
68 // NOTE About move constructor and move assignment operator:
69 // Declaring them with “= default” will create a compiler-generated
70 // implementation that, apparently, does not copy correctly
71 // the data members of type QList. Using “=delete” however
72 // will create a move constructor that it forbidden to be used.
73 // When some code needs a move constructor, the overload resolution
74 // will choose this move constructor, and the compilation fails
75 // because it is forbidden to be used. For details on this behaviour,
76 // see https://blog.knatten.org/2021/10/15/ Therefore, we do not declare
77 // the move constructor at all: Because the copy constructor exists, the
78 // move constructor will not be generated implicitly at all. When some
79 // code needs a move constructor, the overload resolution does not find
80 // one and falls back to the copy constructor (which is the default
81 // implementation, but apparently works correctly also for QList members).
82 // RgbColor &operator=(RgbColor &&other) noexcept = default;
83 // RgbColor(RgbColor &&other) noexcept = default;
84
85 [[nodiscard]] bool operator==(const RgbColor &other) const;
86
87 /** @brief HWB representation.
88 *
89 * Range: [0, 360], [0, 100], [0, 100] */
90 GenericColor hwb;
91 /** @brief HSL representation.
92 *
93 * Range: [0, 360], [0, 100], [0, 100] */
94 GenericColor hsl;
95 /** @brief HSV representation.
96 *
97 * Range: [0, 360], [0, 100], [0, 100] */
98 GenericColor hsv;
99 /** @brief RGB representation.
100 *
101 * Range: [0, 255] */
102 GenericColor rgb255;
103 /** @brief QColor representation.
104 *
105 * <tt>QColor::spec()</tt> is <tt>QColor::Rgb</tt>. */
106 QColor rgbQColor;
107
108private:
109 void fillAll(QColor color, std::optional<double> hue);
110};
111
112QDebug operator<<(QDebug dbg, const PerceptualColor::RgbColor &value);
113
114} // namespace PerceptualColor
115
116#endif // RGBCOLOR_H
KTEXTEDITOR_EXPORT QDebug operator<<(QDebug s, const MovingCursor &cursor)
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.