KIconThemes

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

KDE's Doxygen guidelines are available online.