Elementary provides a prefs (for "preferences") infrastructure, which consists of two sets of APIs: More...

Macros
#define	ELM_PREFS_EVENT_PAGE_CHANGED (&(_ELM_PREFS_EVENT_PAGE_CHANGED))
	s

#define	ELM_PREFS_EVENT_PAGE_SAVED (&(_ELM_PREFS_EVENT_PAGE_SAVED))
	s

#define	ELM_PREFS_EVENT_PAGE_RESET (&(_ELM_PREFS_EVENT_PAGE_RESET))
	s

#define	ELM_PREFS_EVENT_PAGE_LOADED (&(_ELM_PREFS_EVENT_PAGE_LOADED))
	s

#define	ELM_PREFS_EVENT_ITEM_CHANGED (&(_ELM_PREFS_EVENT_ITEM_CHANGED))
	s

#define	ELM_PREFS_EVENT_ACTION (&(_ELM_PREFS_EVENT_ACTION))
	ss

Typedefs
typedef enum _Elm_Prefs_Item_Type	Elm_Prefs_Item_Type
	Elm Prefs item types. More...

typedef struct _Elm_Prefs_Data	Elm_Prefs_Data
	An Elm Prefs Data handle. More...

typedef struct _Elm_Prefs_Data_Event_Changed	Elm_Prefs_Data_Event_Changed
	An Elm Prefs ELM_PREFS_DATA_EVENT_ITEM_CHANGED event info data blob. More...

Enumerations
enum	_Elm_Prefs_Item_Type { , ELM_PREFS_TYPE_BOOL, ELM_PREFS_TYPE_INT, ELM_PREFS_TYPE_FLOAT, ELM_PREFS_TYPE_LABEL, ELM_PREFS_TYPE_DATE, ELM_PREFS_TYPE_TEXT, ELM_PREFS_TYPE_TEXTAREA, ELM_PREFS_TYPE_PAGE, ELM_PREFS_TYPE_RESET, ELM_PREFS_TYPE_SAVE, ELM_PREFS_TYPE_SEPARATOR, ELM_PREFS_TYPE_SWALLOW }
	Elm Prefs item types. More...

enum	Elm_Prefs_Data_Event_Type { , ELM_PREFS_DATA_EVENT_ITEM_CHANGED, ELM_PREFS_DATA_EVENT_LAST }
	Types of events a given prefs data handle may issue. More...

Functions
Elm_Prefs_Data *	elm_prefs_data_new (const char data_file, const char key, Eet_File_Mode mode)
	Create a new prefs data handle. More...

Eina_Bool	elm_prefs_data_version_set (Elm_Prefs_Data *prefs_data, unsigned int version)
	Set the version field of a given prefs data handle. More...

unsigned int	elm_prefs_data_version_get (const Elm_Prefs_Data *prefs_data)
	Get the version field of a given prefs data handle. More...

Elm_Prefs_Data *	elm_prefs_data_ref (Elm_Prefs_Data *prefs_data)
	Increment reference count on a given prefs data handle. More...

void	elm_prefs_data_unref (Elm_Prefs_Data *prefs_data)
	Decrement reference count on a given prefs data handle. More...

Eina_Bool	elm_prefs_data_value_set (Elm_Prefs_Data prefs_data, const char path, const Elm_Prefs_Item_Type type, const Eina_Value *value)
	Set (or delete) one value of a given prefs data handle. More...

Eina_Bool	elm_prefs_data_value_get (const Elm_Prefs_Data prefs_data, const char path, Elm_Prefs_Item_Type type, Eina_Value value)
	Get one value of a given prefs data handle (by key). More...

Eina_Bool	elm_prefs_data_event_callback_add (Elm_Prefs_Data prefs_data, Elm_Prefs_Data_Event_Type type, Elm_Prefs_Data_Event_Cb cb, const void cb_data)
	Register a callback for one of the prefs data events. More...

Eina_Bool	elm_prefs_data_event_callback_del (Elm_Prefs_Data prefs_data, Elm_Prefs_Data_Event_Type type, Elm_Prefs_Data_Event_Cb cb, const void cb_data)
	Unregister a callback for one of the prefs data events. More...

void	elm_prefs_data_autosave_set (Elm_Prefs_Data *prefs_data, Eina_Bool autosave)
	Set whether a given elm prefs data handle should save its values back automatically on changes. More...

Eina_Bool	elm_prefs_data_autosave_get (const Elm_Prefs_Data *prefs_data)
	Get whether a given elm prefs data handle is saving its values back automatically on changes. More...

Eina_Bool	elm_prefs_data_save (const Elm_Prefs_Data prefs_data, const char file, const char *key)
	Save, manually, a given elm prefs data handle data back, on the given file and key. More...

Detailed Description

Elementary provides a prefs (for "preferences") infrastructure, which consists of two sets of APIs:

prefs data and
prefs view.

Prefs Data

