Elementary Store
Elementary

Store is an abstracting API that is intended to farm off fetching of data to threads running asynchronously from the mainloop that actually fetch data needed for a genlist (or possibly future other widgets) so scrolling never blocks waiting on IO (though normally this should be the users job - if using genlist, to ensure all data genlist needs is in memory at the time it needs it, and if it isn't to queue and defer a fetch and let genlist know later when its ready. More...

## Data Structures

struct | _Elm_Store_Item_Mapping_Icon
struct | _Elm_Store_Item_Mapping_Empty
struct | _Elm_Store_Item_Mapping_Photo
struct | _Elm_Store_Item_Mapping_Custom
struct | _Elm_Store_Item_Mapping
struct | _Elm_Store_Item_Info
struct | _Elm_Store_Item_Info_Filesystem

## Macros

#define | ELM_STORE_ITEM_MAPPING_END { ELM_STORE_ITEM_MAPPING_NONE, NULL, 0, { .empty = { EINA_TRUE } } }
| Use this to end a list of mappings.
#define | ELM_STORE_ITEM_MAPPING_OFFSET(st, it)
| Use this to get the offset in bytes in memory for where the data for the mapping lives relative to the item data (a private struct pointed to owned by the user.

## Typedefs

typedef struct _Elm_Store | Elm_Store
| A store object.
typedef struct _Elm_Store_Item | Elm_Store_Item
| A handle of a store item passed to store fetch/unfetch functions.
typedef struct _Elm_Store_Item_Info | Elm_Store_Item_Info
| Basic information about a store item - always cast into a specific type like Elm_Store_Item_Info_Filesystem.
typedef struct _Elm_Store_Item_Info_Filesystem | Elm_Store_Item_Info_Filesystem
| Filesystem specific information about a store item.
typedef struct _Elm_Store_Item_Mapping | Elm_Store_Item_Mapping
| A basic way of telling Store how to take your return data (string, or something else from your struct) and convert it into something genlist can use.
typedef struct _Elm_Store_Item_Mapping_Empty | Elm_Store_Item_Mapping_Empty
| An empty piece of mapping information.
typedef struct _Elm_Store_Item_Mapping_Icon | Elm_Store_Item_Mapping_Icon
typedef struct _Elm_Store_Item_Mapping_Photo | Elm_Store_Item_Mapping_Photo
| The data is a photo, so use these parameters to find it.
typedef struct _Elm_Store_Item_Mapping_Custom | Elm_Store_Item_Mapping_Custom
typedef Eina_Bool(* | Elm_Store_Item_List_Cb) (void *data, Elm_Store_Item_Info *info)
| Function to call for listing an item.
typedef void(* | Elm_Store_Item_Fetch_Cb) (void *data, Elm_Store_Item *sti)
| Function to call to fetch item data.
typedef void(* | Elm_Store_Item_Unfetch_Cb) (void *data, Elm_Store_Item *sti)
| Function to cal lto un-fetch (free) an item.
typedef void *(* | Elm_Store_Item_Mapping_Cb) (void *data, Elm_Store_Item *sti, const char *part)
| Custom mapping function to call.

## Enumerations

enum | Elm_Store_Item_Mapping_Type { ELM_STORE_ITEM_MAPPING_NONE = 0 , ELM_STORE_ITEM_MAPPING_LABEL , ELM_STORE_ITEM_MAPPING_STATE , ELM_STORE_ITEM_MAPPING_ICON , ELM_STORE_ITEM_MAPPING_PHOTO , ELM_STORE_ITEM_MAPPING_CUSTOM , ELM_STORE_ITEM_MAPPING_LAST }
| Possible mappings types. More...

## Functions

Elm_Store * | elm_store_filesystem_new (void)
| Create a new store object.
void | elm_store_free (Elm_Store *st)
| Free the store object and all items it manages.
void | elm_store_filesystem_directory_set (Elm_Store *st, const char *dir)
| Set the path to the directory to scan for a filesystem store.
const char * | elm_store_filesystem_directory_get (const Elm_Store *st)
| Get the directory set on a filesystem store.
const char * | elm_store_item_filesystem_path_get (const Elm_Store_Item *sti)
| Get the path of a specific store item.
void | elm_store_target_genlist_set (Elm_Store *st, Evas_Object *obj)
| Set the target genlist to fill in from the store.
void | elm_store_cache_set (Elm_Store *st, int max)
| Set the maximum number of items that are not visible to keep cached.
int | elm_store_cache_get (const Elm_Store *st)
| Get the maximum number if items to cache.
void | elm_store_list_func_set (Elm_Store *st, Elm_Store_Item_List_Cb func, const void *data)
| Set the function used to deal with listing of items.
void | elm_store_fetch_func_set (Elm_Store *st, Elm_Store_Item_Fetch_Cb func, const void *data)
| Set the function used to deal with fetching of items.
void | elm_store_unfetch_func_set (Elm_Store *st, Elm_Store_Item_Unfetch_Cb func, const void *data)
| Set the function used to free the structure allocated for the item.
void | elm_store_fetch_thread_set (Elm_Store *st, Eina_Bool use_thread)
| Enable or disable fetching in a thread for Store.
Eina_Bool | elm_store_fetch_thread_get (const Elm_Store *st)
| Get the thread enabled fetching option for Store.
void | elm_store_sorted_set (Elm_Store *st, Eina_Bool sorted)
| Set if items are to be sorted or not.
Eina_Bool | elm_store_sorted_get (const Elm_Store *st)
| Get the sorting flag.
void | elm_store_item_data_set (Elm_Store_Item *sti, void *data)
| Set the item data holding item fields to map to item values in genlist.
void * | elm_store_item_data_get (Elm_Store_Item *sti)
| Get the item data.
const Elm_Store * | elm_store_item_store_get (const Elm_Store_Item *sti)
| Fetch the store than a store item belongs to.
const Elm_Object_Item * | elm_store_item_genlist_item_get (const Elm_Store_Item *sti)
| Fetch the genlist item that this store item controls.

## Detailed Description

Store is an abstracting API that is intended to farm off fetching of data to threads running asynchronously from the mainloop that actually fetch data needed for a genlist (or possibly future other widgets) so scrolling never blocks waiting on IO (though normally this should be the users job - if using genlist, to ensure all data genlist needs is in memory at the time it needs it, and if it isn't to queue and defer a fetch and let genlist know later when its ready.

Store actually does this and implements the infrastructure of this, leaving the actual fetch and convert up to functions provided by the user).

It is possible for store to run inline without a thread, but this is highly inadvisable. you can disable this with:

elm_store_fetch_thread_set(store, EINA_FALSE);

Store works first by creating a store, setting up functions to list items and fetch items. Currently the only store type supported is the filesystem store, which will list the files inside a directory (not recursively) and then hand each file it finds (the file path) to the list function for evaluation.

The list function may look at filename, may open the file or do anything it likes to determine something about the file. Either it filters it out (returns `EINA_FALSE`) and it is discarded or it returns `EINA_TRUE` and also provides a "sort id" which is a string store uses to figure out sorting. This string could be the filename, or some data based on its contents. The strings are sorted alphabetically like any normal ASCII strings, with case being important. As this listing function runs in a thread, it can do blocking IO and parsing without hurting the fluidity of the main loop and GUI. The list function also returns information on how to map fields in the source file to elements of the genlist item. For example, how the fetcher reads the private data struct of the user (what memory offset in the struct the data is at) and what type is there (it's a label of some sort, an icon, or with a custom mapping function that figures it out itself and creates the content needed for the genlist item).

Store then uses this sort id to build (over time) a sorted list of items that then map 1:1 to genlist items. When these items are visible and need content, Store calls the fetch function per item, which is responsible for fetching the data from the given item and returning data to store so it can map this to some item content. This function also runs in a thread, and thus can do blocking IO work to later return the data. Sorting is optional and can be enabled or disabled too.

When items are no longer needed, store will cal the unfetch function to free data in memory about that item that is no longer needed. This function is called in the mainloop and is expected to take minimal or almost no time to simply free up memory resources.

## Macro Definition Documentation

## ELM_STORE_ITEM_MAPPING_OFFSET

#define ELM_STORE_ITEM_MAPPING_OFFSET | ( |  | st,
|  |  | it )

Value:
offsetof(st, it)

Use this to get the offset in bytes in memory for where the data for the mapping lives relative to the item data (a private struct pointed to owned by the user.

## Typedef Documentation

## Elm_Store_Item_Mapping_Empty

typedef struct _Elm_Store_Item_Mapping_Empty Elm_Store_Item_Mapping_Empty

An empty piece of mapping information.

Useful for String labels as they get used directly

## Elm_Store_Item_List_Cb

typedef Eina_Bool(* Elm_Store_Item_List_Cb) (void *data, Elm_Store_Item_Info *info)

Function to call for listing an item.

> The item needs a custom mapping which means calling a function and returning a string from it, as opposed to a static lookup. It should not be allocated, and should live in a buffer in memory that survives the return of this function if its a label, or an allocated icon object if its an icon needed etc.

## Enumeration Type Documentation

## Elm_Store_Item_Mapping_Type

enum Elm_Store_Item_Mapping_Type

Possible mappings types.

Since
  1.7

Enumerator
ELM_STORE_ITEM_MAPPING_LABEL | const char * -> label
ELM_STORE_ITEM_MAPPING_STATE | Eina_Bool -> state.
ELM_STORE_ITEM_MAPPING_ICON | char * -> icon path
ELM_STORE_ITEM_MAPPING_PHOTO | char * -> photo path
ELM_STORE_ITEM_MAPPING_CUSTOM | item->custom(it->data, it, part) -> void * (-> any)

## Function Documentation

## elm_store_filesystem_new()

Elm_Store * elm_store_filesystem_new | ( | void |  | ) |

Create a new store object.

This creates a new store object to then configure so it works.

Returns
  A new store object, or NULL if creation fails

References EINA_MAGIC_SET, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## elm_store_free()

void elm_store_free | ( | Elm_Store * | st | ) |

Free the store object and all items it manages.

This frees the given `st` store and all the items it manages. It will clear the List that it populated, but otherwise leave it alone. It will cancel background threads (and may have to wait for them to complete a pending operation to do this).

Parameters

  st | The store to free

References ecore_job_del(), ecore_thread_cancel(), EINA_INLIST_GET, eina_inlist_remove(), eina_list_free(), EINA_MAGIC_CHECK, elm_genlist_clear(), ELM_GENLIST_EVENT_REALIZED, ELM_GENLIST_EVENT_UNREALIZED, and EVAS_CALLBACK_DEL.

## elm_store_filesystem_directory_set()

void elm_store_filesystem_directory_set | ( | Elm_Store * | st,
|  | const char * | dir )

Set the path to the directory to scan for a filesystem store.

This sets the directory (`dir`) to scan and begins scanning in the the background in threads (or not if threading is disabled with elm_store_fetch_thread_set()). Note that Listing is always done in a thread but fetching may not be if disabled here. This should be the last thing called after fetch, list and unfetch functions are set, as well as target genlist etc. You also should not change the directory once set. If you need a new directory scanned, create a new store.

Parameters

  st | The store to modify
  dir | A string giving the path to the directory to scan

References ecore_thread_cancel(), ecore_thread_feedback_run(), EINA_MAGIC_CHECK, eina_stringshare_replace(), and EINA_TRUE.

## elm_store_filesystem_directory_get()

const char * elm_store_filesystem_directory_get | ( | const Elm_Store * | st | ) |

Get the directory set on a filesystem store.

This gets the directory set by elm_store_filesystem_directory_set(). This string returned will be valid until elm_store_filesystem_directory_set() changes it or until the store is freed with elm_store_free().

Returns
  A string with the path set, or NULL if none set.

References EINA_MAGIC_CHECK.

## elm_store_item_filesystem_path_get()

const char * elm_store_item_filesystem_path_get | ( | const Elm_Store_Item * | sti | ) |

Get the path of a specific store item.

This returns the full path of a store item. This string is valid only during the list function set by elm_store_list_func_set() or during the fetch function set by elm_store_fetch_func_set() or during the unfetch function set by elm_store_unfetch_func_set().

Parameters

  sti | The store item to get the path from

Returns
  A full path in a string or NULL if none available

References EINA_MAGIC_CHECK.

## elm_store_target_genlist_set()

void elm_store_target_genlist_set | ( | Elm_Store * | st,
|  | Evas_Object * | obj )

Set the target genlist to fill in from the store.

This tells the store the target genlist to use to fill in content from the store. Once a store starts "going" via elm_store_filesystem_directory_set() The target should never be changed again.

Parameters

  st | The store to do the filling.
  obj | The genlist object to fill in and control the content of from the store.

References EINA_MAGIC_CHECK, elm_genlist_clear(), ELM_GENLIST_EVENT_REALIZED, ELM_GENLIST_EVENT_UNREALIZED, EVAS_CALLBACK_DEL, and evas_object_event_callback_add().

## elm_store_cache_set()

void elm_store_cache_set | ( | Elm_Store * | st,
|  | int | max )

Set the maximum number of items that are not visible to keep cached.

Store may keep some items around for caching purposes that cannot be seen, so this controls the maximum number. The default is 128, but may change at any point in time in the future.

Parameters

  st | The store to modify
  max | The number of items to keep (should be greater than or equal to 0)

References EINA_MAGIC_CHECK.

## elm_store_cache_get()

int elm_store_cache_get | ( | const Elm_Store * | st | ) |

Get the maximum number if items to cache.

This returns the number of items at most to cache.

Parameters

  st | The store to query

Returns
  The maximum number of items to cache (>= 0)

See also
  elm_store_cache_set()

References EINA_MAGIC_CHECK.

## elm_store_list_func_set()

void elm_store_list_func_set | ( | Elm_Store * | st,
|  | Elm_Store_Item_List_Cb | func,
|  | const void * | data )

Set the function used to deal with listing of items.

This function is called per item that is found so it can examine the item and discard it (return `EINA_FALSE` to discard, or `EINA_TRUE` to accept), and work out some sorting ID (that may be filename or anything else based on content). This function is always called from a thread.

Parameters

  st | The store to set the function of
  func | The function to be called
  data | the data pointer to be passed to the `func` function when called

References EINA_MAGIC_CHECK.

## elm_store_fetch_func_set()

void elm_store_fetch_func_set | ( | Elm_Store * | st,
|  | Elm_Store_Item_Fetch_Cb | func,
|  | const void * | data )

Set the function used to deal with fetching of items.

This function is called per item that needs data to be fetched when it becomes visible and such data is needed. This function is normally run from a thread (unless elm_store_fetch_thread_set() disables this). The fetch function is to read data from the source and fill a structure allocated for this item with fields and then rely on the mapping setup to tell Store how to take a field in the structure and apply it to a genlist item.

Parameters

  st | The store to set the function of
  func | The function to be called
  data | the data pointer to be passed to the `func` function when called

References EINA_MAGIC_CHECK.

## elm_store_unfetch_func_set()

void elm_store_unfetch_func_set | ( | Elm_Store * | st,
|  | Elm_Store_Item_Unfetch_Cb | func,
|  | const void * | data )

Set the function used to free the structure allocated for the item.

This function is called per item when it is not needed in memory anymore and should free the structure allocated in and filled in the function set by elm_store_fetch_func_set().

Parameters

  st | The store to set the function of
  func | The function to be called
  data | the data pointer to be passed to the `func` function when called

References EINA_MAGIC_CHECK.

## elm_store_fetch_thread_set()

void elm_store_fetch_thread_set | ( | Elm_Store * | st,
|  | Eina_Bool | use_thread )

Enable or disable fetching in a thread for Store.

Parameters

  st | The store to modify
  use_thread | `EINA_TRUE` to use a thread to fetch, `EINA_FALSE` don't use a thread.

References EINA_MAGIC_CHECK.

## elm_store_fetch_thread_get()

Eina_Bool elm_store_fetch_thread_get | ( | const Elm_Store * | st | ) |

Get the thread enabled fetching option for Store.

Returns
  The state set currently for the store.

See also
  elm_store_fetch_thread_set()

References EINA_FALSE, and EINA_MAGIC_CHECK.

## elm_store_sorted_set()

void elm_store_sorted_set | ( | Elm_Store * | st,
|  | Eina_Bool | sorted )

Set if items are to be sorted or not.

By default items are not sorted, but read "in order" as they are found. If you want to sort, your list function set by elm_store_list_func_set() must provide a sort ID to sort by, and then Store will take care of sorting when it inserts items. You should set this up before you begin listing items in the store and then never change it again.

Parameters

  st | The store to modify
  sorted | `EINA_TRUE` if we are to sort, `EINA_FALSE` if not.

References EINA_MAGIC_CHECK.

## elm_store_sorted_get()

Eina_Bool elm_store_sorted_get | ( | const Elm_Store * | st | ) |

Get the sorting flag.

Get the sorted flag as set by elm_store_sorted_set().

Parameters

  st | The store to query

Returns
  `EINA_TRUE` if sorted, `EINA_FALSE` if not.

References EINA_FALSE, and EINA_MAGIC_CHECK.

## elm_store_item_data_set()

void elm_store_item_data_set | ( | Elm_Store_Item * | sti,
|  | void * | data )

Set the item data holding item fields to map to item values in genlist.

Once you decode an item, allocate a structure for it and fill the structure, you should set the item data with this function (eg in the fetch function). This item pointer is the base offset to use when mapping fields to item values. Once you unfetch, store will handle NULLing the data pointer for you.

Parameters

  sti | The store item to set the data pointer of
  data | The data pointer to set.

References EINA_MAGIC_CHECK.

## elm_store_item_data_get()

void * elm_store_item_data_get | ( | Elm_Store_Item * | sti | ) |

Get the item data.

This gets the data pointer set by elm_store_item_data_set().

Parameters

  sti | The store item to query

Returns
  The data pointer set on the item

References EINA_MAGIC_CHECK.

## elm_store_item_store_get()

const Elm_Store * elm_store_item_store_get | ( | const Elm_Store_Item * | sti | ) |

Fetch the store than a store item belongs to.

This fetches the store object that owns the store item.

Parameters

  sti | The store item to query

Returns
  The store the item belongs to

References EINA_MAGIC_CHECK.

## elm_store_item_genlist_item_get()

const Elm_Object_Item * elm_store_item_genlist_item_get | ( | const Elm_Store_Item * | sti | ) |

Fetch the genlist item that this store item controls.

Parameters

  sti | The store item to query

Returns
  The genlist object item handle controlled by this store item

References EINA_MAGIC_CHECK.