1/* This file is part of the KDE project
2 * Copyright (C) 2007 Matthew Woehlke <mw_triad@users.sourceforge.net>
3 * Copyright (C) 2007 Thomas Zander <zander@kde.org>
4 * Copyright (C) 2007 Zack Rusin <zack@kde.org>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public License
17 * along with this library; see the file COPYING.LIB. If not, write to
18 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22#ifndef KCOLORUTILS_H
23#define KCOLORUTILS_H
24
25#include <kdeui_export.h>
26#include <QtGui/QPainter>
27
28class QColor;
29
30/**
31 * A set of methods used to work with colors.
32 */
33namespace KColorUtils {
34 /**
35 * Calculate the luma of a color. Luma is weighted sum of gamma-adjusted
36 * R'G'B' components of a color. The result is similar to qGray. The range
37 * is from 0.0 (black) to 1.0 (white).
38 *
39 * KColorUtils::darken(), KColorUtils::lighten() and KColorUtils::shade()
40 * operate on the luma of a color.
41 *
42 * @see http://en.wikipedia.org/wiki/Luma_(video)
43 */
44 KDEUI_EXPORT qreal luma(const QColor&);
45
46 /**
47 * Calculate the contrast ratio between two colors, according to the
48 * W3C/WCAG2.0 algorithm, (Lmax + 0.05)/(Lmin + 0.05), where Lmax and Lmin
49 * are the luma values of the lighter color and the darker color,
50 * respectively.
51 *
52 * A contrast ration of 5:1 (result == 5.0) is the minimum for "normal"
53 * text to be considered readable (large text can go as low as 3:1). The
54 * ratio ranges from 1:1 (result == 1.0) to 21:1 (result == 21.0).
55 *
56 * @see KColorUtils::luma
57 */
58 KDEUI_EXPORT qreal contrastRatio(const QColor&, const QColor&);
59
60 /**
61 * Adjust the luma of a color by changing its distance from white.
62 *
63 * @li amount == 1.0 gives white
64 * @li amount == 0.5 results in a color whose luma is halfway between 1.0
65 * and that of the original color
66 * @li amount == 0.0 gives the original color
67 * @li amount == -1.0 gives a color that is 'twice as far from white' as
68 * the original color, that is luma(result) == 1.0 - 2*(1.0 - luma(color))
69 *
70 * @param amount factor by which to adjust the luma component of the color
71 * @param chromaInverseGain (optional) factor by which to adjust the chroma
72 * component of the color; 1.0 means no change, 0.0 maximizes chroma
73 * @see KColorUtils::shade
74 */
75 KDEUI_EXPORT QColor lighten(const QColor&, qreal amount = 0.5, qreal chromaInverseGain = 1.0);
76
77 /**
78 * Adjust the luma of a color by changing its distance from black.
79 *
80 * @li amount == 1.0 gives black
81 * @li amount == 0.5 results in a color whose luma is halfway between 0.0
82 * and that of the original color
83 * @li amount == 0.0 gives the original color
84 * @li amount == -1.0 gives a color that is 'twice as far from black' as
85 * the original color, that is luma(result) == 2*luma(color)
86 *
87 * @param amount factor by which to adjust the luma component of the color
88 * @param chromaGain (optional) factor by which to adjust the chroma
89 * component of the color; 1.0 means no change, 0.0 minimizes chroma
90 * @see KColorUtils::shade
91 */
92 KDEUI_EXPORT QColor darken(const QColor&, qreal amount = 0.5, qreal chromaGain = 1.0);
93
94 /**
95 * Adjust the luma and chroma components of a color. The amount is added
96 * to the corresponding component.
97 *
98 * @param lumaAmount amount by which to adjust the luma component of the
99 * color; 0.0 results in no change, -1.0 turns anything black, 1.0 turns
100 * anything white
101 * @param chromaAmount (optional) amount by which to adjust the chroma
102 * component of the color; 0.0 results in no change, -1.0 minimizes chroma,
103 * 1.0 maximizes chroma
104 * @see KColorUtils::luma
105 */
106 KDEUI_EXPORT QColor shade(const QColor&, qreal lumaAmount, qreal chromaAmount = 0.0);
107
108 /**
109 * Create a new color by tinting one color with another. This function is
110 * meant for creating additional colors withing the same class (background,
111 * foreground) from colors in a different class. Therefore when @p amount
112 * is low, the luma of @p base is mostly preserved, while the hue and
113 * chroma of @p color is mostly inherited.
114 *
115 * @param base color to be tinted
116 * @param color color with which to tint
117 * @param amount how strongly to tint the base; 0.0 gives @p base,
118 * 1.0 gives @p color
119 */
120 KDEUI_EXPORT QColor tint(const QColor &base, const QColor &color, qreal amount = 0.3);
121
122 /**
123 * Blend two colors into a new color by linear combination.
124 * @code
125 QColor lighter = KColorUtils::mix(myColor, Qt::white)
126 * @endcode
127 * @param c1 first color.
128 * @param c2 second color.
129 * @param bias weight to be used for the mix. @p bias <= 0 gives @p c1,
130 * @p bias >= 1 gives @p c2. @p bias == 0.5 gives a 50% blend of @p c1
131 * and @p c2.
132 */
133 KDEUI_EXPORT QColor mix(const QColor &c1, const QColor &c2,
134 qreal bias = 0.5);
135
136 /**
137 * Blend two colors into a new color by painting the second color over the
138 * first using the specified composition mode.
139 * @code
140 QColor white(Qt::white);
141 white.setAlphaF(0.5);
142 QColor lighter = KColorUtils::overlayColors(myColor, white);
143 @endcode
144 * @param base the base color (alpha channel is ignored).
145 * @param paint the color to be overlayed onto the base color.
146 * @param comp the CompositionMode used to do the blending.
147 */
148 KDEUI_EXPORT QColor overlayColors(const QColor &base, const QColor &paint,
149 QPainter::CompositionMode comp = QPainter::CompositionMode_SourceOver);
150
151}
152
153#endif // KCOLORUTILS_H
154// kate: space-indent on; indent-width 4; replace-tabs on; auto-insert-doxygen on;
155