1/* vi: ts=8 sts=4 sw=4
2 *
3 * This file is part of the KDE project, module kdecore.
4 * Copyright (C) 2000 Geert Jansen <jansen@kde.org>
5 * Copyright (C) 2007 Daniel M. Duley <daniel.duley@verizon.net>
6 * with minor additions and based on ideas from
7 * Torsten Rahn <torsten@kde.org>
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Library General Public
11 * License version 2 as published by the Free Software Foundation.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
17 *
18 * You should have received a copy of the GNU Library General Public License
19 * along with this library; see the file COPYING.LIB. If not, write to
20 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
22 */
23
24#ifndef KICONEFFECT_H
25#define KICONEFFECT_H
26
27#include <kdeui_export.h>
28
29#include <QtGui/QImage>
30#include <QtGui/QPixmap>
31#include <QtGui/QColor>
32#include <QtCore/QRect>
33
34class KIconEffectPrivate;
35
36/**
37 * Applies effects to icons.
38 *
39 * This class applies effects to icons depending on their state and
40 * group. For example, it can be used to make all disabled icons
41 * in a toolbar gray.
42 *
43 * \image html kiconeffect-apply.png "Various Effects applied to an image"
44 *
45 * @see KIcon
46 */
47class KDEUI_EXPORT KIconEffect
48{
49public:
50 /**
51 * Create a new KIconEffect.
52 * You will most likely never have to use this to create a new KIconEffect
53 * yourself, as you can use the KIconEffect provided by the global KIconLoader
54 * (which itself is accessible by KIconLoader::global()) through its
55 * iconEffect() function.
56 */
57 KIconEffect();
58 ~KIconEffect();
59
60 /**
61 * This is the enumeration of all possible icon effects.
62 * Note that 'LastEffect' is no valid icon effect but only
63 * used internally to check for invalid icon effects.
64 *
65 * @li NoEffect: Don't apply any icon effect
66 * @li ToGray: Tints the icon gray
67 * @li Colorize: Tints the icon with an other color
68 * @li ToGamma: Change the gamma value of the icon
69 * @li DeSaturate: Reduce the saturation of the icon
70 * @li ToMonochrome: Produces a monochrome icon
71 */
72 enum Effects { NoEffect, ToGray, Colorize, ToGamma, DeSaturate,
73 ToMonochrome,
74 LastEffect };
75
76 /**
77 * Rereads configuration.
78 */
79 void init();
80
81 /**
82 * Tests whether an effect has been configured for the given icon group.
83 * @param group the group to check, see KIconLoader::Group
84 * @param state the state to check, see KIconLoader::States
85 * @returns true if an effect is configured for the given @p group
86 * in @p state, otherwise false.
87 * @see KIconLoader::Group
88 * KIconLoader::States
89 */
90 bool hasEffect(int group, int state) const;
91
92 /**
93 * Returns a fingerprint for the effect by encoding
94 * the given @p group and @p state into a QString. This
95 * is useful for caching.
96 * @param group the group, see KIconLoader::Group
97 * @param state the state, see KIconLoader::States
98 * @return the fingerprint of the given @p group+@p state
99 */
100 QString fingerprint(int group, int state) const;
101
102 /**
103 * Applies an effect to an image. The effect to apply depends on the
104 * @p group and @p state parameters, and is configured by the user.
105 * @param src The image.
106 * @param group The group for the icon, see KIconLoader::Group
107 * @param state The icon's state, see KIconLoader::States
108 * @return An image with the effect applied.
109 */
110 QImage apply(const QImage &src, int group, int state) const;
111
112 /**
113 * Applies an effect to an image.
114 * @param src The image.
115 * @param effect The effect to apply, one of KIconEffect::Effects.
116 * @param value Strength of the effect. 0 <= @p value <= 1.
117 * @param rgb Color parameter for effects that need one.
118 * @param trans Add Transparency if trans = true.
119 * @return An image with the effect applied.
120 */
121 QImage apply(const QImage &src, int effect, float value, const QColor &rgb, bool trans) const;
122 QImage apply(const QImage &src, int effect, float value, const QColor &rgb, const QColor &rgb2, bool trans) const;
123
124 /**
125 * Applies an effect to a pixmap.
126 * @param src The pixmap.
127 * @param group The group for the icon, see KIconLoader::Group
128 * @param state The icon's state, see KIconLoader::States
129 * @return A pixmap with the effect applied.
130 */
131 QPixmap apply(const QPixmap &src, int group, int state) const;
132
133 /**
134 * Applies an effect to a pixmap.
135 * @param src The pixmap.
136 * @param effect The effect to apply, one of KIconEffect::Effects.
137 * @param value Strength of the effect. 0 <= @p value <= 1.
138 * @param rgb Color parameter for effects that need one.
139 * @param trans Add Transparency if trans = true.
140 * @return A pixmap with the effect applied.
141 */
142 QPixmap apply(const QPixmap &src, int effect, float value, const QColor &rgb, bool trans) const;
143 QPixmap apply(const QPixmap &src, int effect, float value, const QColor &rgb, const QColor &rgb2, bool trans) const;
144
145 /**
146 * Returns an image twice as large, consisting of 2x2 pixels.
147 * @param src the image.
148 * @return the scaled image.
149 */
150 QImage doublePixels(const QImage &src) const;
151
152 /**
153 * Tints an image gray.
154 *
155 * @param image The image
156 * @param value Strength of the effect. 0 <= @p value <= 1
157 */
158 static void toGray(QImage &image, float value);
159
160 /**
161 * Colorizes an image with a specific color.
162 *
163 * @param image The image
164 * @param col The color with which the @p image is tinted
165 * @param value Strength of the effect. 0 <= @p value <= 1
166 */
167 static void colorize(QImage &image, const QColor &col, float value);
168
169 /**
170 * Produces a monochrome icon with a given foreground and background color
171 *
172 * @param image The image
173 * @param white The color with which the white parts of @p image are painted
174 * @param black The color with which the black parts of @p image are painted
175 * @param value Strength of the effect. 0 <= @p value <= 1
176 */
177 static void toMonochrome(QImage &image, const QColor &black, const QColor &white, float value);
178
179 /**
180 * Desaturates an image.
181 *
182 * @param image The image
183 * @param value Strength of the effect. 0 <= @p value <= 1
184 */
185 static void deSaturate(QImage &image, float value);
186
187 /**
188 * Changes the gamma value of an image.
189 *
190 * @param image The image
191 * @param value Strength of the effect. 0 <= @p value <= 1
192 */
193 static void toGamma(QImage &image, float value);
194
195 /**
196 * Renders an image semi-transparent.
197 *
198 * @param image The image
199 */
200 static void semiTransparent(QImage &image);
201
202 /**
203 * Renders a pixmap semi-transparent.
204 *
205 * @param pixmap The pixmap
206 */
207 static void semiTransparent(QPixmap &pixmap);
208
209 /**
210 * Overlays an image with an other image.
211 *
212 * @param src The image
213 * @param overlay The image to overlay @p src with
214 */
215 static void overlay(QImage &src, QImage &overlay);
216
217private:
218 KIconEffectPrivate* const d;
219};
220
221#endif
222