KIconLoader Class
Iconloader for KDE. More...
| Header: | #include <KIconLoader> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS IconThemes)target_link_libraries(mytarget PRIVATE KF6::IconThemes) |
| Inherits: | QObject |
Public Types
| enum | Context { Any, Action, Application, Device, MimeType, …, StatusIcon } |
| enum | Group { NoGroup, Desktop, FirstGroup, Toolbar, MainToolbar, …, User } |
(since 6.0) enum | MatchType { MatchExact, MatchBest, MatchBestOrGreaterSize } |
| enum | States { DefaultState, ActiveState, DisabledState, SelectedState, LastState } |
| enum | StdSizes { SizeSmall, SizeSmallMedium, SizeMedium, SizeLarge, SizeHuge, SizeEnormous } |
| enum | Type { Fixed, Scalable, Threshold } |
Public Functions
| KIconLoader(const QString &appname = QString(), const QStringList &extraSearchPaths = QStringList(), QObject *parent = nullptr) | |
| void | addAppDir(const QString &appname, const QString &themeBaseDir = QString()) |
| int | currentSize(KIconLoader::Group group) const |
(since 5.39) QPalette | customPalette() const |
(since 5.85) bool | hasCustomPalette() const |
| bool | hasIcon(const QString &iconName) const |
| QString | iconPath(const QString &name, int group_or_size, bool canReturnNull = false) const |
(since 5.48) QString | iconPath(const QString &name, int group_or_size, bool canReturnNull, qreal scale) const |
| QPixmap | loadIcon(const QString &name, KIconLoader::Group group, int size = 0, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList(), QString *path_store = nullptr, bool canReturnNull = false) const |
| QPixmap | loadMimeTypeIcon(const QString &iconName, KIconLoader::Group group, int size = 0, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList(), QString *path_store = nullptr) const |
(since 5.81) QPixmap | loadScaledIcon(const QString &name, KIconLoader::Group group, qreal scale, const QSize &size = {}, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList(), QString *path_store = nullptr, bool canReturnNull = false) const |
(since 5.48) QPixmap | loadScaledIcon(const QString &name, KIconLoader::Group group, qreal scale, int size = 0, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList(), QString *path_store = nullptr, bool canReturnNull = false) const |
(since 5.88) QPixmap | loadScaledIcon(const QString &name, KIconLoader::Group group, qreal scale, const QSize &size, int state, const QStringList &overlays, QString *path_store, bool canReturnNull, const std::optional<KIconColors> &colorScheme) const |
(since 6.11) QStringList | queryIcons() const |
| QStringList | queryIcons(int group_or_size, KIconLoader::Context context = KIconLoader::Any) const |
| QStringList | queryIconsByContext(int group_or_size, KIconLoader::Context context = KIconLoader::Any) const |
| QStringList | queryIconsByDir(const QString &iconsDir) const |
| void | reconfigure(const QString &appname, const QStringList &extraSearchPaths = QStringList()) |
(since 5.39) void | resetPalette() |
(since 5.0) QStringList | searchPaths() const |
(since 5.39) void | setCustomPalette(const QPalette &palette) |
| KIconTheme * | theme() const |
Public Slots
(since 5.0) void | emitChange(KIconLoader::Group group) |
Signals
(since 5.0) void | iconChanged(int group) |
| void | iconLoaderSettingsChanged() |
Static Public Members
Related Non-Members
(since 5.0) QIcon | icon(const QString &iconName, KIconLoader *iconLoader = nullptr) |
(since 5.0) QIcon | icon(const QString &iconName, const KIconColors &colors, KIconLoader *iconLoader = nullptr) |
(since 5.0) QIcon | icon(const QString &iconName, const QStringList &overlays, KIconLoader *iconLoader = nullptr) |
Detailed Description
Note: For most icon loading use cases perfer using QIcon::fromTheme
KIconLoader will load the current icon theme and all its base themes. Icons will be searched in any of these themes. Additionally, it caches icons and applies effects according to the user's preferences.
In KDE, it is encouraged to load icons by "Group". An icon group is a location on the screen where icons are being used. Standard groups are: Desktop, Toolbar, MainToolbar, Small and Panel. Each group can have some centrally-configured effects applied to its icons. This makes it possible to offer a consistent icon look in all KDE applications.
The standard groups are defined below.
- KIconLoader::Desktop: Icons in the iconview of konqueror, kdesktop and similar apps.
- KIconLoader::Toolbar: Icons in toolbars.
- KIconLoader::MainToolbar: Icons in the main toolbars.
- KIconLoader::Small: Various small (typical 16x16) places: titlebars, listviews and menu entries.
- KIconLoader::Panel: Icons in kicker's panel
The icons are stored on disk in an icon theme or in a standalone directory. The icon theme directories contain multiple sizes and/or depths for the same icon. The iconloader will load the correct one based on the icon group and the current theme. Icon themes are stored globally in share/icons, or, application specific in share/apps/$appdir/icons.
The standalone directories contain just one version of an icon. The directories that are searched are: $appdir/pics and $appdir/toolbar. Icons in these directories can be loaded by using the special group "User".
Member Type Documentation
enum KIconLoader::Context
Defines the context of the icon.
| Constant | Value | Description |
|---|---|---|
KIconLoader::Any | 0 | Some icon with unknown purpose. |
KIconLoader::Action | 1 | An action icon (e.g. 'save', 'print'). |
KIconLoader::Application | 2 | An icon that represents an application. |
KIconLoader::Device | 3 | An icon that represents a device. |
KIconLoader::MimeType | 4 | An icon that represents a mime type (or file type). |
KIconLoader::Animation | 5 | An icon that is animated. |
KIconLoader::Category | 6 | An icon that represents a category. |
KIconLoader::Emblem | 7 | An icon that adds information to an existing icon. |
KIconLoader::Emote | 8 | An icon that expresses an emotion. |
KIconLoader::International | 9 | An icon that represents a country's flag. |
KIconLoader::Place | 10 | An icon that represents a location (e.g. 'home', 'trash'). |
KIconLoader::StatusIcon | 11 | An icon that represents an event. |
enum KIconLoader::Group
The group of the icon.
| Constant | Value | Description |
|---|---|---|
KIconLoader::NoGroup | -1 | No group |
KIconLoader::Desktop | 0 | Desktop icons |
KIconLoader::FirstGroup | 0 | First group |
KIconLoader::Toolbar | 1 | Toolbar icons |
KIconLoader::MainToolbar | 2 | Main toolbar icons |
KIconLoader::Small | 3 | Small icons, e.g. for buttons |
KIconLoader::Panel | 4 | Panel (Plasma Taskbar) icons |
KIconLoader::Dialog | 5 | Icons for use in dialog titles, page lists, etc |
KIconLoader::LastGroup | 6 | Last group |
KIconLoader::User | 7 | User icons |
[since 6.0] enum KIconLoader::MatchType
The type of a match.
| Constant | Value | Description |
|---|---|---|
KIconLoader::MatchExact | 0 | Only try to find an exact match. |
KIconLoader::MatchBest | 1 | Take the best match if there is no exact match. |
KIconLoader::MatchBestOrGreaterSize | 2 | Take the best match or the match with a greater size if there is no exact match. |
This enum was introduced in 6.0.
enum KIconLoader::States
Defines the possible states of an icon.
| Constant | Value | Description |
|---|---|---|
KIconLoader::DefaultState | 0 | The default state. |
KIconLoader::ActiveState | 1 | Icon is active. |
KIconLoader::DisabledState | 2 | Icon is disabled. |
KIconLoader::SelectedState (since 5.22) | 3 | Icon is selected. |
KIconLoader::LastState | 4 | Last state (last constant) |
enum KIconLoader::StdSizes
These are the standard sizes for icons.
| Constant | Value | Description |
|---|---|---|
KIconLoader::SizeSmall | 16 | small icons for menu entries |
KIconLoader::SizeSmallMedium | 22 | slightly larger small icons for toolbars, panels, etc |
KIconLoader::SizeMedium | 32 | medium sized icons for the desktop |
KIconLoader::SizeLarge | 48 | large sized icons for the panel |
KIconLoader::SizeHuge | 64 | huge sized icons for iconviews |
KIconLoader::SizeEnormous | 128 | enormous sized icons for iconviews |
enum KIconLoader::Type
The type of the icon.
| Constant | Value | Description |
|---|---|---|
KIconLoader::Fixed | 0 | Fixed-size icon. |
KIconLoader::Scalable | 1 | Scalable-size icon. |
KIconLoader::Threshold | 2 | A threshold icon. |
Member Function Documentation
[explicit] KIconLoader::KIconLoader(const QString &appname = QString(), const QStringList &extraSearchPaths = QStringList(), QObject *parent = nullptr)
Constructs an iconloader.
appname Add the data directories of this application to the icon search path for the "User" group. The default argument adds the directories of the current application.
extraSearchPaths additional search paths, either absolute or relative to GenericDataLocation
Usually, you use the default iconloader, which can be accessed via KIconLoader::global(), so you hardly ever have to create an iconloader object yourself. That one is the application's iconloader.
void KIconLoader::addAppDir(const QString &appname, const QString &themeBaseDir = QString())
Adds appname to the list of application specific directories with themeBaseDir as its base directory.
Assume the icons are in /home/user/app/icons/hicolor/48x48/my_app.png, the base directory would be /home/user/app/icons; KIconLoader automatically searches themeBaseDir + "/hicolor"
This directory must contain a dir structure as defined by the XDG icons specification
appname The application name.
themeBaseDir The base directory of the application's theme (eg. "/home/user/app/icons")
int KIconLoader::currentSize(KIconLoader::Group group) const
Returns the size of the specified icon group.
Using e.g. KIconLoader::SmallIcon will return 16.
group the group to check.
Returns the current size for an icon group.
[since 5.39] QPalette KIconLoader::customPalette() const
The colors that will be used for the svg stylesheet in case the loaded icons are svg-based, icons can be colored in different ways in different areas of the application
Returns the palette, if any, an invalid one if the user didn't set it
This function was introduced in 5.39.
See also setCustomPalette().
[static slot, since 5.0] void KIconLoader::emitChange(KIconLoader::Group group)
Emits an iconChanged() signal on all the KIconLoader instances in the system indicating that a system's icon group has changed in some way. It will also trigger a reload in all of them to update to the new theme.
group indicates the group that has changed
This function was introduced in 5.0.
[static] KIconLoader *KIconLoader::global()
Returns the global icon loader initialized with the application name.
[since 5.85] bool KIconLoader::hasCustomPalette() const
Returns whether we have set a custom palette using setCustomPalette
This function was introduced in 5.85.
See also resetPalette and setCustomPalette.
bool KIconLoader::hasIcon(const QString &iconName) const
[signal, since 5.0] void KIconLoader::iconChanged(int group)
Emitted when the system icon theme changes
This function was introduced in 5.0.
[signal] void KIconLoader::iconLoaderSettingsChanged()
Emitted by newIconLoader once the new settings have been loaded
QString KIconLoader::iconPath(const QString &name, int group_or_size, bool canReturnNull = false) const
Returns the path of an icon.
name The name of the icon, without extension. If an absolute path is supplied for this parameter, iconPath will return it directly.
group_or_size If positive, search icons whose size is specified by the icon group group_or_size. If negative, search icons whose size is - group_or_size. See KIconLoader::Group and KIconLoader::StdSizes
canReturnNull Can return a null string? If not, a path to the "unknown" icon will be returned.
Returns the path of an icon, can be null or the "unknown" icon when not found, depending on canReturnNull.
[since 5.48] QString KIconLoader::iconPath(const QString &name, int group_or_size, bool canReturnNull, qreal scale) const
Returns the path of an icon.
name The name of the icon, without extension. If an absolute path is supplied for this parameter, iconPath will return it directly.
group_or_size If positive, search icons whose size is specified by the icon group group_or_size. If negative, search icons whose size is - group_or_size. See KIconLoader::Group and KIconLoader::StdSizes
canReturnNull Can return a null string? If not, a path to the "unknown" icon will be returned.
scale The scale of the icon group.
Returns the path of an icon, can be null or the "unknown" icon when not found, depending on canReturnNull.
This function was introduced in 5.48.
QPixmap KIconLoader::loadIcon(const QString &name, KIconLoader::Group group, int size = 0, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList(), QString *path_store = nullptr, bool canReturnNull = false) const
Loads an icon. It will try very hard to find an icon which is suitable. If no exact match is found, a close match is searched. If neither an exact nor a close match is found, a null pixmap or the "unknown" pixmap is returned, depending on the value of the canReturnNull parameter.
name The name of the icon, without extension.
group The icon group. This will specify the size of and effects to be applied to the icon.
size If nonzero, this overrides the size specified by group. See KIconLoader::StdSizes.
state The icon state: DefaultState, ActiveState or DisabledState. Depending on the user's preferences, the iconloader may apply a visual effect to hint about its state.
overlays a list of emblem icons to overlay, by name
path_store If not null, the path of the icon is stored here, if the icon was found. If the icon was not found path_store is unaltered even if the "unknown" pixmap was returned.
canReturnNull Can return a null pixmap? If false, the "unknown" pixmap is returned when no appropriate icon has been found. Note: a null pixmap can still be returned in the event of invalid parameters, such as empty names, negative sizes, and etc.
Returns the QPixmap. Can be null when not found, depending on canReturnNull.
See also drawOverlays.
QPixmap KIconLoader::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. This is basically like loadIcon except that extra desktop themes are loaded if necessary.
Consider using QIcon::fromTheme() with a fallback to "application-octet-stream" instead.
iconName The name of the icon, without extension, usually from KMimeType.
group The icon group. This will specify the size of and effects to be applied to the icon.
size If nonzero, this overrides the size specified by group. See KIconLoader::StdSizes.
state The icon state: DefaultState, ActiveState or DisabledState. Depending on the user's preferences, the iconloader may apply a visual effect to hint about its state.
path_store If not null, the path of the icon is stored here.
overlays a list of emblem icons to overlay, by name
Returns the QPixmap. Can not be null, the "unknown" pixmap is returned when no appropriate icon has been found.
See also drawOverlays.
[since 5.81] QPixmap KIconLoader::loadScaledIcon(const QString &name, KIconLoader::Group group, qreal scale, const QSize &size = {}, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList(), QString *path_store = nullptr, bool canReturnNull = false) const
Loads an icon. It will try very hard to find an icon which is suitable. If no exact match is found, a close match is searched. If neither an exact nor a close match is found, a null pixmap or the "unknown" pixmap is returned, depending on the value of the canReturnNull parameter.
name The name of the icon, without extension.
group The icon group. This will specify the size of and effects to be applied to the icon.
scale The scale of the icon group to use. If no icon exists in the scaled group, a 1x icon with its size multiplied by the scale will be loaded instead.
size If nonzero, this overrides the size specified by group. See KIconLoader::StdSizes. The icon will be fit into size without changing the aspect ratio, which particularly matters for non-square icons.
state The icon state: DefaultState, ActiveState or DisabledState. Depending on the user's preferences, the iconloader may apply a visual effect to hint about its state.
overlays a list of emblem icons to overlay, by name
path_store If not null, the path of the icon is stored here, if the icon was found. If the icon was not found path_store is unaltered even if the "unknown" pixmap was returned.
canReturnNull Can return a null pixmap? If false, the "unknown" pixmap is returned when no appropriate icon has been found. Note: a null pixmap can still be returned in the event of invalid parameters, such as empty names, negative sizes, and etc.
Returns the QPixmap. Can be null when not found, depending on canReturnNull.
This function was introduced in 5.81.
See also drawOverlays.
[since 5.48] QPixmap KIconLoader::loadScaledIcon(const QString &name, KIconLoader::Group group, qreal scale, int size = 0, int state = KIconLoader::DefaultState, const QStringList &overlays = QStringList(), QString *path_store = nullptr, bool canReturnNull = false) const
Loads an icon. It will try very hard to find an icon which is suitable. If no exact match is found, a close match is searched. If neither an exact nor a close match is found, a null pixmap or the "unknown" pixmap is returned, depending on the value of the canReturnNull parameter.
name The name of the icon, without extension.
group The icon group. This will specify the size of and effects to be applied to the icon.
scale The scale of the icon group to use. If no icon exists in the scaled group, a 1x icon with its size multiplied by the scale will be loaded instead.
size If nonzero, this overrides the size specified by group. See KIconLoader::StdSizes.
state The icon state: DefaultState, ActiveState or DisabledState. Depending on the user's preferences, the iconloader may apply a visual effect to hint about its state.
overlays a list of emblem icons to overlay, by name
path_store If not null, the path of the icon is stored here, if the icon was found. If the icon was not found path_store is unaltered even if the "unknown" pixmap was returned.
canReturnNull Can return a null pixmap? If false, the "unknown" pixmap is returned when no appropriate icon has been found. Note: a null pixmap can still be returned in the event of invalid parameters, such as empty names, negative sizes, and etc.
Returns the QPixmap. Can be null when not found, depending on canReturnNull.
This function was introduced in 5.48.
See also drawOverlays.
[since 5.88] QPixmap KIconLoader::loadScaledIcon(const QString &name, KIconLoader::Group group, qreal scale, const QSize &size, int state, const QStringList &overlays, QString *path_store, bool canReturnNull, const std::optional<KIconColors> &colorScheme) const
Loads an icon. It will try very hard to find an icon which is suitable. If no exact match is found, a close match is searched. If neither an exact nor a close match is found, a null pixmap or the "unknown" pixmap is returned, depending on the value of the canReturnNull parameter.
name The name of the icon, without extension.
group The icon group. This will specify the size of and effects to be applied to the icon.
scale The scale of the icon group to use. If no icon exists in the scaled group, a 1x icon with its size multiplied by the scale will be loaded instead.
size If nonzero, this overrides the size specified by group. See KIconLoader::StdSizes. The icon will be fit into size without changing the aspect ratio, which particularly matters for non-square icons.
state The icon state: DefaultState, ActiveState or
DisabledState. Depending on the user's preferences, the iconloader may apply a visual effect to hint about its state.
overlays a list of emblem icons to overlay, by name
path_store If not null, the path of the icon is stored here, if the icon was found. If the icon was not found path_store is unaltered even if the "unknown" pixmap was returned. canReturnNull Can return a null pixmap? If false, the "unknown" pixmap is returned when no appropriate icon has been found. Note: a null pixmap can still be returned in the event of invalid parameters, such as empty names, negative sizes, and etc.
colorScheme will define the stylesheet used to color this icon. Note this will only work if name is an svg file.
Returns the QPixmap. Can be null when not found, depending on canReturnNull.
This function was introduced in 5.88.
See also drawOverlays.
[since 6.11] QStringList KIconLoader::queryIcons() const
Queries all available icons.
This function was introduced in 6.11.
QStringList KIconLoader::queryIcons(int group_or_size, KIconLoader::Context context = KIconLoader::Any) const
Queries all available icons for a specific group, having a specific context.
group_or_size If positive, search icons whose size is specified by the icon group group_or_size. If negative, search icons whose size is - group_or_size. See KIconLoader::Group and KIconLoader::StdSizes
context The icon context. Returns a list of all icons
QStringList KIconLoader::queryIconsByContext(int group_or_size, KIconLoader::Context context = KIconLoader::Any) const
Queries all available icons for a specific context.
group_or_size The icon preferred group or size. If available at this group or size, those icons will be returned, in other case, icons of undefined size will be returned. Positive numbers are groups, negative numbers are negated sizes. See KIconLoader::Group and KIconLoader::StdSizes
context The icon context.
Returns A QStringList containing the icon names available for that context
QStringList KIconLoader::queryIconsByDir(const QString &iconsDir) const
Returns a list of all icons (*.png or *.xpm extension) in the given directory.
iconsDir the directory to search in Returns A QStringList containing the icon paths
void KIconLoader::reconfigure(const QString &appname, const QStringList &extraSearchPaths = QStringList())
Reconfigure the icon loader, for instance to change the associated app name or extra search paths.
This also clears the in-memory pixmap cache (even if the appname didn't change, which is useful for unittests)
appname the application name (empty for the global iconloader)
extraSearchPaths additional search paths, either absolute or relative to GenericDataLocation
[since 5.39] void KIconLoader::resetPalette()
Resets the custom palette used by the KIconLoader to use the QGuiApplication::palette() again (and to follow it in case the application's palette changes)
This function was introduced in 5.39.
[since 5.0] QStringList KIconLoader::searchPaths() const
Returns all the search paths for this icon loader, either absolute or relative to GenericDataLocation.
Mostly internal (for KIconDialog).
This function was introduced in 5.0.
[since 5.39] void KIconLoader::setCustomPalette(const QPalette &palette)
Sets the colors for this KIconLoader.
Note: if you set a custom palette, if you are using some colors from application's palette, you need to track the application palette changes by yourself.
If you no longer wish to use a custom palette, use resetPalette()
This function was introduced in 5.39.
See also customPalette() and resetPalette().
KIconTheme *KIconLoader::theme() const
Returns a pointer to the current theme. Can be used to query available and default sizes for groups.
Note: The KIconTheme will change if reconfigure() is called and therefore it's not recommended to store the pointer anywhere.
Returns a pointer to the current theme. 0 if no theme set.
[static] QPixmap KIconLoader::unknown()
Returns the unknown icon. An icon that is used when no other icon can be found.
Related Non-Members
[since 5.0] QIcon icon(const QString &iconName, KIconLoader *iconLoader = nullptr)
Returns a QIcon with an appropriate KIconEngine to perform loading and rendering. KIcons thus adhere to KDE style and effect standards.
This function was introduced in 5.0.
[since 5.0] QIcon icon(const QString &iconName, const KIconColors &colors, KIconLoader *iconLoader = nullptr)
Returns a QIcon with an appropriate KIconEngine to perform loading and rendering. KIcons thus adhere to KDE style and effect standards.
This function was introduced in 5.0.
[since 5.0] QIcon icon(const QString &iconName, const QStringList &overlays, KIconLoader *iconLoader = nullptr)
Returns a QIcon for the given icon, with additional overlays.
This function was introduced in 5.0.