1/* vi: ts=8 sts=4 sw=4
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 kiconeffect.h KIconEffect
28 *
29 * Applies effects to icons.
30 *
31 * This class applies effects to icons depending on their state and
32 * group. For example, it can be used to make all disabled icons
33 * in a toolbar gray.
34 *
35 * \image html kiconeffect-apply.png "Various Effects applied to an image"
36 *
37 * @see QIcon::fromTheme
38 */
39class KICONTHEMES_EXPORT KIconEffect
40{
41public:
42 /**
43 * Create a new KIconEffect.
44 * You will most likely never have to use this to create a new KIconEffect
45 * yourself, as you can use the KIconEffect provided by the global KIconLoader
46 * (which itself is accessible by KIconLoader::global()) through its
47 * iconEffect() function.
48 */
49 KIconEffect();
50 ~KIconEffect();
51
52 KIconEffect(const KIconEffect &) = delete;
53 KIconEffect &operator=(const KIconEffect &) = delete;
54
55 /**
56 * This is the enumeration of all possible icon effects.
57 * Note that 'LastEffect' is no valid icon effect but only
58 * used internally to check for invalid icon effects.
59 *
60 * @li NoEffect: Do not apply any icon effect
61 * @li ToGray: Tints the icon gray
62 * @li Colorize: Tints the icon with a specific color
63 * @li ToGamma: Change the gamma value of the icon
64 * @li DeSaturate: Reduce the saturation of the icon
65 * @li ToMonochrome: Produces a monochrome icon
66 */
67 enum Effects {
68 NoEffect,
69 ToGray,
70 Colorize,
71 ToGamma,
72 DeSaturate,
73 ToMonochrome,
74 LastEffect,
75 };
76
77 /**
78 * Rereads configuration.
79 */
80 void init();
81
82 /**
83 * Tests whether an effect has been configured for the given icon group.
84 * @param group the group to check, see KIconLoader::Group
85 * @param state the state to check, see KIconLoader::States
86 * @returns true if an effect is configured for the given @p group
87 * in @p state, otherwise false.
88 * @see KIconLoader::Group
89 * KIconLoader::States
90 */
91 bool hasEffect(int group, int state) const;
92
93 /**
94 * Returns a fingerprint for the effect by encoding
95 * the given @p group and @p state into a QString. This
96 * is useful for caching.
97 * @param group the group, see KIconLoader::Group
98 * @param state the state, see KIconLoader::States
99 * @return the fingerprint of the given @p group+@p state
100 */
101 QString fingerprint(int group, int state) const;
102
103 /**
104 * Applies an effect to an image. The effect to apply depends on the
105 * @p group and @p state parameters, and is configured by the user.
106 * @param src The image.
107 * @param group The group for the icon, see KIconLoader::Group
108 * @param state The icon's state, see KIconLoader::States
109 * @return An image with the effect applied.
110 */
111 QImage apply(const QImage &src, int group, int state) const;
112
113 /**
114 * Applies an effect to an image.
115 * @param src The image.
116 * @param effect The effect to apply, one of KIconEffect::Effects.
117 * @param value Strength of the effect. 0 <= @p value <= 1.
118 * @param rgb Color parameter for effects that need one.
119 * @param trans Add Transparency if trans = true.
120 * @return An image with the effect applied.
121 */
122 QImage apply(const QImage &src, int effect, float value, const QColor &rgb, bool trans) const;
123 QImage apply(const QImage &src, int effect, float value, const QColor &rgb, const QColor &rgb2, bool trans) const;
124
125 /**
126 * Applies an effect to a pixmap.
127 * @param src The pixmap.
128 * @param group The group for the icon, see KIconLoader::Group
129 * @param state The icon's state, see KIconLoader::States
130 * @return A pixmap with the effect applied.
131 */
132 QPixmap apply(const QPixmap &src, int group, int state) const;
133
134 /**
135 * Applies an effect to a pixmap.
136 * @param src The pixmap.
137 * @param effect The effect to apply, one of KIconEffect::Effects.
138 * @param value Strength of the effect. 0 <= @p value <= 1.
139 * @param rgb Color parameter for effects that need one.
140 * @param trans Add Transparency if trans = true.
141 * @return A pixmap with the effect applied.
142 */
143 QPixmap apply(const QPixmap &src, int effect, float value, const QColor &rgb, bool trans) const;
144 QPixmap apply(const QPixmap &src, int effect, float value, const QColor &rgb, const QColor &rgb2, bool trans) const;
145
146 /**
147 * Returns an image twice as large, consisting of 2x2 pixels.
148 * @param src the image.
149 * @return the scaled image.
150 */
151 QImage doublePixels(const QImage &src) const;
152
153 /**
154 * Tints an image gray.
155 *
156 * @param image The image
157 * @param value Strength of the effect. 0 <= @p value <= 1
158 */
159 static void toGray(QImage &image, float value);
160
161 /**
162 * Colorizes an image with a specific color.
163 *
164 * @param image The image
165 * @param col The color with which the @p image is tinted
166 * @param value Strength of the effect. 0 <= @p value <= 1
167 */
168 static void colorize(QImage &image, const QColor &col, float value);
169
170 /**
171 * Produces a monochrome icon with a given foreground and background color
172 *
173 * @param image The image
174 * @param white The color with which the white parts of @p image are painted
175 * @param black The color with which the black parts of @p image are painted
176 * @param value Strength of the effect. 0 <= @p value <= 1
177 */
178 static void toMonochrome(QImage &image, const QColor &black, const QColor &white, float value);
179
180 /**
181 * Desaturates an image.
182 *
183 * @param image The image
184 * @param value Strength of the effect. 0 <= @p value <= 1
185 */
186 static void deSaturate(QImage &image, float value);
187
188 /**
189 * Changes the gamma value of an image.
190 *
191 * @param image The image
192 * @param value Strength of the effect. 0 <= @p value <= 1
193 */
194 static void toGamma(QImage &image, float value);
195
196 /**
197 * Renders an image semi-transparent.
198 *
199 * @param image The image
200 */
201 static void semiTransparent(QImage &image);
202
203 /**
204 * Renders a pixmap semi-transparent.
205 *
206 * @param pixmap The pixmap
207 */
208 static void semiTransparent(QPixmap &pixmap);
209
210 /**
211 * Overlays an image with an other image.
212 *
213 * @param src The image
214 * @param overlay The image to overlay @p src with
215 */
216 static void overlay(QImage &src, QImage &overlay);
217
218private:
219 std::unique_ptr<KIconEffectPrivate> const d;
220};
221
222#endif
223

source code of kiconthemes/src/kiconeffect.h