KDE 4.2 PyKDE API Reference

- KDE's Python API

# KPixmapCache Class Reference

`from PyKDE4.kdeui import *`

Subclasses: KIconCache

## 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.

## Enumerations

RemoveStrategy | { RemoveOldest, RemoveSeldomUsed, RemoveLeastRecentlyUsed }

## Methods

| __init__ (self, QString name)
| __init__ (self, KPixmapCache other)
int | cacheLimit (self)
| discard (self)
| ensureInited (self)
bool | find (self, QString key, QPixmap pix)
| insert (self, QString key, QPixmap pix)
bool | isEnabled (self)
bool | isValid (self)
bool | loadCustomData (self, QDataStream stream)
bool | loadCustomIndexHeader (self, QDataStream stream)
QPixmap | loadFromFile (self, QString filename)
QPixmap | loadFromSvg (self, QString filename, QSize size=QSize())
bool | recreateCacheFiles (self)
| removeEntries (self, int newsize=0)
KPixmapCache.RemoveStrategy | removeEntryStrategy (self)
| setCacheLimit (self, int kbytes)
| setRemoveEntryStrategy (self, KPixmapCache.RemoveStrategy strategy)
| setTimestamp (self, long time)
| setUseQPixmapCache (self, bool use)
| setValid (self, bool valid)
int | size (self)
long | timestamp (self)
bool | useQPixmapCache (self)
bool | writeCustomData (self, QDataStream stream)
| writeCustomIndexHeader (self, QDataStream stream)

## Static Methods

| deleteCache (QString name)

## Method Documentation

__init__ | ( | self, |
|  | QString | name
| ) |  |  |

Constucts the pixmap cache object.

Parameters:

  | name | unique name of the cache

__init__ | ( | self, |
|  | KPixmapCache | other
| ) |  |  |

int cacheLimit | ( |  | self ) |

Returns:
  maximum size of the cache (in kilobytes). Default setting is 3 megabytes.

deleteCache | ( | QString | name
| ) |  |  |

Deletes a pixmap cache.

Parameters:

  | name | unique name of the cache to be deleted

discard | ( |  | self ) |

Deletes all entries and reinitializes this cache.

ensureInited | ( |  | self ) |

Makes sure that the cache is initialized correctly.

bool find | ( | self, |
|  | QString | key,
|  | QPixmap | pix
| ) |  |  |

Tries to load pixmap with the specified key from cache.

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

insert | ( | self, |
|  | QString | key,
|  | QPixmap | pix
| ) |  |  |

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

bool isEnabled | ( |  | self ) |

Returns:
  true when the cache is enabled. Cache will be disabled when e.g. its data file cannot be created or read.

bool isValid | ( |  | self ) |

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.

bool loadCustomData | ( | self, |
|  | QDataStream | stream
| ) |  |  |

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

bool loadCustomIndexHeader | ( | self, |
|  | QDataStream | stream
| ) |  |  |

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

QPixmap loadFromFile | ( | self, |
|  | 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.

QPixmap loadFromSvg | ( | self, |
|  | QString | filename,
|  | 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.

bool recreateCacheFiles | ( |  | self ) |

Recreates the cache files.

removeEntries | ( | self, |
|  | 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.

KPixmapCache.RemoveStrategy removeEntryStrategy | ( |  | self ) |

Returns:
  current entry removal strategy. Default is RemoveLeastRecentlyUsed.

setCacheLimit | ( | self, |
|  | 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.

setRemoveEntryStrategy | ( | self, |
|  | KPixmapCache.RemoveStrategy | strategy
| ) |  |  |

Sets the removeEntryStrategy used when removing entries.

setTimestamp | ( | self, |
|  | long | 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.

setUseQPixmapCache | ( | self, |
|  | bool | use
| ) |  |  |

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

setValid | ( | self, |
|  | bool | valid
| ) |  |  |

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

int size | ( |  | self ) |

Returns:
  approximate size of the cache, in kilobytes.

long timestamp | ( |  | self ) |

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.

bool useQPixmapCache | ( |  | self ) |

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

bool writeCustomData | ( | self, |
|  | QDataStream | stream
| ) |  |  |

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

writeCustomIndexHeader | ( | self, |
|  | QDataStream | stream
| ) |  |  |

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

## Enumeration Documentation

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 |