1 | /* |
2 | * This file is part of the KDE project. |
3 | * Copyright © 2010 Michael Pyne <mpyne@kde.org> |
4 | * |
5 | * This library is free software; you can redistribute it and/or |
6 | * modify it under the terms of the GNU Library General Public |
7 | * License version 2 as published by the Free Software Foundation. |
8 | * |
9 | * This library is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | * Library General Public License for more details. |
13 | * |
14 | * You should have received a copy of the GNU Library General Public License |
15 | * along with this library; see the file COPYING.LIB. If not, write to |
16 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | * Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KIMAGECACHE_H |
21 | #define KIMAGECACHE_H |
22 | |
23 | #include <kdeui_export.h> |
24 | #include <kshareddatacache.h> |
25 | |
26 | #include <time.h> |
27 | |
28 | class QImage; |
29 | class QPixmap; |
30 | |
31 | /** |
32 | * @brief A simple wrapping layer over KSharedDataCache to support caching |
33 | * images and pixmaps. |
34 | * |
35 | * This class can be used to share images between different processes, which |
36 | * is useful when it is known that such images will be used across many |
37 | * processes, or when creating the image is expensive. |
38 | * |
39 | * In addition, the class also supports caching QPixmaps <em>in a single |
40 | * process</em> using the setPixmapCaching() function. |
41 | * |
42 | * Tips for use: If you already have QPixmaps that you intend to use, and |
43 | * you do not need access to the actual image data, then try to store and |
44 | * retrieve QPixmaps for use. |
45 | * |
46 | * On the other hand, if you will need to store and retrieve actual image |
47 | * data (to modify the image after retrieval for instance) then you should |
48 | * use QImage to save the conversion cost from QPixmap to QImage. |
49 | * |
50 | * KImageCache is a subclass of KSharedDataCache, so all of the methods that |
51 | * can be used with KSharedDataCache can be used with KImageCache, |
52 | * <em>with the exception of KSharedDataCache::insert() and |
53 | * KSharedDataCache::find()</em>. |
54 | * |
55 | * @author Michael Pyne <mpyne@kde.org> |
56 | * @since 4.5 |
57 | */ |
58 | class KDEUI_EXPORT KImageCache : public KSharedDataCache |
59 | { |
60 | public: |
61 | /** |
62 | * Constructs an image cache, named by @p cacheName, with a default |
63 | * size of @p defaultCacheSize. |
64 | * |
65 | * @param cacheName Name of the cache to use. |
66 | * @param defaultCacheSize The default size, in bytes, of the cache. |
67 | * The actual on-disk size will be slightly larger. If the cache already |
68 | * exists, it will not be resized. If it is required to resize the |
69 | * cache then use the deleteCache() function to remove that cache first. |
70 | * @param expectedItemSize The expected general size of the items to be |
71 | * added to the image cache, in bytes. Use 0 if you just want a default |
72 | * item size. |
73 | */ |
74 | KImageCache(const QString &cacheName, |
75 | unsigned defaultCacheSize, |
76 | unsigned expectedItemSize = 0); |
77 | |
78 | /** |
79 | * Deconstructor |
80 | */ |
81 | ~KImageCache(); |
82 | |
83 | /** |
84 | * Inserts the pixmap given by @p pixmap to the cache, accessible with |
85 | * @p key. The pixmap must be converted to a QImage in order to be stored |
86 | * into shared memory. In order to prevent unnecessary conversions from |
87 | * taking place @p pixmap will also be cached (but not in stored |
88 | * memory) and would be accessible using findPixmap() if pixmap caching is |
89 | * enabled. |
90 | * |
91 | * @param key Name to access @p pixmap with. |
92 | * @param pixmap The pixmap to add to the cache. |
93 | * @return true if the pixmap was successfully cached, false otherwise. |
94 | * @see setPixmapCaching() |
95 | */ |
96 | bool insertPixmap(const QString &key, const QPixmap &pixmap); |
97 | |
98 | /** |
99 | * Inserts the @p image into the shared cache, accessible with @p key. This |
100 | * variant is preferred over insertPixmap() if your source data is already a |
101 | * QImage, if it is essential that the image be in shared memory (such as |
102 | * for SVG icons which have a high render time), or if it will need to be |
103 | * in QImage form after it is retrieved from the cache. |
104 | * |
105 | * @param key Name to access @p image with. |
106 | * @param image The image to add to the shared cache. |
107 | * @return true if the image was successfully cached, false otherwise. |
108 | */ |
109 | bool insertImage(const QString &key, const QImage &image); |
110 | |
111 | /** |
112 | * Copies the cached pixmap identified by @p key to @p destination. If no such |
113 | * pixmap exists @p destination is unchanged. |
114 | * |
115 | * @return true if the pixmap identified by @p key existed, false otherwise. |
116 | * @see setPixmapCaching() |
117 | */ |
118 | bool findPixmap(const QString &key, QPixmap *destination) const; |
119 | |
120 | /** |
121 | * Copies the cached image identified by @p key to @p destination. If no such |
122 | * image exists @p destination is unchanged. |
123 | * |
124 | * @return true if the image identified by @p key existed, false otherwise. |
125 | */ |
126 | bool findImage(const QString &key, QImage *destination) const; |
127 | |
128 | /** |
129 | * Removes all entries from the cache. In addition any cached pixmaps (as per |
130 | * setPixmapCaching()) are also removed. |
131 | */ |
132 | void clear(); |
133 | |
134 | /** |
135 | * @return The time that an image or pixmap was last inserted into a cache. |
136 | */ |
137 | time_t lastModifiedTime() const; |
138 | |
139 | /** |
140 | * @return if QPixmaps added with insertPixmap() will be stored in a local |
141 | * pixmap cache as well as the shared image cache. The default is to cache |
142 | * pixmaps locally. |
143 | */ |
144 | bool pixmapCaching() const; |
145 | |
146 | /** |
147 | * Enables or disables local pixmap caching. If it is anticipated that a pixmap |
148 | * will be frequently needed then this can actually save memory overall since the |
149 | * X server or graphics card will not have to store duplicate copies of the same |
150 | * image. |
151 | * |
152 | * @param enable Enables pixmap caching if true, disables otherwise. |
153 | */ |
154 | void setPixmapCaching(bool enable); |
155 | |
156 | /** |
157 | * @return The highest memory size in bytes to be used by cached pixmaps. |
158 | * @since 4.6 |
159 | */ |
160 | int pixmapCacheLimit() const; |
161 | |
162 | /** |
163 | * Sets the highest memory size the pixmap cache should use. |
164 | * |
165 | * @param size The size in bytes |
166 | * @since 4.6 |
167 | */ |
168 | void setPixmapCacheLimit(int size); |
169 | |
170 | private: |
171 | class Private; |
172 | Private *const d; ///< @internal |
173 | }; |
174 | |
175 | #endif /* KIMAGECACHE_H */ |
176 | |