Tizen Native API  5.5
Elementary Store

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.

Typedefs

typedef struct _Elm_Store Elm_Store
typedef struct _Elm_Store_Item Elm_Store_Item
typedef struct _Elm_Store_Item_Info Elm_Store_Item_Info
typedef struct
_Elm_Store_Item_Info_Filesystem 
Elm_Store_Item_Info_Filesystem
typedef struct
_Elm_Store_Item_Mapping 
Elm_Store_Item_Mapping
typedef struct
_Elm_Store_Item_Mapping_Empty 
Elm_Store_Item_Mapping_Empty
typedef struct
_Elm_Store_Item_Mapping_Photo 
Elm_Store_Item_Mapping_Photo
typedef Eina_Bool(* Elm_Store_Item_List_Cb )(void *data, Elm_Store_Item_Info *info)
typedef void(* Elm_Store_Item_Fetch_Cb )(void *data, Elm_Store_Item *sti)
typedef void(* Elm_Store_Item_Unfetch_Cb )(void *data, Elm_Store_Item *sti)
typedef void *(* Elm_Store_Item_Mapping_Cb )(void *data, Elm_Store_Item *sti, const char *part)

Defines

#define ELM_STORE_ITEM_MAPPING_END   { ELM_STORE_ITEM_MAPPING_NONE, NULL, 0, { .empty = { EINA_TRUE } } }
#define ELM_STORE_ITEM_MAPPING_OFFSET(st, it)   offsetof(st, it)

Define Documentation

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

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 void(* Elm_Store_Item_Fetch_Cb)(void *data, Elm_Store_Item *sti)

Function to call to fetch item data

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 Eina_Bool(* Elm_Store_Item_List_Cb)(void *data, Elm_Store_Item_Info *info)

> 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. Function to call for listing an 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 void*(* Elm_Store_Item_Mapping_Cb)(void *data, Elm_Store_Item *sti, const char *part)

Custom mapping function to call

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

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 void(* Elm_Store_Item_Unfetch_Cb)(void *data, Elm_Store_Item *sti)

Function to cal lto un-fetch (free) an item


Enumeration Type Documentation

Possible mappings types.

Since (EFL) :
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)