Prefs data are simple key/value storage handles. One is able to set/get their values, which are Eina_Value blobs (i.e. dynamically typed). You may also control the version of this data set, for updating purposes. Finally, you may register callbacks on changes on these data.

The main user of prefs data is the prefs widget. After its creation, it's bound to a given prefs data handle (if not, if gets its values from its definition file, which may have defaults). An elm prefs widget has its visuals defined by an .epb file, which is a compiled form of a .edc counterpart – a textual definition much like Edje .edc files. On these files, one defines the values (items) a prefs widget hold, which translate to other Elementary widgets. In other words, it does the mapping between UI widgets into prefs data values, and it keeps the synchrony between its child widgets' states and their corresponding prefs data values.

Typedef Documentation

Elm_Prefs_Data

An Elm Prefs Data handle.

Since: 1.8

Elm_Prefs_Data_Event_Changed

An Elm Prefs ELM_PREFS_DATA_EVENT_ITEM_CHANGED event info data blob.

Since: 1.8

typedef enum _Elm_Prefs_Item_Type Elm_Prefs_Item_Type

Elm Prefs item types.

Since: 1.8

Enumeration Type Documentation

enum _Elm_Prefs_Item_Type

Elm Prefs item types.

Since: 1.8

Enumerator
ELM_PREFS_TYPE_BOOL	boolean type, bound to checkbox-like UI elements
ELM_PREFS_TYPE_INT	integer type, bound to spinner-like UI elements
ELM_PREFS_TYPE_FLOAT	floating point type, bound to spinner-like UI elements
ELM_PREFS_TYPE_LABEL	label type, bound to read-only, label UI elements
ELM_PREFS_TYPE_DATE	date type, bound to date selection UI elements
ELM_PREFS_TYPE_TEXT	text type, bound to single-line, text entry UI elements
ELM_PREFS_TYPE_TEXTAREA	text area type, bound to multi-line, text entry UI elements
ELM_PREFS_TYPE_PAGE	page type, used to nest pages
ELM_PREFS_TYPE_RESET	values resetting trigger type, bound to button-like UI elements
ELM_PREFS_TYPE_SAVE	saving trigger type, bound to button-like UI elements
ELM_PREFS_TYPE_SEPARATOR	separator type, bound to separator-like UI elements
ELM_PREFS_TYPE_SWALLOW	swallow type, bound to an empty 'spot' on the UI meant to receive and display external content

enum Elm_Prefs_Data_Event_Type

Types of events a given prefs data handle may issue.

See also: elm_prefs_data_event_callback_add()

Since: 1.8

Enumerator

ELM_PREFS_DATA_EVENT_ITEM_CHANGED

