KIconThemes

kiconeffect.h
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 <[email protected]>
5  SPDX-FileCopyrightText: 2007 Daniel M. Duley <[email protected]>
6 
7  with minor additions and based on ideas from
8  SPDX-FileContributor: Torsten Rahn <[email protected]>
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 
24 class 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  */
39 class KICONTHEMES_EXPORT KIconEffect
40 {
41 public:
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 
218 private:
219  std::unique_ptr<KIconEffectPrivate> const d;
220 };
221 
222 #endif
Effects
This is the enumeration of all possible icon effects.
Definition: kiconeffect.h:67
QCA_EXPORT void init()
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Sep 26 2023 03:58:09 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.