1/* This file is part of the KDE project
2 SPDX-FileCopyrightText: 2007 Matthew Woehlke <mw_triad@users.sourceforge.net>
3 SPDX-FileCopyrightText: 2007 Thomas Zander <zander@kde.org>
4 SPDX-FileCopyrightText: 2007 Zack Rusin <zack@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KCOLORUTILS_H
10#define KCOLORUTILS_H
11
12#include <kguiaddons_export.h>
13
14#include <QPainter>
15
16class QColor;
17
18// TODO KF7: turn this into a Q_GADGET class with static members to avoid the need for the KColorUtilsSingleton QML wrapper
19
20/*!
21 * \namespace KColorUtils
22 * \inmodule KGuiAddons
23 *
24 * \brief A set of methods used to work with colors.
25 */
26namespace KColorUtils
27{
28/*!
29 * Calculate the hue of a color. The range is from 0.0 (red) to almost 1.0 (slightly blue-ish red).
30 *
31 * The result is computed in linear (not sRGB) color space and may differ slightly from QColor::hue().
32 *
33 * \sa https://en.wikipedia.org/wiki/Hue
34 * \since 5.68
35 */
36KGUIADDONS_EXPORT qreal hue(const QColor &);
37
38/*!
39 * Calculate the chroma of a color. The range is from 0.0 (none) to 1.0 (full).
40 *
41 * The result is computed in linear (not sRGB) color space.
42 *
43 * \sa https://en.wikipedia.org/wiki/Colorfulness
44 * \since 5.68
45 */
46KGUIADDONS_EXPORT qreal chroma(const QColor &);
47
48/*!
49 * Calculate the luma of a color. Luma is weighted sum of gamma-adjusted
50 * R'G'B' components of a color. The result is similar to qGray. The range
51 * is from 0.0 (black) to 1.0 (white).
52 *
53 * The result is computed in linear (not sRGB) color space.
54 *
55 * KColorUtils::darken(), KColorUtils::lighten() and KColorUtils::shade()
56 * operate on the luma of a color.
57 *
58 * \sa http://en.wikipedia.org/wiki/Luma_(video)
59 */
60KGUIADDONS_EXPORT qreal luma(const QColor &);
61
62/*!
63 * Calculate hue, chroma and luma of a color in one call.
64 *
65 * The range of hue is from 0.0 (red) to almost 1.0 (slightly blue-ish red).
66 * The range of chroma is from 0.0 (none) to 1.0 (full).
67 * The range of luma is from 0.0 (black) to 1.0 (white).
68 *
69 * The hue, chroma and luma values are computed in linear (not sRGB) color space.
70 *
71 * \since 5.0
72 */
73KGUIADDONS_EXPORT void getHcy(const QColor &, qreal *hue, qreal *chroma, qreal *luma, qreal *alpha = nullptr);
74
75/*!
76 * Return a QColor based on the given hue, chroma, luma and alpha values.
77 *
78 * The range of hue is cyclical. For example, 0.0 and 1.0 are both red while -0.166667 and 0.833333 are both magenta.
79 * The range of chroma is from 0.0 (none) to 1.0 (full). Out of range values will be clamped.
80 * The range of luma is from 0.0 (black) to 1.0 (white). Out of range values will be clamped.
81 *
82 * The hue, chroma and luma values are computed in linear (not sRGB) color space.
83 *
84 * \since 5.68
85 */
86KGUIADDONS_EXPORT QColor hcyColor(qreal hue, qreal chroma, qreal luma, qreal alpha = 1.0);
87
88/*!
89 * Calculate the contrast ratio between two colors, according to the
90 * W3C/WCAG2.0 algorithm, (Lmax + 0.05)/(Lmin + 0.05), where Lmax and Lmin
91 * are the luma values of the lighter color and the darker color,
92 * respectively.
93 *
94 * A contrast ration of 5:1 (result == 5.0) is the minimum for "normal"
95 * text to be considered readable (large text can go as low as 3:1). The
96 * ratio ranges from 1:1 (result == 1.0) to 21:1 (result == 21.0).
97 *
98 * \sa KColorUtils::luma
99 */
100KGUIADDONS_EXPORT qreal contrastRatio(const QColor &, const QColor &);
101
102/*!
103 * Adjust the luma of a color by changing its distance from white.
104 *
105 * \list
106 * \li amount == 1.0 gives white
107 * \li amount == 0.5 results in a color whose luma is halfway between 1.0
108 * and that of the original color
109 * \li amount == 0.0 gives the original color
110 * \li amount == -1.0 gives a color that is 'twice as far from white' as
111 * the original color, that is luma(result) == 1.0 - 2*(1.0 - luma(color))
112 * \endlist
113 *
114 * \a amount factor by which to adjust the luma component of the color
115 *
116 * \a chromaInverseGain (optional) factor by which to adjust the chroma
117 * component of the color; 1.0 means no change, 0.0 maximizes chroma
118 *
119 * \sa KColorUtils::shade
120 */
121KGUIADDONS_EXPORT QColor lighten(const QColor &, qreal amount = 0.5, qreal chromaInverseGain = 1.0);
122
123/*!
124 * Adjust the luma of a color by changing its distance from black.
125 *
126 * \list
127 * \li amount == 1.0 gives black
128 * \li amount == 0.5 results in a color whose luma is halfway between 0.0
129 * and that of the original color
130 * \li amount == 0.0 gives the original color
131 * \li amount == -1.0 gives a color that is 'twice as far from black' as
132 * the original color, that is luma(result) == 2*luma(color)
133 * \endlist
134 *
135 * \a amount factor by which to adjust the luma component of the color
136 * \a chromaGain (optional) factor by which to adjust the chroma
137 * component of the color; 1.0 means no change, 0.0 minimizes chroma
138 * \sa KColorUtils::shade
139 */
140KGUIADDONS_EXPORT QColor darken(const QColor &, qreal amount = 0.5, qreal chromaGain = 1.0);
141
142/*!
143 * Adjust the luma and chroma components of a color. The amount is added
144 * to the corresponding component.
145 *
146 * \a lumaAmount amount by which to adjust the luma component of the
147 * color; 0.0 results in no change, -1.0 turns anything black, 1.0 turns
148 * anything white
149 *
150 * \a chromaAmount (optional) amount by which to adjust the chroma
151 * component of the color; 0.0 results in no change, -1.0 minimizes chroma,
152 * 1.0 maximizes chroma
153 *
154 * \sa KColorUtils::luma
155 */
156KGUIADDONS_EXPORT QColor shade(const QColor &, qreal lumaAmount, qreal chromaAmount = 0.0);
157
158/*!
159 * Create a new color by tinting one color with another. This function is
160 * meant for creating additional colors withings the same class (background,
161 * foreground) from colors in a different class. Therefore when \a amount
162 * is low, the luma of \a base is mostly preserved, while the hue and
163 * chroma of \a color is mostly inherited.
164 *
165 * \a base color to be tinted
166 *
167 * \a color color with which to tint
168 *
169 * \a amount how strongly to tint the base; 0.0 gives @p base,
170 * 1.0 gives @p color
171 */
172KGUIADDONS_EXPORT QColor tint(const QColor &base, const QColor &color, qreal amount = 0.3);
173
174/*!
175 * Blend two colors into a new color by linear combination.
176 * \code
177 * QColor lighter = KColorUtils::mix(myColor, Qt::white)
178 * \endcode
179 *
180 * \a c1 first color.
181 *
182 * \a c2 second color.
183 *
184 * \a bias weight to be used for the mix. \a bias <= 0 gives \a c1,
185 *
186 * \a bias >= 1 gives \a c2. \a bias == 0.5 gives a 50% blend of \a c1
187 * and \a c2.
188 */
189KGUIADDONS_EXPORT QColor mix(const QColor &c1, const QColor &c2, qreal bias = 0.5);
190
191/*!
192 * Blend two colors into a new color by painting the second color over the
193 * first using the specified composition mode.
194 * \code
195 * QColor white(Qt::white);
196 * white.setAlphaF(0.5);
197 * QColor lighter = KColorUtils::overlayColors(myColor, white);
198 * \endcode
199 *
200 * \a base the base color (alpha channel is ignored).
201 *
202 * \a paint the color to be overlaid onto the base color.
203 *
204 * \a comp the CompositionMode used to do the blending.
205 */
206KGUIADDONS_EXPORT QColor overlayColors(const QColor &base, const QColor &paint, QPainter::CompositionMode comp = QPainter::CompositionMode_SourceOver);
207}
208
209#endif // KCOLORUTILS_H
210

source code of kguiaddons/src/colors/kcolorutils.h