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: 2000 Antonio Larrosa <larrosa@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-only
8*/
9
10#ifndef KICONLOADER_H
11#define KICONLOADER_H
12
13#include <QObject>
14#include <QSize>
15#include <QString>
16#include <QStringList>
17#include <memory>
18
19#if __has_include(<optional>) && __cplusplus >= 201703L
20#include <optional>
21#endif
22
23#include <kiconthemes_export.h>
24
25class QIcon;
26class QMovie;
27class QPixmap;
28
29class KIconColors;
30class KIconLoaderPrivate;
31class KIconEffect;
32class KIconTheme;
33
34/*!
35 * \class KIconLoader
36 * \inmodule KIconThemes
37 *
38 * \brief Iconloader for KDE.
39 *
40 * \note For most icon loading use cases perfer using QIcon::fromTheme
41 *
42 * KIconLoader will load the current icon theme and all its base themes.
43 * Icons will be searched in any of these themes. Additionally, it caches
44 * icons and applies effects according to the user's preferences.
45 *
46 * In KDE, it is encouraged to load icons by "Group". An icon group is a
47 * location on the screen where icons are being used. Standard groups are:
48 * Desktop, Toolbar, MainToolbar, Small and Panel. Each group can have some
49 * centrally-configured effects applied to its icons. This makes it possible
50 * to offer a consistent icon look in all KDE applications.
51 *
52 * The standard groups are defined below.
53 *
54 * \list
55 * \li KIconLoader::Desktop: Icons in the iconview of konqueror, kdesktop and similar apps.
56 * \li KIconLoader::Toolbar: Icons in toolbars.
57 * \li KIconLoader::MainToolbar: Icons in the main toolbars.
58 * \li KIconLoader::Small: Various small (typical 16x16) places: titlebars, listviews
59 * and menu entries.
60 * \li KIconLoader::Panel: Icons in kicker's panel
61 * \endlist
62 *
63 * The icons are stored on disk in an icon theme or in a standalone
64 * directory. The icon theme directories contain multiple sizes and/or
65 * depths for the same icon. The iconloader will load the correct one based
66 * on the icon group and the current theme. Icon themes are stored globally
67 * in share/icons, or, application specific in share/apps/$appdir/icons.
68 *
69 * The standalone directories contain just one version of an icon. The
70 * directories that are searched are: $appdir/pics and $appdir/toolbar.
71 * Icons in these directories can be loaded by using the special group
72 * "User".
73 */
74class KICONTHEMES_EXPORT KIconLoader : public QObject
75{
76 Q_OBJECT
77
78public:
79 /*!
80 * \enum KIconLoader::Context
81 *
82 * \brief Defines the context of the icon.
83 *
84 * \value Any Some icon with unknown purpose.
85 * \value Action An action icon (e.g. 'save', 'print').
86 * \value Application An icon that represents an application.
87 * \value Device An icon that represents a device.
88 * \value MimeType An icon that represents a mime type (or file type).
89 * \value Animation An icon that is animated.
90 * \value Category An icon that represents a category.
91 * \value Emblem An icon that adds information to an existing icon.
92 * \value Emote An icon that expresses an emotion.
93 * \value International An icon that represents a country's flag.
94 * \value Place An icon that represents a location (e.g. 'home', 'trash').
95 * \value StatusIcon An icon that represents an event.
96 */
97 enum Context {
98 Any,
99 Action,
100 Application,
101 Device,
102 MimeType,
103 Animation,
104 Category,
105 Emblem,
106 Emote,
107 International,
108 Place,
109 StatusIcon,
110 };
111 Q_ENUM(Context)
112
113 /*!
114 * \enum KIconLoader::Type
115 *
116 * \brief The type of the icon.
117 *
118 * \value Fixed Fixed-size icon.
119 * \value Scalable Scalable-size icon.
120 * \value Threshold A threshold icon.
121 */
122 enum Type {
123 Fixed,
124 Scalable,
125 Threshold,
126 };
127 Q_ENUM(Type)
128
129 /*!
130 * \enum KIconLoader::MatchType
131 *
132 * \brief The type of a match.
133 *
134 * \value MatchExact Only try to find an exact match.
135 * \value MatchBest Take the best match if there is no exact match.
136 * \value MatchBestOrGreaterSize Take the best match or the match with a greater size if there is no exact match. \since 6.0
137 */
138 enum MatchType {
139 MatchExact,
140 MatchBest,
141 MatchBestOrGreaterSize,
142 };
143 Q_ENUM(MatchType)
144
145 /*!
146 * \enum KIconLoader::Group
147 *
148 * \brief The group of the icon.
149 *
150 * \value NoGroup No group
151 * \value Desktop Desktop icons
152 * \value FirstGroup First group
153 * \value Toolbar Toolbar icons
154 * \value MainToolbar Main toolbar icons
155 * \value Small Small icons, e.g. for buttons
156 * \value Panel Panel (Plasma Taskbar) icons
157 * \value Dialog Icons for use in dialog titles, page lists, etc
158 * \value LastGroup Last group
159 * \value User User icons
160 */
161 enum Group {
162 NoGroup = -1,
163 Desktop = 0,
164 FirstGroup = 0,
165 Toolbar,
166 MainToolbar,
167 Small,
168 // TODO KF6: remove this (See https://phabricator.kde.org/T14340)
169 Panel,
170 Dialog,
171 LastGroup,
172 User,
173 };
174 Q_ENUM(Group)
175
176 /*!
177 * \enum KIconLoader::StdSizes
178 *
179 * \brief These are the standard sizes for icons.
180 *
181 * \value SizeSmall small icons for menu entries
182 * \value SizeSmallMedium slightly larger small icons for toolbars, panels, etc
183 * \value SizeMedium medium sized icons for the desktop
184 * \value SizeLarge large sized icons for the panel
185 * \value SizeHuge huge sized icons for iconviews
186 * \value SizeEnormous enormous sized icons for iconviews
187 */
188 enum StdSizes {
189 SizeSmall = 16,
190 SizeSmallMedium = 22,
191 SizeMedium = 32,
192 SizeLarge = 48,
193 SizeHuge = 64,
194 SizeEnormous = 128,
195 };
196 Q_ENUM(StdSizes)
197
198 /*!
199 * \enum KIconLoader::States
200 *
201 * \brief Defines the possible states of an icon.
202 *
203 * \value DefaultState The default state.
204 * \value ActiveState Icon is active.
205 * \value DisabledState Icon is disabled.
206 * \value [since 5.22] SelectedState Icon is selected.
207 * \value LastState Last state (last constant)
208 */
209 enum States {
210 DefaultState,
211 ActiveState,
212 DisabledState,
213 SelectedState,
214 LastState,
215 };
216 Q_ENUM(States)
217
218 /*!
219 * Constructs an iconloader.
220 *
221 * \a appname Add the data directories of this application to the
222 * icon search path for the "User" group. The default argument adds the
223 * directories of the current application.
224 *
225 * \a extraSearchPaths additional search paths, either absolute or relative to GenericDataLocation
226 *
227 * Usually, you use the default iconloader, which can be accessed via
228 * KIconLoader::global(), so you hardly ever have to create an
229 * iconloader object yourself. That one is the application's iconloader.
230 */
231 explicit KIconLoader(const QString &appname = QString(), const QStringList &extraSearchPaths = QStringList(), QObject *parent = nullptr);
232
233 ~KIconLoader() override;
234
235 /*!
236 * Returns the global icon loader initialized with the application name.
237 */
238 static KIconLoader *global();
239
240 /*!
241 * Adds \a appname to the list of application specific directories with \a themeBaseDir as its base directory.
242 *
243 * Assume the icons are in /home/user/app/icons/hicolor/48x48/my_app.png, the base directory would be
244 * /home/user/app/icons; KIconLoader automatically searches \a themeBaseDir + "/hicolor"
245 *
246 * This directory must contain a dir structure as defined by the XDG icons specification
247 *
248 * \a appname The application name.
249 *
250 * \a themeBaseDir The base directory of the application's theme (eg. "/home/user/app/icons")
251 */
252 void addAppDir(const QString &appname, const QString &themeBaseDir = QString());
253
254 /*!
255 * Loads an icon. It will try very hard to find an icon which is
256 * suitable. If no exact match is found, a close match is searched.
257 * If neither an exact nor a close match is found, a null pixmap or
258 * the "unknown" pixmap is returned, depending on the value of the
259 * \a canReturnNull parameter.
260 *
261 * \a name The name of the icon, without extension.
262 *
263 * \a group The icon group. This will specify the size of and effects to
264 * be applied to the icon.
265 *
266 * \a size If nonzero, this overrides the size specified by \a group.
267 * See KIconLoader::StdSizes.
268 *
269 * \a state The icon state: \c DefaultState, \c ActiveState or
270 * \c DisabledState. Depending on the user's preferences, the iconloader
271 * may apply a visual effect to hint about its state.
272 *
273 * \a overlays a list of emblem icons to overlay, by name
274 * \sa drawOverlays
275 *
276 * \a path_store If not null, the path of the icon is stored here,
277 * if the icon was found. If the icon was not found \a path_store
278 * is unaltered even if the "unknown" pixmap was returned.
279 *
280 * \a canReturnNull Can return a null pixmap? If false, the
281 * "unknown" pixmap is returned when no appropriate icon has been
282 * found. Note: a null pixmap can still be returned in the
283 * event of invalid parameters, such as empty names, negative sizes,
284 * and etc.
285 *
286 * Returns the QPixmap. Can be null when not found, depending on
287 * \a canReturnNull.
288 */
289 QPixmap loadIcon(const QString &name,
290 KIconLoader::Group group,
291 int size = 0,
292 int state = KIconLoader::DefaultState,
293 const QStringList &overlays = QStringList(),
294 QString *path_store = nullptr,
295 bool canReturnNull = false) const;
296
297 // TODO KF6 merge loadIcon() and loadScaledIcon()
298 /*!
299 * Loads an icon. It will try very hard to find an icon which is
300 * suitable. If no exact match is found, a close match is searched.
301 * If neither an exact nor a close match is found, a null pixmap or
302 * the "unknown" pixmap is returned, depending on the value of the
303 * \a canReturnNull parameter.
304 *
305 * \a name The name of the icon, without extension.
306 *
307 * \a group The icon group. This will specify the size of and effects to
308 * be applied to the icon.
309 *
310 * \a scale The scale of the icon group to use. If no icon exists in the
311 * scaled group, a 1x icon with its size multiplied by the scale will be
312 * loaded instead.
313 *
314 * \a size If nonzero, this overrides the size specified by \a group.
315 * See KIconLoader::StdSizes.
316 *
317 * \a state The icon state: \c DefaultState, \c ActiveState or
318 * \c DisabledState. Depending on the user's preferences, the iconloader
319 * may apply a visual effect to hint about its state.
320 *
321 * \a overlays a list of emblem icons to overlay, by name
322 * \sa drawOverlays
323 *
324 * \a path_store If not null, the path of the icon is stored here,
325 * if the icon was found. If the icon was not found \a path_store
326 * is unaltered even if the "unknown" pixmap was returned.
327 *
328 * \a canReturnNull Can return a null pixmap? If false, the
329 * "unknown" pixmap is returned when no appropriate icon has been
330 * found. Note: a null pixmap can still be returned in the
331 * event of invalid parameters, such as empty names, negative sizes,
332 * and etc.
333 *
334 * Returns the QPixmap. Can be null when not found, depending on
335 * \a canReturnNull.
336 * \since 5.48
337 */
338 QPixmap loadScaledIcon(const QString &name,
339 KIconLoader::Group group,
340 qreal scale,
341 int size = 0,
342 int state = KIconLoader::DefaultState,
343 const QStringList &overlays = QStringList(),
344 QString *path_store = nullptr,
345 bool canReturnNull = false) const;
346
347 /*!
348 * Loads an icon. It will try very hard to find an icon which is
349 * suitable. If no exact match is found, a close match is searched.
350 * If neither an exact nor a close match is found, a null pixmap or
351 * the "unknown" pixmap is returned, depending on the value of the
352 * \a canReturnNull parameter.
353 *
354 * \a name The name of the icon, without extension.
355 *
356 * \a group The icon group. This will specify the size of and effects to
357 * be applied to the icon.
358 *
359 * \a scale The scale of the icon group to use. If no icon exists in the
360 * scaled group, a 1x icon with its size multiplied by the scale will be
361 * loaded instead.
362 *
363 * \a size If nonzero, this overrides the size specified by \a group.
364 * See KIconLoader::StdSizes. The icon will be fit into \a size
365 * without changing the aspect ratio, which particularly matters
366 * for non-square icons.
367 *
368 * \a state The icon state: \c DefaultState, \c ActiveState or \c DisabledState. Depending on the user's preferences, the iconloader may apply a visual
369 * effect to hint about its state.
370 *
371 * \a overlays a list of emblem icons to overlay, by name
372 * \sa drawOverlays
373 *
374 * \a path_store If not null, the path of the icon is stored here,
375 * if the icon was found. If the icon was not found \a path_store
376 * is unaltered even if the "unknown" pixmap was returned.
377 *
378 * \a canReturnNull Can return a null pixmap? If false, the
379 * "unknown" pixmap is returned when no appropriate icon has been
380 * found. Note: a null pixmap can still be returned in the
381 * event of invalid parameters, such as empty names, negative sizes,
382 * and etc.
383 *
384 * Returns the QPixmap. Can be null when not found, depending on
385 * \a canReturnNull.
386 * \since 5.81
387 */
388 QPixmap loadScaledIcon(const QString &name,
389 KIconLoader::Group group,
390 qreal scale,
391 const QSize &size = {},
392 int state = KIconLoader::DefaultState,
393 const QStringList &overlays = QStringList(),
394 QString *path_store = nullptr,
395 bool canReturnNull = false) const;
396
397#if __has_include(<optional>) && __cplusplus >= 201703L
398 /*!
399 * Loads an icon. It will try very hard to find an icon which is
400 * suitable. If no exact match is found, a close match is searched.
401 * If neither an exact nor a close match is found, a null pixmap or
402 * the "unknown" pixmap is returned, depending on the value of the
403 * \a canReturnNull parameter.
404 *
405 * \a name The name of the icon, without extension.
406 *
407 * \a group The icon group. This will specify the size of and effects to
408 * be applied to the icon.
409 *
410 * \a scale The scale of the icon group to use. If no icon exists in the
411 * scaled group, a 1x icon with its size multiplied by the scale will be
412 * loaded instead.
413 *
414 * \a size If nonzero, this overrides the size specified by \a group.
415 * See KIconLoader::StdSizes. The icon will be fit into \a size
416 * without changing the aspect ratio, which particularly matters
417 * for non-square icons.
418 *
419 * \a state The icon state: \c DefaultState, \c ActiveState or
420 * \c DisabledState. Depending on the user's preferences, the iconloader
421 * may apply a visual effect to hint about its state.
422 *
423 * \a overlays a list of emblem icons to overlay, by name
424 * \sa drawOverlays()
425 *
426 * \a path_store If not null, the path of the icon is stored here,
427 * if the icon was found. If the icon was not found \a path_store
428 * is unaltered even if the "unknown" pixmap was returned.
429 * \a canReturnNull Can return a null pixmap? If false, the
430 * "unknown" pixmap is returned when no appropriate icon has been
431 * found. Note: a null pixmap can still be returned in the
432 * event of invalid parameters, such as empty names, negative sizes,
433 * and etc.
434 *
435 * \a colorScheme will define the stylesheet used to color this icon.
436 * Note this will only work if \a name is an svg file.
437 *
438 * Returns the QPixmap. Can be null when not found, depending on
439 * \a canReturnNull.
440 * \since 5.88
441 */
442 QPixmap loadScaledIcon(const QString &name,
443 KIconLoader::Group group,
444 qreal scale,
445 const QSize &size,
446 int state,
447 const QStringList &overlays,
448 QString *path_store,
449 bool canReturnNull,
450 const std::optional<KIconColors> &colorScheme) const;
451#endif
452
453 /*!
454 * Loads an icon for a mimetype.
455 * This is basically like loadIcon except that extra desktop themes are loaded if necessary.
456 *
457 * Consider using QIcon::fromTheme() with a fallback to "application-octet-stream" instead.
458 *
459 * \a iconName The name of the icon, without extension, usually from KMimeType.
460 *
461 * \a group The icon group. This will specify the size of and effects to
462 * be applied to the icon.
463 *
464 * \a size If nonzero, this overrides the size specified by \a group.
465 * See KIconLoader::StdSizes.
466 *
467 * \a state The icon state: \c DefaultState, \c ActiveState or
468 * \c DisabledState. Depending on the user's preferences, the iconloader
469 * may apply a visual effect to hint about its state.
470 *
471 * \a path_store If not null, the path of the icon is stored here.
472 *
473 * \a overlays a list of emblem icons to overlay, by name
474 * \sa drawOverlays
475 *
476 * Returns the QPixmap. Can not be null, the
477 * "unknown" pixmap is returned when no appropriate icon has been found.
478 */
479 QPixmap loadMimeTypeIcon(const QString &iconName,
480 KIconLoader::Group group,
481 int size = 0,
482 int state = KIconLoader::DefaultState,
483 const QStringList &overlays = QStringList(),
484 QString *path_store = nullptr) const;
485
486 /*!
487 * Returns the path of an icon.
488 *
489 * \a name The name of the icon, without extension. If an absolute
490 * path is supplied for this parameter, iconPath will return it
491 * directly.
492 *
493 * \a group_or_size If positive, search icons whose size is
494 * specified by the icon group \a group_or_size. If negative, search
495 * icons whose size is - \a group_or_size.
496 * See KIconLoader::Group and KIconLoader::StdSizes
497 *
498 * \a canReturnNull Can return a null string? If not, a path to the
499 * "unknown" icon will be returned.
500 *
501 * Returns the path of an icon, can be null or the "unknown" icon when
502 * not found, depending on \a canReturnNull.
503 */
504 QString iconPath(const QString &name, int group_or_size, bool canReturnNull = false) const;
505
506 // TODO KF6 merge iconPath() with and without "scale" and move that argument after "group_or_size"
507 /*!
508 * Returns the path of an icon.
509 *
510 * \a name The name of the icon, without extension. If an absolute
511 * path is supplied for this parameter, iconPath will return it
512 * directly.
513 *
514 * \a group_or_size If positive, search icons whose size is
515 * specified by the icon group \a group_or_size. If negative, search
516 * icons whose size is - \a group_or_size.
517 * See KIconLoader::Group and KIconLoader::StdSizes
518 *
519 * \a canReturnNull Can return a null string? If not, a path to the
520 * "unknown" icon will be returned.
521 *
522 * \a scale The scale of the icon group.
523 *
524 * Returns the path of an icon, can be null or the "unknown" icon when
525 * not found, depending on \a canReturnNull.
526 * \since 5.48
527 */
528 QString iconPath(const QString &name, int group_or_size, bool canReturnNull, qreal scale) const;
529
530#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
531 /*!
532 * Loads an animated icon.
533 *
534 * \a name The name of the icon.
535 *
536 * \a group The icon group. See loadIcon().
537 *
538 * \a size Override the default size for \a group.
539 * See KIconLoader::StdSizes.
540 *
541 * \a parent The parent object of the returned QMovie.
542 *
543 * Returns A QMovie object. Can be null if not found or not valid.
544 * Ownership is passed to the caller.
545 * \deprecated[6.5] use QMovie API
546 */
547 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use QMovie API")
548 QMovie *loadMovie(const QString &name, KIconLoader::Group group, int size = 0, QObject *parent = nullptr) const;
549#endif
550
551#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
552 /*!
553 * Returns the path to an animated icon.
554 *
555 * \a name The name of the icon.
556 *
557 * \a group The icon group. See loadIcon().
558 *
559 * \a size Override the default size for \a group.
560 * See KIconLoader::StdSizes.
561 *
562 * Returns the full path to the movie, ready to be passed to QMovie's constructor.
563 *
564 * Empty string if not found.
565 * \deprecated [6.5] use QMovie API
566 */
567 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use QMovie API")
568 QString moviePath(const QString &name, KIconLoader::Group group, int size = 0) const;
569#endif
570
571#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
572 /*!
573 * Loads an animated icon as a series of still frames. If you want to load
574 * a .mng animation as QMovie instead, please use loadMovie() instead.
575 *
576 * \a name The name of the icon.
577 *
578 * \a group The icon group. See loadIcon().
579 *
580 * \a size Override the default size for \a group.
581 * See KIconLoader::StdSizes.
582 *
583 * Returns a QStringList containing the absolute path of all the frames
584 * making up the animation.
585 *
586 * \deprecated [6.5] use QMovie API
587 */
588 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use QMovie API")
589 QStringList loadAnimated(const QString &name, KIconLoader::Group group, int size = 0) const;
590#endif
591
592 /*!
593 * Queries all available icons.
594 * \since 6.11
595 */
596 [[nodiscard]] QStringList queryIcons() const;
597
598 /*!
599 * Queries all available icons for a specific group, having a specific
600 * context.
601 *
602 * \a group_or_size If positive, search icons whose size is
603 * specified by the icon group \a group_or_size. If negative, search
604 * icons whose size is - \a group_or_size.
605 * See KIconLoader::Group and KIconLoader::StdSizes
606 *
607 * \a context The icon context.
608 * Returns a list of all icons
609 */
610 QStringList queryIcons(int group_or_size, KIconLoader::Context context = KIconLoader::Any) const;
611
612 /*!
613 * Queries all available icons for a specific context.
614 *
615 * \a group_or_size The icon preferred group or size. If available
616 * at this group or size, those icons will be returned, in other case,
617 * icons of undefined size will be returned. Positive numbers are groups,
618 * negative numbers are negated sizes. See KIconLoader::Group and
619 * KIconLoader::StdSizes
620 *
621 * \a context The icon context.
622 *
623 * Returns A QStringList containing the icon names
624 * available for that context
625 */
626 QStringList queryIconsByContext(int group_or_size, KIconLoader::Context context = KIconLoader::Any) const;
627
628 /*!
629 * \internal
630 */
631 bool hasContext(KIconLoader::Context context) const;
632
633 /*!
634 * Returns a list of all icons (*.png or *.xpm extension) in the
635 * given directory.
636 *
637 * \a iconsDir the directory to search in
638 * Returns A QStringList containing the icon paths
639 */
640 QStringList queryIconsByDir(const QString &iconsDir) const;
641
642 /*!
643 * Returns all the search paths for this icon loader, either absolute or
644 * relative to GenericDataLocation.
645 *
646 * Mostly internal (for KIconDialog).
647 * \since 5.0
648 */
649 QStringList searchPaths() const;
650
651 /*!
652 * Returns the size of the specified icon group.
653 *
654 * Using e.g. KIconLoader::SmallIcon will return 16.
655 *
656 * \a group the group to check.
657 *
658 * Returns the current size for an icon group.
659 */
660 int currentSize(KIconLoader::Group group) const;
661
662 /*!
663 * Returns a pointer to the current theme.
664 * Can be used to query
665 * available and default sizes for groups.
666 *
667 * \note The KIconTheme will change if reconfigure() is called and
668 * therefore it's not recommended to store the pointer anywhere.
669 *
670 * Returns a pointer to the current theme. 0 if no theme set.
671 */
672 KIconTheme *theme() const;
673
674#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
675 /*!
676 * Returns a pointer to the KIconEffect object used by the icon loader.
677 * Returns the KIconEffect.
678 *
679 * \deprecated [6.5] use the static KIconEffect API
680 */
681 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use static KIconEffect API")
682 KIconEffect *iconEffect() const;
683#endif
684
685 /*!
686 * Reconfigure the icon loader, for instance to change the associated app name or extra search paths.
687 *
688 * This also clears the in-memory pixmap cache (even if the appname didn't change, which is useful for unittests)
689 *
690 * \a appname the application name (empty for the global iconloader)
691 *
692 * \a extraSearchPaths additional search paths, either absolute or relative to GenericDataLocation
693 */
694 void reconfigure(const QString &appname, const QStringList &extraSearchPaths = QStringList());
695
696 /*!
697 * Returns the unknown icon. An icon that is used when no other icon
698 * can be found.
699 */
700 static QPixmap unknown();
701
702#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(6, 5)
703 /*!
704 * Draws overlays on the specified pixmap, it takes the width and height
705 * of the pixmap into consideration
706 *
707 * \a overlays List of up to 4 overlays to blend over the pixmap. The first overlay
708 * will be in the bottom right corner, followed by bottom left, top left
709 * and top right. An empty QString can be used to leave the specific position
710 * blank.
711 *
712 * \a pixmap to draw on
713 * \since 4.7
714 * \deprecated [6.5]
715 * Use KIconUtils::addOverlays from KGuiAddons
716 */
717 KICONTHEMES_DEPRECATED_VERSION(6, 5, "Use KIconUtils::addOverlays from KGuiAddons")
718 void drawOverlays(const QStringList &overlays, QPixmap &pixmap, KIconLoader::Group group, int state = KIconLoader::DefaultState) const;
719#endif
720
721 /*!
722 *
723 */
724 bool hasIcon(const QString &iconName) const;
725
726 /*!
727 * Sets the colors for this KIconLoader.
728 *
729 * \note if you set a custom palette, if you are using some colors from
730 * application's palette, you need to track the application palette changes by yourself.
731 *
732 * If you no longer wish to use a custom palette, use resetPalette()
733 * \sa resetPalette()
734 * \since 5.39
735 */
736 void setCustomPalette(const QPalette &palette);
737
738 /*!
739 * The colors that will be used for the svg stylesheet in case the
740 * loaded icons are svg-based, icons can be colored in different ways in
741 * different areas of the application
742 *
743 * Returns the palette, if any, an invalid one if the user didn't set it
744 * \since 5.39
745 */
746 QPalette customPalette() const;
747
748 /*!
749 * Resets the custom palette used by the KIconLoader to use the
750 * QGuiApplication::palette() again (and to follow it in case the
751 * application's palette changes)
752 * \since 5.39
753 */
754 void resetPalette();
755
756 /*!
757 * Returns whether we have set a custom palette using setCustomPalette
758 *
759 * \since 5.85
760 * \sa resetPalette, setCustomPalette
761 */
762 bool hasCustomPalette() const;
763
764public Q_SLOTS:
765 // TODO KF7: while marked as deprecated, newIconLoader() is still used:
766 // internally by KIconLoadeer as well as by Plasma's Icons kcm module (state: 5.17)
767 // this needs some further cleanup work before removing it from the API with KICONTHEMES_ENABLE_DEPRECATED_SINCE
768 /*!
769 * Re-initialize the global icon loader
770 *
771 * \deprecated[5.0]
772 * Use emitChange(Group)
773 */
774 KICONTHEMES_DEPRECATED_VERSION(5, 0, "Use KIconLoader::emitChange(Group)")
775 void newIconLoader();
776
777 /*!
778 * Emits an iconChanged() signal on all the KIconLoader instances in the system
779 * indicating that a system's icon group has changed in some way. It will also trigger
780 * a reload in all of them to update to the new theme.
781 *
782 * \a group indicates the group that has changed
783 *
784 * \since 5.0
785 */
786 static void emitChange(Group group);
787
788Q_SIGNALS:
789 /*!
790 * Emitted by newIconLoader once the new settings have been loaded
791 */
792 void iconLoaderSettingsChanged();
793
794 /*!
795 * Emitted when the system icon theme changes
796 *
797 * \since 5.0
798 */
799 void iconChanged(int group);
800
801private:
802 friend class KIconLoaderPrivate;
803 std::unique_ptr<KIconLoaderPrivate> const d;
804
805 Q_PRIVATE_SLOT(d, void _k_refreshIcons(int group))
806};
807
808/*!
809 * \namespace KDE
810 * \inmodule KIconThemes
811 */
812namespace KDE
813{
814/*!
815 * \relates KIconLoader
816 * Returns a QIcon with an appropriate
817 * KIconEngine to perform loading and rendering. KIcons thus adhere to
818 * KDE style and effect standards.
819 * \since 5.0
820 */
821KICONTHEMES_EXPORT QIcon icon(const QString &iconName, KIconLoader *iconLoader = nullptr);
822
823/*!
824 * \relates KIconLoader
825 * Returns a QIcon with an appropriate
826 * KIconEngine to perform loading and rendering. KIcons thus adhere to
827 * KDE style and effect standards.
828 * \since 5.0
829 */
830KICONTHEMES_EXPORT QIcon icon(const QString &iconName, const KIconColors &colors, KIconLoader *iconLoader = nullptr);
831
832/*!
833 * \relates KIconLoader
834 * Returns a QIcon for the given icon, with additional overlays.
835 * \since 5.0
836 */
837KICONTHEMES_EXPORT QIcon icon(const QString &iconName, const QStringList &overlays, KIconLoader *iconLoader = nullptr);
838
839}
840
841inline KIconLoader::Group &operator++(KIconLoader::Group &group)
842{
843 group = static_cast<KIconLoader::Group>(group + 1);
844 return group;
845}
846inline KIconLoader::Group operator++(KIconLoader::Group &group, int)
847{
848 KIconLoader::Group ret = group;
849 ++group;
850 return ret;
851}
852
853#endif // KICONLOADER_H
854

source code of kiconthemes/src/kiconloader.h