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 | |
32 | class QIcon; |
33 | class QMovie; |
34 | class QPixmap; |
35 | |
36 | class KComponentData; |
37 | class KIconLoaderPrivate; |
38 | class KStandardDirs; |
39 | class KIconEffect; |
40 | class 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 | */ |
77 | class 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 | |
87 | public: |
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 (); |
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 () 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 | |
467 | Q_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 | */ |
482 | KDEUI_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 |
491 | KDEUI_EXPORT_DEPRECATED QIcon DesktopIconSet(const QString& name, int size=0); |
492 | #endif |
493 | |
494 | /** |
495 | * \relates KIconLoader |
496 | * Load a toolbar icon. |
497 | */ |
498 | KDEUI_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 |
507 | KDEUI_EXPORT_DEPRECATED QIcon BarIconSet(const QString& name, int size=0); |
508 | #endif |
509 | |
510 | /** |
511 | * \relates KIconLoader |
512 | * Load a small icon. |
513 | */ |
514 | KDEUI_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 |
523 | KDEUI_EXPORT_DEPRECATED QIcon SmallIconSet(const QString& name, int size=0); |
524 | #endif |
525 | |
526 | /** |
527 | * \relates KIconLoader |
528 | * Load a main toolbar icon. |
529 | */ |
530 | KDEUI_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 |
539 | KDEUI_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 | */ |
546 | KDEUI_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 |
554 | KDEUI_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 | */ |
561 | KDEUI_EXPORT int IconSize(KIconLoader::Group group); |
562 | |
563 | inline KIconLoader::Group& operator++(KIconLoader::Group& group) { group = static_cast<KIconLoader::Group>(group+1); return group; } |
564 | inline KIconLoader::Group operator++(KIconLoader::Group& group,int) { KIconLoader::Group ret = group; ++group; return ret; } |
565 | |
566 | #endif // KICONLOADER_H |
567 | |