• Skip to content
  • Skip to link menu
KDE 4.1 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KDEUI

KPixmapCache Class Reference

#include <kpixmapcache.h>

Inheritance diagram for KPixmapCache:

Inheritance graph
[legend]

List of all members.


Detailed Description

General-purpose pixmap cache for KDE.

The pixmap cache can be used to store pixmaps which can later be loaded from the cache very quickly.

Its most common use is storing SVG images which might be expensive to render every time they are used. With the cache you can render each SVG only once and later use the stored version unless the SVG file or requested pixmap size changes.

KPixmapCache's API is similar to that of the QPixmapCache so if you're already using the latter then all you need to do is creating a KPixmapCache object (unlike QPixmapCache, KPixmapCache doesn't have many static methods) and calling insert() and find() method on that object:

  // Create KPixmapCache object
  KPixmapCache* cache = new KPixmapCache("myapp-pixmaps");
  // Load a pixmap
  QPixmap pix;
  if (!cache->find("pixmap-1", pix)) {
      // Pixmap isn't in the cache, create it and insert to cache
      pix = createPixmapFromData();
      cache->insert("pixmap-1", pix);
  }
  // Use pix

The above example illustrates that you can also cache pixmaps created from some data. In case such data is updated, you might need to discard cache contents using discard() method:

 // Discard the cache if it's too old
 if (cache->timestamp() < mydataTimestamp()) {
     cache->discard();
 }
 // Now the cache contains up-to-date data
As demonstrated, you can use cache's timestamp() method to see when the cache was created. If necessary, you can also change the timestamp using setTimestamp() method.

Definition at line 76 of file kpixmapcache.h.


Public Types

enum  RemoveStrategy { RemoveOldest, RemoveSeldomUsed, RemoveLeastRecentlyUsed }

Public Member Functions

int cacheLimit () const
void discard ()
virtual bool find (const QString &key, QPixmap &pix)
virtual void insert (const QString &key, const QPixmap &pix)
bool isEnabled () const
bool isValid () const
 KPixmapCache (const QString &name)
QPixmap loadFromFile (const QString &filename)
QPixmap loadFromSvg (const QString &filename, const QSize &size=QSize())
void removeEntries (int newsize=0)
RemoveStrategy removeEntryStrategy () const
void setCacheLimit (int kbytes)
void setRemoveEntryStrategy (RemoveStrategy strategy)
void setTimestamp (unsigned int time)
void setUseQPixmapCache (bool use)
int size () const
unsigned int timestamp () const
bool useQPixmapCache () const
virtual ~KPixmapCache ()

Static Public Member Functions

static void deleteCache (const QString &name)

Protected Member Functions

void ensureInited () const
virtual bool loadCustomData (QDataStream &stream)
virtual bool loadCustomIndexHeader (QDataStream &stream)
bool recreateCacheFiles ()
void setValid (bool valid)
virtual bool writeCustomData (QDataStream &stream)
virtual void writeCustomIndexHeader (QDataStream &stream)

Member Enumeration Documentation

enum KPixmapCache::RemoveStrategy

Describes which entries will be removed first during cache cleanup.

  • RemoveOldest oldest entries are removed first.
  • RemoveSeldomUsed least used entries are removed first.
  • RemoveLeastRecentlyUsed least recently used entries are removed first.
Enumerator:
RemoveOldest 
RemoveSeldomUsed 
RemoveLeastRecentlyUsed 

Definition at line 160 of file kpixmapcache.h.


Constructor & Destructor Documentation

KPixmapCache::KPixmapCache ( const QString &  name  )  [explicit]

Constucts the pixmap cache object.

Parameters:
name unique name of the cache

Definition at line 1007 of file kpixmapcache.cpp.

KPixmapCache::~KPixmapCache (  )  [virtual]

Definition at line 1020 of file kpixmapcache.cpp.


Member Function Documentation

int KPixmapCache::cacheLimit (  )  const

Returns:
maximum size of the cache (in kilobytes).

Default setting is 3 megabytes.

Definition at line 1152 of file kpixmapcache.cpp.

void KPixmapCache::deleteCache ( const QString &  name  )  [static]

Deletes a pixmap cache.

Parameters:
name unique name of the cache to be deleted

Definition at line 1239 of file kpixmapcache.cpp.

void KPixmapCache::discard (  ) 

Deletes all entries and reinitializes this cache.

Definition at line 1248 of file kpixmapcache.cpp.

void KPixmapCache::ensureInited (  )  const [protected]

Makes sure that the cache is initialized correctly.

Definition at line 1060 of file kpixmapcache.cpp.

bool KPixmapCache::find ( const QString &  key,
QPixmap &  pix 
) [virtual]

Tries to load pixmap with the specified key from cache.

Returns:
true when pixmap was found and loaded from cache, false otherwise

Reimplemented in KIconCache.

Definition at line 1277 of file kpixmapcache.cpp.

void KPixmapCache::insert ( const QString &  key,
const QPixmap &  pix 
) [virtual]

Insert specified pixmap into the cache.

If the cache already contains pixmap with the specified key then it is overwritten.

Reimplemented in KIconCache.

Definition at line 1371 of file kpixmapcache.cpp.

bool KPixmapCache::isEnabled (  )  const

Returns:
true when the cache is enabled.

Cache will be disabled when e.g. its data file cannot be created or read.

Definition at line 1076 of file kpixmapcache.cpp.

bool KPixmapCache::isValid (  )  const

Returns:
true when the cache is ready to be used.

False usually means that some additional initing has to be done before the cache can be used.

Definition at line 1082 of file kpixmapcache.cpp.

bool KPixmapCache::loadCustomData ( QDataStream &  stream  )  [protected, virtual]

Can be used by subclasses to write custom data into the the stream.

Reimplemented in KIconCache.

Definition at line 1366 of file kpixmapcache.cpp.

bool KPixmapCache::loadCustomIndexHeader ( QDataStream &  stream  )  [protected, virtual]

Can be used by subclasses to write custom data into cache's header.

Reimplemented in KIconCache.

Definition at line 1067 of file kpixmapcache.cpp.

QPixmap KPixmapCache::loadFromFile ( const QString &  filename  ) 

Loads pixmap from given file, using the cache.

If file's modified-time is more recent than cache's timestamp() , then the cache is discarded.

Definition at line 1454 of file kpixmapcache.cpp.

QPixmap KPixmapCache::loadFromSvg ( const QString &  filename,
const QSize &  size = QSize() 
)

Same as above, but uses SVG file instead.

Parameters:
size size of the pixmap where the SVG is render to. If not given then SVG's default size is used.

Definition at line 1479 of file kpixmapcache.cpp.

bool KPixmapCache::recreateCacheFiles (  )  [protected]

Recreates the cache files.

Definition at line 1173 of file kpixmapcache.cpp.

void KPixmapCache::removeEntries ( int  newsize = 0  ) 

Removes some of the entries in the cache according to current removeEntryStrategy().

Parameters:
newsize wanted size of the cache, in bytes. If 0 is given then current cacheLimit() is used.
Warning: this works by copying some entries to a new cache and then replacing the old cache with the new one. Thus it might be slow and will temporarily use extra disk space.

Definition at line 1268 of file kpixmapcache.cpp.

KPixmapCache::RemoveStrategy KPixmapCache::removeEntryStrategy (  )  const

Returns:
current entry removal strategy.

Default is RemoveLeastRecentlyUsed.

Definition at line 1163 of file kpixmapcache.cpp.

void KPixmapCache::setCacheLimit ( int  kbytes  ) 

Sets the maximum size of the cache (in kilobytes).

If cache gets bigger the limit then some entries are removed (according to removeEntryStrategy() ). Setting cache limit to 0 disables automatic cache size limiting.

Note that the cleanup might not be done immediately, so the cache might temporarily (for a few seconds) grow bigger than the limit.

Definition at line 1157 of file kpixmapcache.cpp.

void KPixmapCache::setRemoveEntryStrategy ( KPixmapCache::RemoveStrategy  strategy  ) 

Sets the removeEntryStrategy used when removing entries.

Definition at line 1168 of file kpixmapcache.cpp.

void KPixmapCache::setTimestamp ( unsigned int  time  ) 

Sets the timestamp of app-specific cache.

It's saved in the cache file and can later be retrieved using timestamp() method. By default the timestamp is set to the cache creation time.

Definition at line 1100 of file kpixmapcache.cpp.

void KPixmapCache::setUseQPixmapCache ( bool  use  ) 

Sets whether QPixmapCache (memory caching) should be used in addition to disk cache.

QPixmapCache is used by default.

Definition at line 1142 of file kpixmapcache.cpp.

void KPixmapCache::setValid ( bool  valid  )  [protected]

Can be used by subclasses to indicate that cache needs some additional initing before it can be used.

Definition at line 1088 of file kpixmapcache.cpp.

int KPixmapCache::size (  )  const

Returns:
approximate size of the cache, in kilobytes.

Definition at line 1131 of file kpixmapcache.cpp.

unsigned int KPixmapCache::timestamp (  )  const

Returns:
timestamp of the cache, set using the setTimestamp method.

It can be used by the application to check whether app-specific cache has outdated.

Definition at line 1094 of file kpixmapcache.cpp.

bool KPixmapCache::useQPixmapCache (  )  const

Whether QPixmapCache should be used to cache pixmaps in memory in addition to caching them on the disk.

Definition at line 1147 of file kpixmapcache.cpp.

bool KPixmapCache::writeCustomData ( QDataStream &  stream  )  [protected, virtual]

Can be used by subclasses to load custom data from the the stream.

Reimplemented in KIconCache.

Definition at line 1436 of file kpixmapcache.cpp.

void KPixmapCache::writeCustomIndexHeader ( QDataStream &  stream  )  [protected, virtual]

Can be used by subclasses to load custom data from cache's header.

Reimplemented in KIconCache.

Definition at line 1072 of file kpixmapcache.cpp.


The documentation for this class was generated from the following files:
  • kpixmapcache.h
  • kpixmapcache.cpp

KDEUI

Skip menu "KDEUI"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • KIO
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • Kross
  • KUtils
  • Nepomuk
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.5.4
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal