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 KICONTHEME_H
11#define KICONTHEME_H
12
13#include <kiconthemes_export.h>
14
15#include <QList>
16#include <QString>
17#include <QStringList>
18
19#include <memory>
20
21#include "kiconloader.h"
22
23class QAction;
24
25/**
26 * @internal
27 * Class to use/access icon themes in KDE. This class is used by the
28 * iconloader but can be used by others too.
29 * @warning You should not use this class externally. This class is exported because
30 * the KCM needs it.
31 * @see KIconLoader
32 */
33class KICONTHEMES_EXPORT KIconTheme
34{
35public:
36 /**
37 * Load an icon theme by name.
38 * @param name the name of the theme (e.g. "hicolor" or "keramik")
39 * @param appName the name of the application. Can be null. This argument
40 * allows applications to have themed application icons.
41 * @param basePathHint optional hint where to search the app themes.
42 * This is appended at the end of the search paths
43 */
44 explicit KIconTheme(const QString &name, const QString &appName = QString(), const QString &basePathHint = QString());
45 ~KIconTheme();
46
47 KIconTheme(const KIconTheme &) = delete;
48 KIconTheme &operator=(const KIconTheme &) = delete;
49
50 /**
51 * The stylized name of the icon theme.
52 * @return the (human-readable) name of the theme
53 */
54 QString name() const;
55
56 /**
57 * The internal name of the icon theme (same as the name argument passed
58 * to the constructor).
59 * @return the internal name of the theme
60 */
61 QString internalName() const;
62
63 /**
64 * A description for the icon theme.
65 * @return a human-readable description of the theme, QString()
66 * if there is none
67 */
68 QString description() const;
69
70 /**
71 * Return the name of the "example" icon. This can be used to
72 * present the theme to the user.
73 * @return the name of the example icon, QString() if there is none
74 */
75 QString example() const;
76
77 /**
78 * Return the name of the screenshot.
79 * @return the name of the screenshot, QString() if there is none
80 */
81 QString screenshot() const;
82
83 /**
84 * Returns the toplevel theme directory.
85 * @return the directory of the theme
86 */
87 QString dir() const;
88
89 /**
90 * The themes this icon theme falls back on.
91 * @return a list of icon themes that are used as fall-backs
92 */
93 QStringList inherits() const;
94
95 /**
96 * The icon theme exists?
97 * @return true if the icon theme is valid
98 */
99 bool isValid() const;
100
101 /**
102 * The icon theme should be hidden to the user?
103 * @return true if the icon theme is hidden
104 */
105 bool isHidden() const;
106
107 /**
108 * The minimum display depth required for this theme. This can either
109 * be 8 or 32.
110 * @return the minimum bpp (8 or 32)
111 */
112 int depth() const;
113
114 /**
115 * The default size of this theme for a certain icon group.
116 * @param group The icon group. See KIconLoader::Group.
117 * @return The default size in pixels for the given icon group.
118 */
119 int defaultSize(KIconLoader::Group group) const;
120
121 /**
122 * Query available sizes for a group.
123 * @param group The icon group. See KIconLoader::Group.
124 * @return a list of available sizes for the given group
125 */
126 QList<int> querySizes(KIconLoader::Group group) const;
127
128 /**
129 * Query available icons for a size and context.
130 * @param size the size of the icons
131 * @param context the context of the icons
132 * @return the list of icon names
133 */
134 QStringList queryIcons(int size, KIconLoader::Context context = KIconLoader::Any) const;
135
136 /**
137 * Query available icons for a context and preferred size.
138 * @param size the size of the icons
139 * @param context the context of the icons
140 * @return the list of icon names
141 */
142 QStringList queryIconsByContext(int size, KIconLoader::Context context = KIconLoader::Any) const;
143
144 /**
145 * Lookup an icon in the theme.
146 * @param name The name of the icon, with extension.
147 * @param size The desired size of the icon.
148 * @param match The matching mode. KIconLoader::MatchExact returns an icon
149 * only if matches exactly. KIconLoader::MatchBest returns the best matching
150 * icon.
151 * @return An absolute path to the file of the icon if it's found, QString() otherwise.
152 * @see KIconLoader::isValid will return true, and false otherwise.
153 */
154 QString iconPath(const QString &name, int size, KIconLoader::MatchType match) const;
155
156 /**
157 * Lookup an icon in the theme.
158 * @param name The name of the icon, with extension.
159 * @param size The desired size of the icon.
160 * @param match The matching mode. KIconLoader::MatchExact returns an icon
161 * only if matches exactly. KIconLoader::MatchBest returns the best matching
162 * icon.
163 * @param scale The scale of the icon group.
164 * @return An absolute path to the file of the icon if it's found, QString() otherwise.
165 * @see KIconLoader::isValid will return true, and false otherwise.
166 * @since 5.48
167 */
168 // TODO KF6 merge iconPath() with and without "scale" and move that argument after "size"
169 QString iconPath(const QString &name, int size, KIconLoader::MatchType match, qreal scale) const;
170
171 /**
172 * Lookup an icon in the theme.
173 * @param name The name of the icon, without extension.
174 * @param size The desired size of the icon.
175 * @param match The matching mode. KIconLoader::MatchExact returns an icon
176 * only if matches exactly. KIconLoader::MatchBest returns the best matching
177 * icon.
178 * @return An absolute path to the file of the icon if it's found, QString() otherwise.
179 * @see KIconLoader::isValid will return true, and false otherwise.
180 *
181 * @since 5.22
182 */
183 QString iconPathByName(const QString &name, int size, KIconLoader::MatchType match) const;
184
185 /**
186 * Lookup an icon in the theme.
187 * @param name The name of the icon, without extension.
188 * @param size The desired size of the icon.
189 * @param match The matching mode. KIconLoader::MatchExact returns an icon
190 * only if matches exactly. KIconLoader::MatchBest returns the best matching
191 * icon.
192 * @param scale The scale of the icon group.
193 * @return An absolute path to the file of the icon if it's found, QString() otherwise.
194 * @see KIconLoader::isValid will return true, and false otherwise.
195 *
196 * @since 5.48
197 */
198 // TODO KF6 merge iconPathByName() with and without "scale" and move that argument after "size"
199 QString iconPathByName(const QString &name, int size, KIconLoader::MatchType match, qreal scale) const;
200
201 /**
202 * Returns true if the theme has any icons for the given context.
203 */
204 bool hasContext(KIconLoader::Context context) const;
205
206 /**
207 * If true, this theme is made of SVG icons that will be colorized following the system
208 * color scheme. This is necessary for monochrome themes that should look visible on both
209 * light and dark color schemes.
210 * @return true if the SVG will be colorized with a stylesheet.
211 * @since 5.22
212 */
213 bool followsColorScheme() const;
214
215 /**
216 * List all icon themes installed on the system, global and local.
217 * @return the list of all icon themes
218 */
219 static QStringList list();
220
221 /**
222 * Returns the current icon theme.
223 * @return the name of the current theme
224 */
225 static QString current();
226
227 /**
228 * Force a current theme and disable automatic resolution of the current
229 * theme in favor of the forced theme.
230 *
231 * To reset a forced theme, simply set an empty themeName.
232 *
233 * @param themeName name of the theme to force as current theme, or an
234 * empty string to unset theme forcing.
235 *
236 * @note This should only be used when a very precise expectation about
237 * the current theme is present. Most notably in unit tests
238 * this can be used to force a given theme.
239 *
240 * @warning A forced theme persists across reconfigure() calls!
241 *
242 * @see current
243 * @since 5.23
244 */
245 static void forceThemeForTests(const QString &themeName);
246
247 /**
248 * Reconfigure the theme.
249 */
250 static void reconfigure();
251
252 /**
253 * Returns the default icon theme.
254 * @return the name of the default theme name
255 */
256 static QString defaultThemeName();
257
258private:
259 std::unique_ptr<class KIconThemePrivate> const d;
260};
261
262#endif
263

source code of kiconthemes/src/kicontheme.h