KGuiAddons

kimagecache.h
1/* This file is part of the KDE project.
2 SPDX-FileCopyrightText: 2010 Michael Pyne <mpyne@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6
7#ifndef KIMAGECACHE_H
8#define KIMAGECACHE_H
9
10// check that KGUIADDONS_LIB is defined in case the application is not using CMake
11// (if KGUIADDONS_LIB is not defined, we cannot assume that KCOREADDONS_LIB not being
12// defined means that we are not linked against KCoreAddons)
13#if defined(KGUIADDONS_LIB) && !defined(KCOREADDONS_LIB)
14#ifdef __GNUC__
15#warning "KImageCache requires KF6CoreAddons (for kshareddatacache.h)"
16#else
17#pragma message("KImageCache requires KF6CoreAddons (for kshareddatacache.h)")
18#endif
19#endif
20
21#include <klocalimagecacheimpl.h>
22#include <kshareddatacache.h>
23
24#include <QImage>
25#include <QPixmap>
26
27#define KImageCache KSharedPixmapCacheMixin<KSharedDataCache>
28
29/**
30 * @brief A simple wrapping layer over KSharedDataCache to support caching
31 * images and pixmaps.
32 *
33 * This class can be used to share images between different processes, which
34 * is useful when it is known that such images will be used across many
35 * processes, or when creating the image is expensive.
36 *
37 * In addition, the class also supports caching QPixmaps <em>in a single
38 * process</em> using the setPixmapCaching() function.
39 *
40 * Tips for use: If you already have QPixmaps that you intend to use, and
41 * you do not need access to the actual image data, then try to store and
42 * retrieve QPixmaps for use.
43 *
44 * On the other hand, if you will need to store and retrieve actual image
45 * data (to modify the image after retrieval for instance) then you should
46 * use QImage to save the conversion cost from QPixmap to QImage.
47 *
48 * KSharedPixmapCacheMixin is a subclass of KSharedDataCache, so all of the methods that
49 * can be used with KSharedDataCache can be used with KSharedPixmapCacheMixin,
50 * <em>with the exception of KSharedDataCache::insert() and
51 * KSharedDataCache::find()</em>.
52 *
53 * @author Michael Pyne <mpyne@kde.org>
54 * @since 4.5
55 */
56template<class T>
58{
59public:
60 /**
61 * Constructs an image cache, named by @p cacheName, with a default
62 * size of @p defaultCacheSize.
63 *
64 * @param cacheName Name of the cache to use.
65 * @param defaultCacheSize The default size, in bytes, of the cache.
66 * The actual on-disk size will be slightly larger. If the cache already
67 * exists, it will not be resized. If it is required to resize the
68 * cache then use the deleteCache() function to remove that cache first.
69 * @param expectedItemSize The expected general size of the items to be
70 * added to the image cache, in bytes. Use 0 if you just want a default
71 * item size.
72 */
73 KSharedPixmapCacheMixin(const QString &cacheName, unsigned defaultCacheSize, unsigned expectedItemSize = 0)
74 : T(cacheName, defaultCacheSize, expectedItemSize)
75 , KLocalImageCacheImplementation(defaultCacheSize)
76 {
77 }
78
79 /**
80 * Inserts the pixmap given by @p pixmap to the cache, accessible with
81 * @p key. The pixmap must be converted to a QImage in order to be stored
82 * into shared memory. In order to prevent unnecessary conversions from
83 * taking place @p pixmap will also be cached (but not in shared
84 * memory) and would be accessible using findPixmap() if pixmap caching is
85 * enabled.
86 *
87 * @param key Name to access @p pixmap with.
88 * @param pixmap The pixmap to add to the cache.
89 * @return true if the pixmap was successfully cached, false otherwise.
90 * @see setPixmapCaching()
91 */
92 bool insertPixmap(const QString &key, const QPixmap &pixmap)
93 {
94 insertLocalPixmap(key, pixmap);
95
96 // One thing to think about is only inserting things to the shared cache
97 // that are frequently used. But that would require tracking the use count
98 // in our local cache too, which I think is probably too much work.
99
100 return insertImage(key, pixmap.toImage());
101 }
102
103 /**
104 * Inserts the @p image into the shared cache, accessible with @p key. This
105 * variant is preferred over insertPixmap() if your source data is already a
106 * QImage, if it is essential that the image be in shared memory (such as
107 * for SVG icons which have a high render time), or if it will need to be
108 * in QImage form after it is retrieved from the cache.
109 *
110 * @param key Name to access @p image with.
111 * @param image The image to add to the shared cache.
112 * @return true if the image was successfully cached, false otherwise.
113 */
114 bool insertImage(const QString &key, const QImage &image)
115 {
116 if (this->insert(key, serializeImage(image))) {
117 updateModifiedTime();
118 return true;
119 }
120
121 return false;
122 }
123
124 /**
125 * Copies the cached pixmap identified by @p key to @p destination. If no such
126 * pixmap exists @p destination is unchanged.
127 *
128 * @return true if the pixmap identified by @p key existed, false otherwise.
129 * @see setPixmapCaching()
130 */
131 bool findPixmap(const QString &key, QPixmap *destination) const
132 {
133 if (findLocalPixmap(key, destination)) {
134 return true;
135 }
136
137 QByteArray cachedData;
138 if (!this->find(key, &cachedData) || cachedData.isNull()) {
139 return false;
140 }
141
142 if (destination) {
143 destination->loadFromData(cachedData, "PNG");
144
145 // Manually re-insert to pixmap cache if we'll be using this one.
146 insertLocalPixmap(key, *destination);
147 }
148
149 return true;
150 }
151
152 /**
153 * Copies the cached image identified by @p key to @p destination. If no such
154 * image exists @p destination is unchanged.
155 *
156 * @return true if the image identified by @p key existed, false otherwise.
157 */
158 bool findImage(const QString &key, QImage *destination) const
159 {
160 QByteArray cachedData;
161 if (!this->find(key, &cachedData) || cachedData.isNull()) {
162 return false;
163 }
164
165 if (destination) {
166 destination->loadFromData(cachedData, "PNG");
167 }
168
169 return true;
170 }
171
172 /**
173 * Removes all entries from the cache. In addition any cached pixmaps (as per
174 * setPixmapCaching()) are also removed.
175 */
176 void clear()
177 {
178 clearLocalCache();
179 T::clear();
180 }
181
182 /**
183 * @return The time that an image or pixmap was last inserted into a cache.
184 */
185 using KLocalImageCacheImplementation::lastModifiedTime;
186
187 /**
188 * @return if QPixmaps added with insertPixmap() will be stored in a local
189 * pixmap cache as well as the shared image cache. The default is to cache
190 * pixmaps locally.
191 */
192 using KLocalImageCacheImplementation::pixmapCaching;
193
194 /**
195 * Enables or disables local pixmap caching. If it is anticipated that a pixmap
196 * will be frequently needed then this can actually save memory overall since the
197 * X server or graphics card will not have to store duplicate copies of the same
198 * image.
199 *
200 * @param enable Enables pixmap caching if true, disables otherwise.
201 */
202 using KLocalImageCacheImplementation::setPixmapCaching;
203
204 /**
205 * @return The highest memory size in bytes to be used by cached pixmaps.
206 * @since 4.6
207 */
208 using KLocalImageCacheImplementation::pixmapCacheLimit;
209
210 /**
211 * Sets the highest memory size the pixmap cache should use.
212 *
213 * @param size The size in bytes
214 * @since 4.6
215 */
216 using KLocalImageCacheImplementation::setPixmapCacheLimit;
217};
218
219#endif /* KIMAGECACHE_H */
You are not supposed to use this class directly, use KImageCache instead.
A simple wrapping layer over KSharedDataCache to support caching images and pixmaps.
Definition kimagecache.h:58
void clear()
Removes all entries from the cache.
bool findPixmap(const QString &key, QPixmap *destination) const
Copies the cached pixmap identified by key to destination.
KSharedPixmapCacheMixin(const QString &cacheName, unsigned defaultCacheSize, unsigned expectedItemSize=0)
Constructs an image cache, named by cacheName, with a default size of defaultCacheSize.
Definition kimagecache.h:73
bool findImage(const QString &key, QImage *destination) const
Copies the cached image identified by key to destination.
bool insertPixmap(const QString &key, const QPixmap &pixmap)
Inserts the pixmap given by pixmap to the cache, accessible with key.
Definition kimagecache.h:92
bool insertImage(const QString &key, const QImage &image)
Inserts the image into the shared cache, accessible with key.
bool isNull() const const
bool loadFromData(QByteArrayView data, const char *format)
bool loadFromData(const QByteArray &data, const char *format, Qt::ImageConversionFlags flags)
QImage toImage() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:52:09 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.