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
28class QImage;
29class 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 */
58class 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