KIconThemes 5.109.0
kiconloader.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 <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
34class KPixmapSequence;
35
73class KICONTHEMES_EXPORT KIconLoader : public QObject
74{
75 Q_OBJECT
76
77public:
81 enum Context {
86#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(4, 8)
87 FileSystem
88 KICONTHEMES_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 4, 8, "Use Place instead"),
89#elif KICONTHEMES_BUILD_DEPRECATED_SINCE(4, 8)
90 FileSystem_DEPRECATED_DO_NOT_USE,
91#endif
100 };
101 Q_ENUM(Context)
102
103
106 enum Type {
110 };
111 Q_ENUM(Type)
112
113
119 };
120 Q_ENUM(MatchType)
121
122
125 enum Group {
127 NoGroup = -1,
129 Desktop = 0,
131 FirstGroup = 0,
138#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 104)
140 Panel KICONTHEMES_ENUMERATOR_DEPRECATED_VERSION(5, 104, "Use another group or explicit size"),
141#else
142 Panel_DEPRECATED_DO_NOT_USE,
143#endif
150 };
151 Q_ENUM(Group)
152
153
156 enum StdSizes {
158 SizeSmall = 16,
160 SizeSmallMedium = 22,
162 SizeMedium = 32,
164 SizeLarge = 48,
166 SizeHuge = 64,
168 SizeEnormous = 128,
169 };
170 Q_ENUM(StdSizes)
171
172
175 enum States {
181 };
182 Q_ENUM(States)
183
184
195 explicit KIconLoader(const QString &appname = QString(), const QStringList &extraSearchPaths = QStringList(), QObject *parent = nullptr);
196
200 ~KIconLoader() override;
201
206 static KIconLoader *global();
207
216 void addAppDir(const QString &appname, const QString &themeBaseDir = QString());
217
246 QPixmap loadIcon(const QString &name,
247 KIconLoader::Group group,
248 int size = 0,
249 int state = KIconLoader::DefaultState,
250 const QStringList &overlays = QStringList(),
251 QString *path_store = nullptr,
252 bool canReturnNull = false) const;
253
286 // TODO KF6 merge loadIcon() and loadScaledIcon()
287 QPixmap loadScaledIcon(const QString &name,
288 KIconLoader::Group group,
289 qreal scale,
290 int size = 0,
291 int state = KIconLoader::DefaultState,
292 const QStringList &overlays = QStringList(),
293 QString *path_store = nullptr,
294 bool canReturnNull = false) const;
295
330 QPixmap loadScaledIcon(const QString &name,
331 KIconLoader::Group group,
332 qreal scale,
333 const QSize &size = {},
334 int state = KIconLoader::DefaultState,
335 const QStringList &overlays = QStringList(),
336 QString *path_store = nullptr,
337 bool canReturnNull = false) const;
338
339#if __has_include(<optional>) && __cplusplus >= 201703L
376 QPixmap loadScaledIcon(const QString &name,
377 KIconLoader::Group group,
378 qreal scale,
379 const QSize &size,
380 int state,
381 const QStringList &overlays,
382 QString *path_store,
383 bool canReturnNull,
384 const std::optional<KIconColors> &colorScheme) const;
385#endif
386
407 QPixmap loadMimeTypeIcon(const QString &iconName,
408 KIconLoader::Group group,
409 int size = 0,
410 int state = KIconLoader::DefaultState,
411 const QStringList &overlays = QStringList(),
412 QString *path_store = nullptr) const;
413
421 KPixmapSequence loadPixmapSequence(const QString &iconName, int size = SizeSmall) const;
422
423#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 0)
441 KICONTHEMES_DEPRECATED_VERSION(5, 0, "Use QIcon::fromTheme(const QString&)")
442 QIcon loadIconSet(const QString &name, KIconLoader::Group group, int size = 0, bool canReturnNull = false);
443#endif
444
459 QString iconPath(const QString &name, int group_or_size, bool canReturnNull = false) const;
460
477 // TODO KF6 merge iconPath() with and without "scale" and move that argument after "group_or_size"
478 QString iconPath(const QString &name, int group_or_size, bool canReturnNull, qreal scale) const;
479
490 QMovie *loadMovie(const QString &name, KIconLoader::Group group, int size = 0, QObject *parent = nullptr) const;
491
501 QString moviePath(const QString &name, KIconLoader::Group group, int size = 0) const;
502
513 QStringList loadAnimated(const QString &name, KIconLoader::Group group, int size = 0) const;
514
525 QStringList queryIcons(int group_or_size, KIconLoader::Context context = KIconLoader::Any) const;
526
538 QStringList queryIconsByContext(int group_or_size, KIconLoader::Context context = KIconLoader::Any) const;
539
543 bool hasContext(KIconLoader::Context context) const;
544
551 QStringList queryIconsByDir(const QString &iconsDir) const;
552
559 QStringList searchPaths() const;
560
571
579 KIconTheme *theme() const;
580
586
593 void reconfigure(const QString &appname, const QStringList &extraSearchPaths = QStringList());
594
600 static QPixmap unknown();
601
602#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 82)
610 KICONTHEMES_DEPRECATED_VERSION_BELATED(5, 82, 3, 1, "No known users")
611 bool alphaBlending(KIconLoader::Group group) const;
612#endif
613
624 void drawOverlays(const QStringList &overlays, QPixmap &pixmap, KIconLoader::Group group, int state = KIconLoader::DefaultState) const;
625
626 bool hasIcon(const QString &iconName) const;
627
636 void setCustomPalette(const QPalette &palette);
637
645 QPalette customPalette() const;
646
654
661 bool hasCustomPalette() const;
662
663public Q_SLOTS:
664 // TODO: while marked as deprecated, newIconLoader() is still used:
665 // internally by KIconLoadeer as well as by Plasma's Icons kcm module (state: 5.17)
666 // this needs some further cleanup work before removing it from the API with KICONTHEMES_ENABLE_DEPRECATED_SINCE
673 KICONTHEMES_DEPRECATED_VERSION(5, 0, "Use KIconLoader::emitChange(Group)")
674 void newIconLoader();
675
685 static void emitChange(Group group);
686
687Q_SIGNALS:
691 void iconLoaderSettingsChanged();
692
698 void iconChanged(int group);
699
700private:
701 friend class KIconLoaderPrivate;
702 // @internal the data object
703 std::unique_ptr<KIconLoaderPrivate> const d;
704
705 Q_PRIVATE_SLOT(d, void _k_refreshIcons(int group))
706};
707
708#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 63)
716KICONTHEMES_EXPORT
717KICONTHEMES_DEPRECATED_VERSION(5, 63, "See API dox for replacement")
718QPixmap DesktopIcon(const QString &name, int size = 0, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList());
719#endif
720
721#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 0)
727KICONTHEMES_EXPORT
728KICONTHEMES_DEPRECATED_VERSION(5, 0, "Use QIcon::fromTheme(const QString&)")
729QIcon DesktopIconSet(const QString &name, int size = 0);
730#endif
731
732#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 63)
740KICONTHEMES_EXPORT
741KICONTHEMES_DEPRECATED_VERSION(5, 63, "See API dox for replacement")
742QPixmap BarIcon(const QString &name, int size = 0, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList());
743#endif
744
745#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 0)
751KICONTHEMES_EXPORT
752KICONTHEMES_DEPRECATED_VERSION(5, 0, "Use QIcon::fromTheme(const QString&)")
753QIcon BarIconSet(const QString &name, int size = 0);
754#endif
755
756#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 63)
764KICONTHEMES_EXPORT
765KICONTHEMES_DEPRECATED_VERSION(5, 63, "See API dox for replacement")
766QPixmap SmallIcon(const QString &name, int size = 0, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList());
767#endif
768
769#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 0)
775KICONTHEMES_EXPORT
776KICONTHEMES_DEPRECATED_VERSION(5, 0, "Use QIcon::fromTheme(const QString&)")
777QIcon SmallIconSet(const QString &name, int size = 0);
778#endif
779
780#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 63)
788KICONTHEMES_EXPORT
789KICONTHEMES_DEPRECATED_VERSION(5, 63, "See API dox for replacement")
790QPixmap MainBarIcon(const QString &name, int size = 0, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList());
791#endif
792
793#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 0)
799KICONTHEMES_EXPORT
800KICONTHEMES_DEPRECATED_VERSION(5, 0, "Use QIcon::fromTheme(const QString&)")
801QIcon MainBarIconSet(const QString &name, int size = 0);
802#endif
803
804#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 65)
811KICONTHEMES_EXPORT
812KICONTHEMES_DEPRECATED_VERSION(5, 65, "See API dox for replacement")
813QPixmap UserIcon(const QString &name, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList());
814#endif
815
816#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 0)
822KICONTHEMES_EXPORT
823KICONTHEMES_DEPRECATED_VERSION(5, 0, "Use QIcon::fromTheme(const QString&)")
824QIcon UserIconSet(const QString &name);
825#endif
826
827#if KICONTHEMES_ENABLE_DEPRECATED_SINCE(5, 66)
834KICONTHEMES_EXPORT
835KICONTHEMES_DEPRECATED_VERSION(5, 66, "Use QStyle::pixelMetric or KIconLoader::currentSize")
836int IconSize(KIconLoader::Group group);
837#endif
838
839namespace KDE
840{
848KICONTHEMES_EXPORT QIcon icon(const QString &iconName, KIconLoader *iconLoader = nullptr);
849KICONTHEMES_EXPORT QIcon icon(const QString &iconName, const KIconColors &colors, KIconLoader *iconLoader = nullptr);
850
856KICONTHEMES_EXPORT QIcon icon(const QString &iconName, const QStringList &overlays, KIconLoader *iconLoader = nullptr);
857
858}
859
860inline KIconLoader::Group &operator++(KIconLoader::Group &group)
861{
862 group = static_cast<KIconLoader::Group>(group + 1);
863 return group;
864}
865inline KIconLoader::Group operator++(KIconLoader::Group &group, int)
866{
867 KIconLoader::Group ret = group;
868 ++group;
869 return ret;
870}
871
872#endif // KICONLOADER_H
Sepecifies which colors will be used when recoloring icons as its stylesheet.
Definition kiconcolors.h:31
Applies effects to icons.
Definition kiconeffect.h:40
Iconloader for KDE.
Definition kiconloader.h:74
QStringList queryIconsByContext(int group_or_size, KIconLoader::Context context=KIconLoader::Any) const
Queries all available icons for a specific context.
Group
The group of the icon.
Definition kiconloader.h:125
@ Small
Small icons, e.g. for buttons.
Definition kiconloader.h:137
@ User
User icons.
Definition kiconloader.h:149
@ LastGroup
Last group.
Definition kiconloader.h:147
@ MainToolbar
Main toolbar icons.
Definition kiconloader.h:135
@ Toolbar
Toolbar icons.
Definition kiconloader.h:133
@ Dialog
Icons for use in dialog titles, page lists, etc.
Definition kiconloader.h:145
QStringList queryIcons(int group_or_size, KIconLoader::Context context=KIconLoader::Any) const
Queries all available icons for a specific group, having a specific context.
QIcon icon(const QString &iconName, KIconLoader *iconLoader=nullptr)
Returns a QIcon with an appropriate KIconEngine to perform loading and rendering.
QStringList searchPaths() const
Returns all the search paths for this icon loader, either absolute or relative to GenericDataLocation...
void resetPalette()
Resets the custom palette used by the KIconLoader to use the QGuiApplication::palette() again (and to...
QIcon icon(const QString &iconName, const QStringList &overlays, KIconLoader *iconLoader=nullptr)
Returns a QIcon for the given icon, with additional overlays.
States
Defines the possible states of an icon.
Definition kiconloader.h:175
@ ActiveState
Icon is active.
Definition kiconloader.h:177
@ DisabledState
Icon is disabled.
Definition kiconloader.h:178
@ LastState
Last state (last constant)
Definition kiconloader.h:180
@ DefaultState
The default state.
Definition kiconloader.h:176
@ SelectedState
Icon is selected.
Definition kiconloader.h:179
QString moviePath(const QString &name, KIconLoader::Group group, int size=0) const
Returns the path to an animated icon.
QMovie * loadMovie(const QString &name, KIconLoader::Group group, int size=0, QObject *parent=nullptr) const
Loads an animated icon.
QStringList queryIconsByDir(const QString &iconsDir) const
Returns a list of all icons (*.png or *.xpm extension) in the given directory.
int currentSize(KIconLoader::Group group) const
Returns the current size of the icon group.
StdSizes
These are the standard sizes for icons.
Definition kiconloader.h:156
KPixmapSequence loadPixmapSequence(const QString &iconName, int size=SizeSmall) const
Loads a pixmapSequence given the xdg icon name.
void reconfigure(const QString &appname, const QStringList &extraSearchPaths=QStringList())
Reconfigure the icon loader, for instance to change the associated app name or extra search paths.
KIconTheme * theme() const
Returns a pointer to the current theme.
QPixmap loadMimeTypeIcon(const QString &iconName, KIconLoader::Group group, int size=0, int state=KIconLoader::DefaultState, const QStringList &overlays=QStringList(), QString *path_store=nullptr) const
Loads an icon for a mimetype.
bool hasCustomPalette() const
void drawOverlays(const QStringList &overlays, QPixmap &pixmap, KIconLoader::Group group, int state=KIconLoader::DefaultState) const
Draws overlays on the specified pixmap, it takes the width and height of the pixmap into consideratio...
static QPixmap unknown()
Returns the unknown icon.
QStringList loadAnimated(const QString &name, KIconLoader::Group group, int size=0) const
Loads an animated icon as a series of still frames.
void setCustomPalette(const QPalette &palette)
Sets the colors for this KIconLoader.
KIconEffect * iconEffect() const
Returns a pointer to the KIconEffect object used by the icon loader.
QPalette customPalette() const
The colors that will be used for the svg stylesheet in case the loaded icons are svg-based,...
QString iconPath(const QString &name, int group_or_size, bool canReturnNull, qreal scale) const
Returns the path of an icon.
Context
Defines the context of the icon.
Definition kiconloader.h:81
@ Category
An icon that represents a category.
Definition kiconloader.h:94
@ Emblem
An icon that adds information to an existing icon.
Definition kiconloader.h:95
@ StatusIcon
An icon that represents an event.
Definition kiconloader.h:99
@ Application
An icon that represents an application.
Definition kiconloader.h:84
@ Emote
An icon that expresses an emotion.
Definition kiconloader.h:96
@ Any
Some icon with unknown purpose.
Definition kiconloader.h:82
@ Place
An icon that represents a location (e.g. 'home', 'trash').
Definition kiconloader.h:98
@ MimeType
An icon that represents a mime type (or file type).
Definition kiconloader.h:92
@ Action
An action icon (e.g. 'save', 'print').
Definition kiconloader.h:83
@ International
An icon that represents a country's flag.
Definition kiconloader.h:97
@ Animation
An icon that is animated.
Definition kiconloader.h:93
@ Device
An icon that represents a device.
Definition kiconloader.h:85
Type
The type of the icon.
Definition kiconloader.h:106
@ Fixed
Fixed-size icon.
Definition kiconloader.h:107
@ Scalable
Scalable-size icon.
Definition kiconloader.h:108
@ Threshold
A threshold icon.
Definition kiconloader.h:109
MatchType
The type of a match.
Definition kiconloader.h:116
@ MatchBest
Take the best match if there is no exact match.
Definition kiconloader.h:118
@ MatchExact
Only try to find an exact match.
Definition kiconloader.h:117
QString iconPath(const QString &name, int group_or_size, bool canReturnNull=false) const
Returns the path of an icon.