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

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