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 | |
34 | class 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 | */ |
47 | class KDEUI_EXPORT KIconEffect |
48 | { |
49 | public: |
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 | |
217 | private: |
218 | KIconEffectPrivate* const d; |
219 | }; |
220 | |
221 | #endif |
222 | |