Etk
Main Page Object Hierarchy Data Structures Related Pages
Etk

Cache system of Etk


Detailed Description

The cache system is used by widgets that frequently need to load images, such as Etk_Tree or Etk_Iconbox.

You will almost never have to use Etk_Cache directly, except if you are implementing a new widget that needs to load a lot of images efficiently, or if you are creating a new tree-model that displays images.

The cache system is a simple pool where you can store a limited number of Evas objects associated to a filename and to a key. If you try to add a new object with etk_cache_add() while the cache is already full, the oldest object of the cache will be destroyed. You can then retrieve a cached object from its filename/key with etk_cache_find().
You can also dynamically change the maximum size of the cache system with etk_cache_size_set() and know the current number of cached objects with etk_cache_num_objects_get().


Data Structures

struct  Etk_Cache
 A system used to cache image objects for widgets that frequently need to load images. More...

Functions

Etk_Cache * etk_cache_new (int size)
 Creates a new cache system that you can use to cache image objects or Edje objects. You usually don't need to use that, except if you are implementing your own widget or your own tree model which may need to load a lot of images efficiently.
void etk_cache_destroy (Etk_Cache *cache)
 Destroys the cache system: it destroys all the cached objects, and frees the memory used by the cache system.
void etk_cache_clear (Etk_Cache *cache)
 Clears the cache system: it destroys all the cached objects. The cache system remains still usable.
void etk_cache_free_callback_set (Etk_Cache *cache, void(*free_cb)(Evas_Object *object, void *data), void *data)
 Sets the callback to call when a cached object is deleted (if it is there is no more space in the cache, or if the cache is being cleared).
void etk_cache_size_set (Etk_Cache *cache, int size)
 Sets the max number of objects that the cache system can contain. If the new size is smaller than current number of objects in the cache, the oldest objects that can't fit in the new cache size will be destroyed.
int etk_cache_size_get (Etk_Cache *cache)
 Gets the max number of objects that can be stored by the cache system.
int etk_cache_num_objects_get (Etk_Cache *cache)
 Gets the current number of objects stored in the cache system.
void etk_cache_add (Etk_Cache *cache, Evas_Object *object, const char *filename, const char *key)
 Adds an Evas image object or an Edje object in the cache system. If the cache is already full, the oldest object will be removed. The object to cache will also be automatically hidden.
void etk_cache_remove (Etk_Cache *cache, Evas_Object *object)
 Removes an object from the cache. The object won't be destroyed.
Evas_Object * etk_cache_find (Etk_Cache *cache, const char *filename, const char *key)
 Finds an object in the cache according to its filename and its key. If the object is present in the cache, it will be removed from the cache and returned. Otherwise NULL is returned.


Function Documentation

Etk_Cache * etk_cache_new ( int  size  ) 

Creates a new cache system that you can use to cache image objects or Edje objects. You usually don't need to use that, except if you are implementing your own widget or your own tree model which may need to load a lot of images efficiently.

Parameters:
size the max number of objects the cache system could store
Returns:
Returns the new cache system
Note:
You will need to destroy it with etk_cache_destroy() when you no longer need it

void etk_cache_destroy ( Etk_Cache *  cache  ) 

Destroys the cache system: it destroys all the cached objects, and frees the memory used by the cache system.

Parameters:
cache the cache system to destroy

void etk_cache_clear ( Etk_Cache *  cache  ) 

Clears the cache system: it destroys all the cached objects. The cache system remains still usable.

Parameters:
cache the cache system to clear

void etk_cache_free_callback_set ( Etk_Cache *  cache,
void(*)(Evas_Object *object, void *data)  free_cb,
void *  data 
)

Sets the callback to call when a cached object is deleted (if it is there is no more space in the cache, or if the cache is being cleared).

Parameters:
cache a cache system
free_cb the function to call when a cached object is deleted. object is the object that will be deleted, and data is the user data you gave (see the next param)
data a data pointer that will be passed to the callback when it is called

void etk_cache_size_set ( Etk_Cache *  cache,
int  size 
)

Sets the max number of objects that the cache system can contain. If the new size is smaller than current number of objects in the cache, the oldest objects that can't fit in the new cache size will be destroyed.

Parameters:
cache the cache system to resize
size the new size (max number of objects) of the cache system

int etk_cache_size_get ( Etk_Cache *  cache  ) 

Gets the max number of objects that can be stored by the cache system.

Parameters:
cache a cache system
Returns:
Returns the max number of objects that can be stored by the cache system

int etk_cache_num_objects_get ( Etk_Cache *  cache  ) 

Gets the current number of objects stored in the cache system.

Parameters:
cache a cache system
Returns:
Returns the current number of objects stored by the cache system

void etk_cache_add ( Etk_Cache *  cache,
Evas_Object *  object,
const char *  filename,
const char *  key 
)

Adds an Evas image object or an Edje object in the cache system. If the cache is already full, the oldest object will be removed. The object to cache will also be automatically hidden.

Parameters:
cache a cache system
object the Evas image object or the Edje object to cache
filename the filename associated to the object
key the key associated to the object (the group for an Edje object, the key for an image from an Eet file, or NULL otherwise)
Note:
Once the object is added to the cache, you should keep no reference to it. It may for example be deleted if there is no more space in the cache system

void etk_cache_remove ( Etk_Cache *  cache,
Evas_Object *  object 
)

Removes an object from the cache. The object won't be destroyed.

Parameters:
cache a cache system
object the object to remove from the cache system

Evas_Object * etk_cache_find ( Etk_Cache *  cache,
const char *  filename,
const char *  key 
)

Finds an object in the cache according to its filename and its key. If the object is present in the cache, it will be removed from the cache and returned. Otherwise NULL is returned.

Parameters:
cache the cache system where to find the object
filename the filename of the object to find
key the key associated to the object to find (the group for an Edje object, the key for an image from an Eet file, or NULL otherwise)
Returns:
Returns an object corresponding to the given filename and key, or NULL if no such object is cached