The group of values has been automatically saved (event info is the group's name (key))

ELM_PREFS_DATA_EVENT_LAST

A given item (prefs data value) has been changed (event info is an Elm_Prefs_Data_Event_Changed pointer)

sentinel value, don't use it

Function Documentation

Eina_Bool elm_prefs_data_autosave_get ( const Elm_Prefs_Data * prefs_data )

Get whether a given elm prefs data handle is saving its values back automatically on changes.

Parameters

prefs_data A valid prefs data handle

Returns: EINA_TRUE if prefs_data is saving automatically, EINA_FALSE otherwise.

See also: elm_prefs_data_autosave_set()

Since: 1.8

void elm_prefs_data_autosave_set	(	Elm_Prefs_Data *	prefs_data,
		Eina_Bool	autosave
	)

Set whether a given elm prefs data handle should save its values back automatically on changes.

Parameters

prefs_data	A valid prefs data handle
autosave	`EINA_TRUE` to save automatically, `EINA_FALSE` otherwise.

If autosave is EINA_TRUE, every call to elm_prefs_data_value_set() will implicitly issue elm_prefs_data_save() too.

Warning: This call will do nothing if prefs_data was created with mode EET_FILE_MODE_READ – auto saving will be always disabled in this mode, as it can't write back.

See also: elm_prefs_data_autosave_get()

Since: 1.8

Eina_Bool elm_prefs_data_event_callback_add	(	Elm_Prefs_Data *	prefs_data,
		Elm_Prefs_Data_Event_Type	type,
		Elm_Prefs_Data_Event_Cb	cb,
		const void *	cb_data
	)

Register a callback for one of the prefs data events.

Parameters

prefs_data	A valid prefs data handle
type	The type of event to register to
cb	The callback function to issue on this event
cb_data	The data pointer to pass to cb on this event

Returns: EINA_TRUE on success, EINA_FALSE otherwise

See also: Elm_Prefs_Data_Event_Type for more details on the events.; elm_prefs_data_event_callback_del()

Since: 1.8

References ELM_PREFS_DATA_EVENT_LAST.

Eina_Bool elm_prefs_data_event_callback_del	(	Elm_Prefs_Data *	prefs_data,
		Elm_Prefs_Data_Event_Type	type,
		Elm_Prefs_Data_Event_Cb	cb,
		const void *	cb_data
	)

Unregister a callback for one of the prefs data events.

Parameters

prefs_data	A valid prefs data handle
type	The type of event to unregister
cb	The callback function being used to this event
cb_data	The data pointer being passed to cb on this event

Returns: EINA_TRUE on success, EINA_FALSE otherwise

See also: Elm_Prefs_Data_Event_Type for more details on the events.; elm_prefs_data_event_callback_add()

Note: If a same event callback (with matching type, callback function and data pointers) was added more than once on prefs_data, them same number of matching calls of this type have to issued to delete all them.

Since: 1.8

Elm_Prefs_Data* elm_prefs_data_new	(	const char *	data_file,
		const char *	key,
		Eet_File_Mode	mode
	)

Create a new prefs data handle.

Parameters

data_file	The (user) file where to read data from
key	The key where the data is stored under
mode	The mode of access to the given file

Returns: A new prefs data handle

If data_file is NULL, efreet_config_home_get()/<appname>/preferences.cfg will be used, by default. If key is NULL, it is considered a default key – "main".

If mode is EET_FILE_MODE_READ, autosave will be always false for this elm_prefs_data handle. If mode is EET_FILE_MODE_WRITE, than data_file won't be read, but just written to.

Note: An elm prefs data handle starts with a reference count of 1 (see elm_prefs_data_ref()). Use elm_prefs_data_unref() to delete it.

Since: 1.8

Elm_Prefs_Data* elm_prefs_data_ref ( Elm_Prefs_Data * prefs_data )

Increment reference count on a given prefs data handle.

Parameters

prefs_data A valid prefs data handle

Returns: The same prefs data handle, prefs_data

This increments the reference count of by 1. Use this to pass the handle safely to contexts other than the creation one, for example. Only when the reference count on a prefs data handle reaches 0 (see elm_prefs_data_unref()) will it be deleted.

Since: 1.8

Eina_Bool elm_prefs_data_save	(	const Elm_Prefs_Data *	prefs_data,
		const char *	file,
		const char *	key
	)

Save, manually, a given elm prefs data handle data back, on the given file and key.

Parameters

prefs_data	A valid prefs data handle
file	The file (path) to save to (`NULL` means same file as it was opened with)
key	The under which to save values (`NULL` means the same key as it was opened with)

Returns: EINA_TRUE on success, EINA_FALSE otherwise.

See also: elm_prefs_data_autosave_set()

Since: 1.8

void elm_prefs_data_unref ( Elm_Prefs_Data * prefs_data )

Decrement reference count on a given prefs data handle.

Parameters

prefs_data A valid prefs data handle

This decrements the reference count of by 1. When the reference count on reach 0, it will it be deleted.

See also: elm_prefs_data_ref() for more details.

Since: 1.8

Eina_Bool elm_prefs_data_value_get	(	const Elm_Prefs_Data *	prefs_data,
		const char *	path,
		Elm_Prefs_Item_Type *	type,
		Eina_Value *	value
	)

Get one value of a given prefs data handle (by key).

Parameters

prefs_data	A valid prefs data handle
path	The (unique) name (key) of the given value
type	The item type associated with the value
value	A valid `Eina_Value` handle, where to store the value, itself.

Returns: EINA_TRUE on success, EINA_FALSE otherwise

This will retrieve one of 's values, by name. The value itself will be written to value, which will be overriden.

Since: 1.8

Eina_Bool elm_prefs_data_value_set	(	Elm_Prefs_Data *	prefs_data,
		const char *	path,
		const Elm_Prefs_Item_Type	type,
		const Eina_Value *	value
	)

Set (or delete) one value of a given prefs data handle.

Parameters

prefs_data	A valid prefs data handle
path	The (unique) name (key) of the given value
type	The item type to which the value is to be associated
value	The value, itself. It must be a valid `Eina_Value` handle, bound to a given type and value or `NULL`. On the second case, the call will actually delete the given key from prefs_data.

Returns: EINA_TRUE on success, EINA_FALSE otherwise

A prefs data handle holds a list of key/value entries. This will set one of 's values, by name. The value itself may be any valid and filled up Eina_Value handle.

Since: 1.8

References ELM_PREFS_DATA_EVENT_ITEM_CHANGED.

unsigned int elm_prefs_data_version_get ( const Elm_Prefs_Data * prefs_data )

Get the version field of a given prefs data handle.

Parameters

prefs_data A valid prefs data handle

Returns: The version of prefs_data or -1, on errors.

See also: elm_prefs_data_version_set()

Since: 1.8

Eina_Bool elm_prefs_data_version_set	(	Elm_Prefs_Data *	prefs_data,
		unsigned int	version
	)

Set the version field of a given prefs data handle.

Parameters

prefs_data	A valid prefs data handle
version	The version number

Returns: EINA_TRUE on success, EINA_FALSE otherwise

See also: elm_prefs_data_version_get()

Since: 1.8

Macros

Typedefs

Enumerations

Functions

Detailed Description

Prefs Data

Typedef Documentation

Enumeration Type Documentation

Function Documentation