1/*
2
3 This file is part of the KDE project, module kdecore.
4 SPDX-FileCopyrightText: 2000 Geert Jansen <jansen@kde.org>
5 SPDX-FileCopyrightText: 2007 Daniel M. Duley <daniel.duley@verizon.net>
6
7 with minor additions and based on ideas from
8 SPDX-FileContributor: Torsten Rahn <torsten@kde.org>
9
10 SPDX-License-Identifier: LGPL-2.0-only
11*/
12
13#ifndef KICONEFFECT_H
14#define KICONEFFECT_H
15
16#include <kiconthemes_export.h>
17
18#include <QColor>
19#include <QImage>
20#include <QPixmap>
21
22#include <memory>
23
24class KIconEffectPrivate;
25
26/*!
27 * \class KIconEffect
28 * \inmodule KIconThemes
29 *
30 * \brief Applies effects to icons.
31 *
32 * This class applies effects to icons depending on their state and
33 * group. For example, it can be used to make all disabled icons
34 * in a toolbar gray.
35 *
36 * \image kiconeffect-apply.png "Various Effects applied to an image"
37 *
38 * \sa QIcon::fromTheme
39 */
40class KICONTHEMES_EXPORT KIconEffect
41{
42public:
43#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
44 /*!
45 * Create a new KIconEffect.
46 * You will most likely never have to use this to create a new KIconEffect
47 * yourself, as you can use the KIconEffect provided by the global KIconLoader
48 * (which itself is accessible by KIconLoader::global()) through its
49 * iconEffect() function.
50 *
51 * \deprecated[6.5] use the static API
52 */
53 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
54 KIconEffect();
55#endif
56 ~KIconEffect();
57
58 KIconEffect(const KIconEffect &) = delete;
59 KIconEffect &operator=(const KIconEffect &) = delete;
60
61#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
62 /*!
63 * This is the enumeration of all possible icon effects.
64 *
65 * \value NoEffect Do not apply any icon effect
66 * \value ToGray Tints the icon gray
67 * \value Colorize Tints the icon with a specific color
68 * \value ToGamma Change the gamma value of the icon
69 * \value DeSaturate Reduce the saturation of the icon
70 * \value ToMonochrome Produces a monochrome icon
71 * \omitvalue LastEffect
72 *
73 * \deprecated[6.5] use the static API
74 */
75 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
76 enum Effects {
77 NoEffect,
78 ToGray,
79 Colorize,
80 ToGamma,
81 DeSaturate,
82 ToMonochrome,
83 LastEffect,
84 };
85#endif
86
87#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
88 /*!
89 * Rereads configuration.
90 *
91 * \deprecated[6.5] use the static API
92 */
93 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
94 void init();
95#endif
96
97#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
98 /*!
99 * Tests whether an effect has been configured for the given icon group.
100 *
101 * \a group the group to check, see KIconLoader::Group
102 *
103 * \a state the state to check, see KIconLoader::States
104 *
105 * Returns true if an effect is configured for the given \a group
106 * in \a state, otherwise false.
107 *
108 * \sa KIconLoader::Group, KIconLoader::States
109 *
110 * \deprecated [6.5] use the static API
111 */
112 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
113 bool hasEffect(int group, int state) const;
114#endif
115
116#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
117 /*!
118 * Returns a fingerprint for the effect by encoding
119 * the given \a group and \a state into a QString.
120 *
121 * This is useful for caching.
122 *
123 * \a group the group, see KIconLoader::Group
124 *
125 * \a state the state, see KIconLoader::States
126 *
127 * Returns the fingerprint of the given \a group + \a state
128 *
129 * \deprecated[6.5] use the static API
130 */
131 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
132 QString fingerprint(int group, int state) const;
133#endif
134
135#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
136 /*!
137 * Applies an effect to an image. The effect to apply depends on the
138 * \a group and \a state parameters, and is configured by the user.
139 *
140 * \a src The image.
141 *
142 * \a group The group for the icon, see KIconLoader::Group
143 *
144 * \a state The icon's state, see KIconLoader::States
145 *
146 * Returns An image with the effect applied.
147 *
148 * \deprecated[6.5] use the static API
149 */
150 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
151 QImage apply(const QImage &src, int group, int state) const;
152#endif
153
154#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
155 /*!
156 * Applies an effect to an image.
157 *
158 * \a src The image.
159 *
160 * \a effect The effect to apply, one of KIconEffect::Effects.
161 *
162 * \a value Strength of the effect. 0 <= \a value <= 1.
163 *
164 * \a rgb Color parameter for effects that need one.
165 *
166 * \a trans Add Transparency if trans = true.
167 *
168 * Returns An image with the effect applied.
169 *
170 * \deprecated[6.5] use the static API
171 */
172 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
173 QImage apply(const QImage &src, int effect, float value, const QColor &rgb, bool trans) const;
174
175 /*!
176 * Applies an effect to an image.
177 *
178 * \a src The image.
179 *
180 * \a effect The effect to apply, one of KIconEffect::Effects.
181 *
182 * \a value Strength of the effect. 0 <= \a value <= 1.
183 *
184 * \a rgb Color parameter for effects that need one.
185 *
186 * \a trans Add Transparency if trans = true.
187 *
188 * Returns An image with the effect applied.
189 *
190 * \deprecated[6.5] use the static API
191 */
192 QImage apply(const QImage &src, int effect, float value, const QColor &rgb, const QColor &rgb2, bool trans) const;
193#endif
194
195#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
196 /*!
197 * Applies an effect to a pixmap.
198 *
199 * \a src The pixmap.
200 *
201 * \a group The group for the icon, see KIconLoader::Group
202 *
203 * \a state The icon's state, see KIconLoader::States
204 *
205 * Returns A pixmap with the effect applied.
206 *
207 * \deprecated[6.5] use the static API
208 */
209 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
210 QPixmap apply(const QPixmap &src, int group, int state) const;
211#endif
212
213#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
214 /*!
215 * Applies an effect to a pixmap.
216 *
217 * \a src The pixmap.
218 *
219 * \a effect The effect to apply, one of KIconEffect::Effects.
220 *
221 * \a value Strength of the effect. 0 <= \a value <= 1.
222 *
223 * \a rgb Color parameter for effects that need one.
224 *
225 * \a trans Add Transparency if trans = true.
226 *
227 * Returns A pixmap with the effect applied.
228 *
229 * \deprecated[6.5] use the static API
230 */
231 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
232 QPixmap apply(const QPixmap &src, int effect, float value, const QColor &rgb, bool trans) const;
233
234 /*!
235 * Applies an effect to a pixmap.
236 *
237 * \a src The pixmap.
238 *
239 * \a effect The effect to apply, one of KIconEffect::Effects.
240 *
241 * \a value Strength of the effect. 0 <= \a value <= 1.
242 *
243 * \a rgb Color parameter for effects that need one.
244 *
245 * \a trans Add Transparency if trans = true.
246 *
247 * Returns A pixmap with the effect applied.
248 *
249 * \deprecated[6.5] use the static API
250 */
251 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
252 QPixmap apply(const QPixmap &src, int effect, float value, const QColor &rgb, const QColor &rgb2, bool trans) const;
253#endif
254
255#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
256 /*!
257 * Returns an image twice as large, consisting of 2x2 pixels.
258 *
259 * \a src the image.
260 *
261 * Returns the scaled image.
262 *
263 * \deprecated [6.5] use the static API
264 */
265 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static API")
266 QImage doublePixels(const QImage &src) const;
267#endif
268
269 /*!
270 * Tints an image gray.
271 *
272 * \a image The image
273 *
274 * \a value Strength of the effect. 0 <= \a value <= 1
275 */
276 static void toGray(QImage &image, float value);
277
278 /*!
279 * Colorizes an image with a specific color.
280 *
281 * \a image The image
282 *
283 * \a col The color with which the \a image is tinted
284 *
285 * \a value Strength of the effect. 0 <= \a value <= 1
286 */
287 static void colorize(QImage &image, const QColor &col, float value);
288
289 /*!
290 * Produces a monochrome icon with a given foreground and background color
291 *
292 * \a image The image
293 *
294 * \a white The color with which the white parts of \a image are painted
295 *
296 * \a black The color with which the black parts of \a image are painted
297 *
298 * \a value Strength of the effect. 0 <= \a value <= 1
299 */
300 static void toMonochrome(QImage &image, const QColor &black, const QColor &white, float value);
301
302 /*!
303 * Desaturates an image.
304 *
305 * \a image The image
306 *
307 * \a value Strength of the effect. 0 <= \a value <= 1
308 */
309 static void deSaturate(QImage &image, float value);
310
311 /*!
312 * Changes the gamma value of an image.
313 *
314 * \a image The image
315 *
316 * \a value Strength of the effect. 0 <= \a value <= 1
317 */
318 static void toGamma(QImage &image, float value);
319
320 /*!
321 * Renders an image semi-transparent.
322 *
323 * \a image The image
324 */
325 static void semiTransparent(QImage &image);
326
327 /*!
328 * Renders a pixmap semi-transparent.
329 *
330 * \a pixmap The pixmap
331 */
332 static void semiTransparent(QPixmap &pixmap);
333
334 /*!
335 * Overlays an image with an other image.
336 *
337 * \a src The image
338 *
339 * \a overlay The image to overlay \a src with
340 */
341 static void overlay(QImage &src, QImage &overlay);
342
343 /*!
344 * Applies a disabled effect
345 *
346 * \a image The image
347 *
348 * \since 6.5
349 */
350 static void toDisabled(QImage &image);
351
352 /*!
353 * Applies a disabled effect
354 *
355 * \a pixmap The image
356 *
357 * \since 6.5
358 */
359 static void toDisabled(QPixmap &pixmap);
360
361 /*!
362 * Applies an effect for an icon that is in an 'active' state
363 *
364 * \a image The image
365 *
366 * \since 6.5
367 */
368 static void toActive(QImage &image);
369
370 /*!
371 * Applies an effect for an icon that is in an 'active' state
372 *
373 * \a pixmap The image
374 *
375 * \since 6.5
376 */
377 static void toActive(QPixmap &pixmap);
378
379private:
380 std::unique_ptr<KIconEffectPrivate> const d;
381};
382
383#endif
384

source code of kiconthemes/src/kiconeffect.h