1/* vi: ts=8 sts=4 sw=4
2 *
3 * This file is part of the KDE project, module kdecore.
4 * Copyright (C) 2000 Geert Jansen <jansen@kde.org>
5 * Antonio Larrosa <larrosa@kde.org>
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License version 2 as published by the Free Software Foundation.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public License
17 * along with this library; see the file COPYING.LIB. If not, write to
18 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22#ifndef KICONLOADER_H
23#define KICONLOADER_H
24
25#include <QtCore/QString>
26#include <QtCore/QStringList>
27#include <QtCore/QObject>
28
29#include <kglobal.h>
30#include <kdeui_export.h>
31
32class QIcon;
33class QMovie;
34class QPixmap;
35
36class KComponentData;
37class KIconLoaderPrivate;
38class KStandardDirs;
39class KIconEffect;
40class KIconTheme;
41
42/**
43 * Iconloader for KDE.
44 *
45 * KIconLoader will load the current icon theme and all its base themes.
46 * Icons will be searched in any of these themes. Additionally, it caches
47 * icons and applies effects according to the user's preferences.
48 *
49 * In KDE, it is encouraged to load icons by "Group". An icon group is a
50 * location on the screen where icons are being used. Standard groups are:
51 * Desktop, Toolbar, MainToolbar, Small and Panel. Each group has some
52 * centrally configured properties bound to it, including the icon size
53 * and effects. This makes it possible to offer a consistent icon look in
54 * all KDE applications.
55 *
56 * The standard groups are defined below.
57 *
58 * @li KIconLoader::Desktop: Icons in the iconview of konqueror, kdesktop and similar apps.
59 * @li KIconLoader::Toolbar: Icons in toolbars.
60 * @li KIconLoader::MainToolbar: Icons in the main toolbars.
61 * @li KIconLoader::Small: Various small (typical 16x16) places: titlebars, listviews
62 * and menu entries.
63 * @li KIconLoader::Panel: Icons in kicker's panel
64 *
65 * The icons are stored on disk in an icon theme or in a standalone
66 * directory. The icon theme directories contain multiple sizes and/or
67 * depths for the same icon. The iconloader will load the correct one based
68 * on the icon group and the current theme. Icon themes are stored globally
69 * in share/icons, or, application specific in share/apps/$appdir/icons.
70 *
71 * The standalone directories contain just one version of an icon. The
72 * directories that are searched are: $appdir/pics and $appdir/toolbar.
73 * Icons in these directories can be loaded by using the special group
74 * "User".
75 *
76 */
77class KDEUI_EXPORT KIconLoader : public QObject
78{
79 Q_OBJECT
80 Q_ENUMS(Context)
81 Q_ENUMS(Type)
82 Q_ENUMS(MatchType)
83 Q_ENUMS(Group)
84 Q_ENUMS(StdSizes)
85 Q_ENUMS(States)
86
87public:
88 /**
89 * Defines the context of the icon.
90 */
91 enum Context {
92 Any, ///< Some icon with unknown purpose.
93 Action, ///< An action icon (e.g. 'save', 'print').
94 Application, ///< An icon that represents an application.
95 Device, ///< An icon that represents a device.
96 FileSystem, ///< An icon that represents a file system. @deprecated Use Place instead.
97 MimeType, ///< An icon that represents a mime type (or file type).
98 Animation, ///< An icon that is animated.
99 Category, ///< An icon that represents a category.
100 Emblem, ///< An icon that adds information to an existing icon.
101 Emote, ///< An icon that expresses an emotion.
102 International, ///< An icon that represents a country's flag.
103 Place, ///< An icon that represents a location (e.g. 'home', 'trash').
104 StatusIcon ///< An icon that represents an event.
105 };
106
107 /**
108 * The type of the icon.
109 */
110 enum Type {
111 Fixed, ///< Fixed-size icon.
112 Scalable, ///< Scalable-size icon.
113 Threshold ///< A threshold icon.
114 };
115
116 /**
117 * The type of a match.
118 */
119 enum MatchType {
120 MatchExact, ///< Only try to find an exact match.
121 MatchBest ///< Take the best match if there is no exact match.
122 };
123
124 /**
125 * The group of the icon.
126 */
127 enum Group {
128 /// No group
129 NoGroup=-1,
130 /// Desktop icons
131 Desktop=0,
132 /// First group
133 FirstGroup=0,
134 /// Toolbar icons
135 Toolbar,
136 /// Main toolbar icons
137 MainToolbar,
138 /// Small icons, e.g. for buttons
139 Small,
140 /// Panel (Plasma Taskbar) icons
141 Panel,
142 /// Icons for use in dialog titles, page lists, etc
143 Dialog,
144 /// Last group
145 LastGroup,
146 /// User icons
147 User
148 };
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 };
167
168 /**
169 * Defines the possible states of an icon.
170 */
171 enum States {
172 DefaultState, ///< The default state.
173 ActiveState, ///< Icon is active.
174 DisabledState, ///< Icon is disabled.
175 LastState ///< Last state (last constant)
176 };
177
178 /**
179 * Constructs an iconloader.
180 * @param appname Add the data directories of this application to the
181 * icon search path for the "User" group. The default argument adds the
182 * directories of the current application.
183 * @param dirs the KStandardDirs object to use. If null the global one is used
184 *
185 * Usually, you use the default iconloader, which can be accessed via
186 * KIconLoader::global(), so you hardly ever have to create an
187 * iconloader object yourself. That one is the current KComponentData's
188 * (typically KApplication's) iconloader.
189 */
190 explicit KIconLoader(const QString& appname=QString(), KStandardDirs *dirs = 0, QObject* parent = 0);
191
192 /**
193 * Constructs an iconloader.
194 * @param componentData the KComponentData to use to create this icon loader.
195 *
196 * Usually, you use the default iconloader, which can be accessed via
197 * KIconLoader::global(), so you hardly ever have to create an
198 * iconloader object yourself. That one is the current KComponentData's
199 * (typically KApplication's) iconloader.
200 */
201 explicit KIconLoader(const KComponentData &componentData, QObject* parent = 0);
202
203 /**
204 * Cleanup
205 */
206 ~KIconLoader();
207
208 /**
209 * Returns the global icon loader initialized with the global KComponentData.
210 * @return global icon loader
211 */
212 static KIconLoader* global();
213
214 /**
215 * Adds @p appname to the list of application specific directories.
216 * @param appname The application name.
217 */
218 void addAppDir(const QString& appname);
219
220 /**
221 * Loads an icon. It will try very hard to find an icon which is
222 * suitable. If no exact match is found, a close match is searched.
223 * If neither an exact nor a close match is found, a null pixmap or
224 * the "unknown" pixmap is returned, depending on the value of the
225 * @p canReturnNull parameter.
226 *
227 * @param name The name of the icon, without extension.
228 * @param group The icon group. This will specify the size of and effects to
229 * be applied to the icon.
230 * @param size If nonzero, this overrides the size specified by @p group.
231 * See KIconLoader::StdSizes.
232 * @param state The icon state: @p DefaultState, @p ActiveState or
233 * @p DisabledState. Depending on the user's preferences, the iconloader
234 * may apply a visual effect to hint about its state.
235 * @param overlays a list of emblem icons to overlay, by name. the emblem
236 * prefix is applied automatically to each name, e.g.
237 * "zip" becomes "emblem-zip"
238 * @param path_store If not null, the path of the icon is stored here,
239 * if the icon was found. If the icon was not found @p path_store
240 * is unaltered even if the "unknown" pixmap was returned.
241 * @param canReturnNull Can return a null pixmap? If false, the
242 * "unknown" pixmap is returned when no appropriate icon has been
243 * found. <em>Note:</em> a null pixmap can still be returned in the
244 * event of invalid parameters, such as empty names, negative sizes,
245 * and etc.
246 * @return the QPixmap. Can be null when not found, depending on
247 * @p canReturnNull.
248 */
249 QPixmap loadIcon(const QString& name, KIconLoader::Group group, int size=0,
250 int state=KIconLoader::DefaultState, const QStringList &overlays = QStringList(),
251 QString *path_store=0L,
252 bool canReturnNull=false) const;
253
254 /**
255 * Loads an icon for a mimetype.
256 * This is basically like loadIcon except that extra desktop themes are loaded if necessary.
257 *
258 * @param iconName The name of the icon, without extension, usually from KMimeType.
259 * @param group The icon group. This will specify the size of and effects to
260 * be applied to the icon.
261 * @param size If nonzero, this overrides the size specified by @p group.
262 * See KIconLoader::StdSizes.
263 * @param state The icon state: @p DefaultState, @p ActiveState or
264 * @p DisabledState. Depending on the user's preferences, the iconloader
265 * may apply a visual effect to hint about its state.
266 * @param path_store If not null, the path of the icon is stored here.
267 * @param overlays a list of emblem icons to overlay, by name. the emblem
268 * prefix is applied automatically to each name, e.g.
269 * "zip" becomes "emblem-zip"
270 * @return the QPixmap. Can not be null, the
271 * "unknown" pixmap is returned when no appropriate icon has been found.
272 */
273 QPixmap loadMimeTypeIcon( const QString& iconName, KIconLoader::Group group, int size=0,
274 int state=KIconLoader::DefaultState, const QStringList &overlays = QStringList(),
275 QString *path_store=0 ) const;
276
277 /**
278 * Creates an icon set, that will do on-demand loading of the icon.
279 * Loading itself is done by calling loadIcon .
280 *
281 * @param name The name of the icon, without extension.
282 * @param group The icon group. This will specify the size of and effects to
283 * be applied to the icon.
284 * @param size If nonzero, this overrides the size specified by @p group.
285 * See KIconLoader::StdSizes.
286 * @param canReturnNull Can return a null iconset? If false, iconset
287 * containing the "unknown" pixmap is returned when no appropriate icon has
288 * been found.
289 * @return the icon set. Can be null when not found, depending on
290 * @p canReturnNull.
291 *
292 * @deprecated use KIcon instead, which uses the iconloader internally
293 */
294#ifndef KDE_NO_DEPRECATED
295 KDE_DEPRECATED QIcon loadIconSet(const QString& name, KIconLoader::Group group, int size = 0,
296 bool canReturnNull = false);
297#endif
298
299 /**
300 * Returns the path of an icon.
301 * @param name The name of the icon, without extension. If an absolute
302 * path is supplied for this parameter, iconPath will return it
303 * directly.
304 * @param group_or_size If positive, search icons whose size is
305 * specified by the icon group @p group_or_size. If negative, search
306 * icons whose size is - @p group_or_size.
307 * See KIconLoader::Group and KIconLoader::StdSizes
308 * @param canReturnNull Can return a null string? If not, a path to the
309 * "unknown" icon will be returned.
310 * @return the path of an icon, can be null or the "unknown" icon when
311 * not found, depending on @p canReturnNull.
312 */
313 QString iconPath(const QString& name, int group_or_size,
314 bool canReturnNull=false) const;
315
316 /**
317 * Loads an animated icon.
318 * @param name The name of the icon.
319 * @param group The icon group. See loadIcon().
320 * @param size Override the default size for @p group.
321 * See KIconLoader::StdSizes.
322 * @param parent The parent object of the returned QMovie.
323 * @return A QMovie object. Can be null if not found or not valid.
324 * Ownership is passed to the caller.
325 */
326 QMovie *loadMovie(const QString& name, KIconLoader::Group group, int size=0, QObject *parent=0) const;
327
328 /**
329 * Returns the path to an animated icon.
330 * @param name The name of the icon.
331 * @param group The icon group. See loadIcon().
332 * @param size Override the default size for @p group.
333 * See KIconLoader::StdSizes.
334 * @return the full path to the movie, ready to be passed to QMovie's constructor.
335 * Empty string if not found.
336 */
337 QString moviePath(const QString& name, KIconLoader::Group group, int size=0) const;
338
339 /**
340 * Loads an animated icon as a series of still frames. If you want to load
341 * a .mng animation as QMovie instead, please use loadMovie() instead.
342 * @param name The name of the icon.
343 * @param group The icon group. See loadIcon().
344 * @param size Override the default size for @p group.
345 * See KIconLoader::StdSizes.
346 * @return A QStringList containing the absolute path of all the frames
347 * making up the animation.
348 */
349 QStringList loadAnimated(const QString& name, KIconLoader::Group group, int size=0) const;
350
351 /**
352 * Queries all available icons for a specific group, having a specific
353 * context.
354 * @param group_or_size If positive, search icons whose size is
355 * specified by the icon group @p group_or_size. If negative, search
356 * icons whose size is - @p group_or_size.
357 * See KIconLoader::Group and KIconLoader::StdSizes
358 * @param context The icon context.
359 * @return a list of all icons
360 */
361 QStringList queryIcons(int group_or_size, KIconLoader::Context context=KIconLoader::Any) const;
362
363 /**
364 * Queries all available icons for a specific context.
365 * @param group_or_size The icon preferred group or size. If available
366 * at this group or size, those icons will be returned, in other case,
367 * icons of undefined size will be returned. Positive numbers are groups,
368 * negative numbers are negated sizes. See KIconLoader::Group and
369 * KIconLoader::StdSizes
370 * @param context The icon context.
371 * @return A QStringList containing the icon names
372 * available for that context
373 */
374 QStringList queryIconsByContext(int group_or_size,
375 KIconLoader::Context context=KIconLoader::Any) const;
376
377 /**
378 * @internal
379 */
380 bool hasContext( KIconLoader::Context context ) const;
381
382 /**
383 * Returns a list of all icons (*.png or *.xpm extension) in the
384 * given directory.
385 * @param iconsDir the directory to search in
386 * @return A QStringList containing the icon paths
387 */
388 QStringList queryIconsByDir( const QString& iconsDir ) const;
389
390 /**
391 * Returns the current size of the icon group.
392 * Using e.g. KIconLoader::SmallIcon will retrieve the icon size
393 * that is currently set from System Settings->Appearance->Icon
394 * sizes. SmallIcon for instance, would typically be 16x16, but
395 * the user could increase it and this setting would change as well.
396 * @param group the group to check.
397 * @return the current size for an icon group.
398 */
399 int currentSize(KIconLoader::Group group) const;
400
401 /**
402 * Returns a pointer to the current theme. Can be used to query
403 * available and default sizes for groups.
404 * @note The KIconTheme will change if reconfigure() is called and
405 * therefore it's not recommended to store the pointer anywhere.
406 * @return a pointer to the current theme. 0 if no theme set.
407 */
408 KIconTheme *theme() const;
409
410 /**
411 * Returns a pointer to the KIconEffect object used by the icon loader.
412 * @return the KIconEffect.
413 */
414 KIconEffect *iconEffect() const;
415
416 /**
417 * Called by KComponentData::newIconLoader to reconfigure the icon loader.
418 * @param _appname the new application name
419 * @param _dirs the new standard directories. If 0, the directories
420 * from KGlobal will be taken.
421 */
422 void reconfigure( const QString& _appname, KStandardDirs *_dirs );
423
424 /**
425 * Returns the unknown icon. An icon that is used when no other icon
426 * can be found.
427 * @return the unknown pixmap
428 */
429 static QPixmap unknown();
430
431 /**
432 * Checks whether the user wants to blend the icons with the background
433 * using the alpha channel information for a given group.
434 * @param group the group to check
435 * @return true if alpha blending is desired
436 * @obsolete
437 */
438 bool alphaBlending( KIconLoader::Group group ) const;
439
440 /**
441 * Adds all the default themes from other desktops at the end of
442 * the list of icon themes.
443 */
444 void addExtraDesktopThemes();
445
446 /**
447 * Returns if the default icon themes of other desktops have been added
448 * to the list of icon themes where icons are searched.
449 */
450 bool extraDesktopThemesAdded() const;
451
452 /**
453 * Draws overlays on the specified pixmap, it takes the width and height
454 * of the pixmap into consideration
455 * @param overlays to draw
456 * @param pixmap to draw on
457 * @since 4.7
458 */
459 void drawOverlays(const QStringList &overlays, QPixmap &pixmap, KIconLoader::Group group, int state = KIconLoader::DefaultState) const;
460
461 public Q_SLOTS:
462 /**
463 * Re-initialize the global icon loader
464 */
465 void newIconLoader();
466
467Q_SIGNALS:
468 /**
469 * Emitted by newIconLoader once the new settings have been loaded
470 */
471 void iconLoaderSettingsChanged();
472
473 private:
474 // @internal the data object
475 KIconLoaderPrivate *d;
476};
477
478/**
479 * \relates KIconLoader
480 * Load a desktop icon.
481 */
482KDEUI_EXPORT QPixmap DesktopIcon(const QString& name, int size=0,
483 int state=KIconLoader::DefaultState, const QStringList& overlays = QStringList());
484
485/**
486 * \relates KIconLoader
487 * Load a desktop icon, and apply the necessary effects to get an IconSet.
488 * @deprecated use KIcon(name) or KIcon(name,componentData.iconLoader()) instead
489 */
490#ifndef KDE_NO_DEPRECATED
491KDEUI_EXPORT_DEPRECATED QIcon DesktopIconSet(const QString& name, int size=0);
492#endif
493
494/**
495 * \relates KIconLoader
496 * Load a toolbar icon.
497 */
498KDEUI_EXPORT QPixmap BarIcon(const QString& name, int size=0, int state=KIconLoader::DefaultState,
499 const QStringList& overlays = QStringList());
500
501/**
502 * \relates KIconLoader
503 * Load a toolbar icon, and apply the necessary effects to get an IconSet.
504 * @deprecated use KIcon(name) or KIcon(name,componentData.iconLoader()) instead
505 */
506#ifndef KDE_NO_DEPRECATED
507KDEUI_EXPORT_DEPRECATED QIcon BarIconSet(const QString& name, int size=0);
508#endif
509
510/**
511 * \relates KIconLoader
512 * Load a small icon.
513 */
514KDEUI_EXPORT QPixmap SmallIcon(const QString& name, int size=0,
515 int state=KIconLoader::DefaultState, const QStringList &overlays = QStringList());
516
517/**
518 * \relates KIconLoader
519 * Load a small icon, and apply the necessary effects to get an IconSet.
520 * @deprecated use KIcon(name) or KIcon(name,componentData.iconLoader()) instead
521 */
522#ifndef KDE_NO_DEPRECATED
523KDEUI_EXPORT_DEPRECATED QIcon SmallIconSet(const QString& name, int size=0);
524#endif
525
526/**
527 * \relates KIconLoader
528 * Load a main toolbar icon.
529 */
530KDEUI_EXPORT QPixmap MainBarIcon(const QString& name, int size=0,
531 int state=KIconLoader::DefaultState, const QStringList &overlays = QStringList());
532
533/**
534 * \relates KIconLoader
535 * Load a main toolbar icon, and apply the effects to get an IconSet.
536 * @deprecated use KIcon(name) or KIcon(name,componentData.iconLoader()) instead
537 */
538#ifndef KDE_NO_DEPRECATED
539KDEUI_EXPORT_DEPRECATED QIcon MainBarIconSet(const QString& name, int size=0);
540#endif
541
542/**
543 * \relates KIconLoader
544 * Load a user icon. User icons are searched in $appdir/pics.
545 */
546KDEUI_EXPORT QPixmap UserIcon(const QString& name, int state=KIconLoader::DefaultState, const QStringList &overlays = QStringList());
547
548/**
549 * \relates KIconLoader
550 * Load a user icon, and apply the effects to get an IconSet.
551 * @deprecated use KIcon(name) or KIcon(name,componentData.iconLoader()) instead
552 */
553#ifndef KDE_NO_DEPRECATED
554KDEUI_EXPORT_DEPRECATED QIcon UserIconSet(const QString& name);
555#endif
556
557/**
558 * \relates KIconLoader
559 * Returns the current icon size for a specific group.
560 */
561KDEUI_EXPORT int IconSize(KIconLoader::Group group);
562
563inline KIconLoader::Group& operator++(KIconLoader::Group& group) { group = static_cast<KIconLoader::Group>(group+1); return group; }
564inline KIconLoader::Group operator++(KIconLoader::Group& group,int) { KIconLoader::Group ret = group; ++group; return ret; }
565
566#endif // KICONLOADER_H
567