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 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 * \class KIconTheme
27 * \inmodule KIconThemes
28 *
29 * \brief Class to use/access icon themes in KDE.
30 *
31 * This class is used by the
32 * iconloader but can be used by others too.
33 * \warning You should not use this class externally. This class is exported because
34 * the KCM needs it.
35 * \sa KIconLoader
36 */
37class KICONTHEMES_EXPORT KIconTheme
38{
39public:
40 /*!
41 * Load an icon theme by name.
42 *
43 * \a name the name of the theme (e.g. "hicolor" or "keramik")
44 *
45 * \a appName the name of the application. Can be null. This argument
46 * allows applications to have themed application icons.
47 *
48 * \a basePathHint optional hint where to search the app themes.
49 * This is appended at the end of the search paths
50 */
51 explicit KIconTheme(const QString &name, const QString &appName = QString(), const QString &basePathHint = QString());
52 ~KIconTheme();
53
54 KIconTheme(const KIconTheme &) = delete;
55 KIconTheme &operator=(const KIconTheme &) = delete;
56
57 /*!
58 * The stylized name of the icon theme.
59 *
60 * Returns the (human-readable) name of the theme
61 */
62 QString name() const;
63
64 /*!
65 * The internal name of the icon theme (same as the name argument passed
66 * to the constructor).
67 *
68 * Returns the internal name of the theme
69 */
70 QString internalName() const;
71
72 /*!
73 * A description for the icon theme.
74 *
75 * Returns a human-readable description of the theme, QString()
76 * if there is none
77 */
78 QString description() const;
79
80 /*!
81 * Return the name of the "example" icon. This can be used to
82 * present the theme to the user.
83 *
84 * Returns the name of the example icon, QString() if there is none
85 */
86 QString example() const;
87
88 /*!
89 * Returns the name of the screenshot, QString() if there is none
90 */
91 QString screenshot() const;
92
93 /*!
94 * Returns the toplevel theme directory.
95 */
96 QString dir() const;
97
98 /*!
99 * The themes this icon theme falls back on.
100 *
101 * Returns a list of icon themes that are used as fall-backs
102 */
103 QStringList inherits() const;
104
105 /*!
106 * The icon theme exists?
107 *
108 * Returns true if the icon theme is valid
109 */
110 bool isValid() const;
111
112 /*!
113 * The icon theme should be hidden to the user?
114 *
115 * Returns true if the icon theme is hidden
116 */
117 bool isHidden() const;
118
119 /*!
120 * The minimum display depth required for this theme. This can either
121 * be 8 or 32.
122 *
123 * Returns the minimum bpp (8 or 32)
124 */
125 int depth() const;
126
127 /*!
128 * The default size of this theme for a certain icon group.
129 *
130 * \a group The icon group. See KIconLoader::Group.
131 *
132 * Returns The default size in pixels for the given icon group.
133 */
134 int defaultSize(KIconLoader::Group group) const;
135
136 /*!
137 * Query available sizes for a group.
138 *
139 * \a group The icon group. See KIconLoader::Group.
140 *
141 * Returns a list of available sizes for the given group
142 */
143 QList<int> querySizes(KIconLoader::Group group) const;
144
145 /*!
146 * Query all available icons.
147 *
148 * Returns the list of icon names
149 *
150 * \since 6.11
151 */
152 [[nodiscard]] QStringList queryIcons() const;
153
154 /*!
155 * Query available icons for a size and context.
156 *
157 * \a size the size of the icons
158 *
159 * \a context the context of the icons
160 *
161 * Returns the list of icon names
162 */
163 QStringList queryIcons(int size, KIconLoader::Context context = KIconLoader::Any) const;
164
165 /*!
166 * Query available icons for a context and preferred size.
167 *
168 * \a size the size of the icons
169 *
170 * \a context the context of the icons
171 *
172 * Returns the list of icon names
173 */
174 QStringList queryIconsByContext(int size, KIconLoader::Context context = KIconLoader::Any) const;
175
176 /*!
177 * Lookup an icon in the theme.
178 *
179 * \a name The name of the icon, with extension.
180 *
181 * \a size The desired size of the icon.
182 *
183 * \a match The matching mode. KIconLoader::MatchExact returns an icon
184 * only if matches exactly. KIconLoader::MatchBest returns the best matching
185 * icon.
186 *
187 * Returns An absolute path to the file of the icon if it's found, QString() otherwise.
188 *
189 * KIconLoader::isValid will return true, and false otherwise.
190 */
191 QString iconPath(const QString &name, int size, KIconLoader::MatchType match) const;
192
193 // TODO KF6 merge iconPath() with and without "scale" and move that argument after "size"
194 /*!
195 * Lookup an icon in the theme.
196 *
197 * \a name The name of the icon, with extension.
198 *
199 * \a size The desired size of the icon.
200 *
201 * \a match The matching mode. KIconLoader::MatchExact returns an icon
202 * only if matches exactly. KIconLoader::MatchBest returns the best matching
203 * icon.
204 *
205 * \a scale The scale of the icon group.
206 *
207 * Returns An absolute path to the file of the icon if it's found, QString() otherwise.
208 *
209 * KIconLoader::isValid will return true, and false otherwise.
210 * \since 5.48
211 */
212 QString iconPath(const QString &name, int size, KIconLoader::MatchType match, qreal scale) const;
213
214 /*!
215 * Lookup an icon in the theme.
216 *
217 * \a name The name of the icon, without extension.
218 *
219 * \a size The desired size of the icon.
220 *
221 * \a match The matching mode. KIconLoader::MatchExact returns an icon
222 * only if matches exactly. KIconLoader::MatchBest returns the best matching
223 * icon.
224 *
225 * Returns An absolute path to the file of the icon if it's found, QString() otherwise.
226 *
227 * KIconLoader::isValid will return true, and false otherwise.
228 *
229 * \since 5.22
230 */
231 QString iconPathByName(const QString &name, int size, KIconLoader::MatchType match) const;
232
233 // TODO KF6 merge iconPathByName() with and without "scale" and move that argument after "size"
234 /*!
235 * Lookup an icon in the theme.
236 *
237 * \a name The name of the icon, without extension.
238 *
239 * \a size The desired size of the icon.
240 *
241 * \a match The matching mode. KIconLoader::MatchExact returns an icon
242 * only if matches exactly. KIconLoader::MatchBest returns the best matching
243 * icon.
244 *
245 * \a scale The scale of the icon group.
246 *
247 * Returns An absolute path to the file of the icon if it's found, QString() otherwise.
248 *
249 * KIconLoader::isValid will return true, and false otherwise.
250 *
251 * \since 5.48
252 */
253 QString iconPathByName(const QString &name, int size, KIconLoader::MatchType match, qreal scale) const;
254
255 /*!
256 * Returns true if the theme has any icons for the given context.
257 */
258 bool hasContext(KIconLoader::Context context) const;
259
260 /*!
261 * If true, this theme is made of SVG icons that will be colorized following the system
262 * color scheme. This is necessary for monochrome themes that should look visible on both
263 * light and dark color schemes.
264 *
265 * Returns true if the SVG will be colorized with a stylesheet.
266 * \since 5.22
267 */
268 bool followsColorScheme() const;
269
270 /*!
271 * List all icon themes installed on the system, global and local.
272 *
273 * Returns the list of all icon themes
274 */
275 static QStringList list();
276
277 /*!
278 * Returns the current icon theme.
279 */
280 static QString current();
281
282 /*!
283 * Force a current theme and disable automatic resolution of the current
284 * theme in favor of the forced theme.
285 *
286 * To reset a forced theme, simply set an empty themeName.
287 *
288 * \a themeName name of the theme to force as current theme, or an
289 * empty string to unset theme forcing.
290 *
291 * \note This should only be used when a very precise expectation about
292 * the current theme is present. Most notably in unit tests
293 * this can be used to force a given theme.
294 *
295 * \warning A forced theme persists across reconfigure() calls!
296 *
297 * \sa current
298 * \since 5.23
299 */
300 static void forceThemeForTests(const QString &themeName);
301
302 /*!
303 * Reconfigure the theme.
304 */
305 static void reconfigure();
306
307 /*!
308 * Returns the name of the default theme name
309 */
310 static QString defaultThemeName();
311
312 /*!
313 * Enforces the Breeze icon theme (including our KIconEngine for re-coloring).
314 *
315 * If the user has configured a different icon set, that one will be taken.
316 *
317 * (following the settings in the application configuration with fallback to kdeglobals)
318 *
319 * Must be called before the construction of the first Q(Core)Application, as it
320 * might need to modify plugin loading and installs a startup function.
321 *
322 * If the application is already using the KDE platform theme, the icon set will not
323 * be touched and the platform theme will ensure proper theming.
324 *
325 * Does setup the needed KColorSchemeManager to follow the system color mode starting
326 * with version 6.6.
327 *
328 * \since 6.3
329 */
330 static void initTheme();
331
332private:
333 std::unique_ptr<class KIconThemePrivate> const d;
334};
335
336#endif
337

source code of kiconthemes/src/kicontheme.h