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

Data Structures
struct	_Elm_Prefs_Item_Spec_Void

struct	_Elm_Prefs_Item_Spec_Bool

struct	_Elm_Prefs_Item_Spec_Int

struct	_Elm_Prefs_Item_Spec_Float

struct	_Elm_Prefs_Item_Spec_String

struct	_Elm_Prefs_Item_Spec_Date

struct	_Elm_Prefs_Item_Spec_Page

union	_Elm_Prefs_Item_Spec

struct	_Elm_Prefs_Item_Iface
	Interface between items of the Prefs widget and the real widgets implementing them. More...

struct	_Elm_Prefs_Item_Iface_Info
	Convenience struct used to mass-register widgets implementing prefs items interfaces. More...

struct	_Elm_Prefs_Page_Iface
	Interface between pages of the Prefs widget and the real widgets implementing them. More...

struct	_Elm_Prefs_Page_Iface_Info
	Convenience struct used to mass-register widgets implementing prefs pages interfaces. More...

struct	_Elm_Prefs_Data_Event_Changed

Macros
#define	ELM_PREFS_CLASS elm_prefs_class_get()
	Elementary preferences class.

#define	ELM_PREFS_EVENT_PAGE_CHANGED (&(_ELM_PREFS_EVENT_PAGE_CHANGED))
	Called when page changed. More...

#define	ELM_PREFS_EVENT_PAGE_SAVED (&(_ELM_PREFS_EVENT_PAGE_SAVED))
	Called when page was saved. More...

#define	ELM_PREFS_EVENT_PAGE_LOADED (&(_ELM_PREFS_EVENT_PAGE_LOADED))
	Called when page got loaded. More...

#define	ELM_PREFS_EVENT_ITEM_CHANGED (&(_ELM_PREFS_EVENT_ITEM_CHANGED))
	Called when item changed. More...

#define	ELM_PREFS_EVENT_ACTION (&(_ELM_PREFS_EVENT_ACTION))
	Called when action was done. More...

Typedefs
typedef struct _Elm_Prefs_Item_Spec_Void	Elm_Prefs_Item_Spec_Void

typedef struct _Elm_Prefs_Item_Spec_Bool	Elm_Prefs_Item_Spec_Bool

typedef struct _Elm_Prefs_Item_Spec_Int	Elm_Prefs_Item_Spec_Int

typedef struct _Elm_Prefs_Item_Spec_Float	Elm_Prefs_Item_Spec_Float

typedef struct _Elm_Prefs_Item_Spec_String	Elm_Prefs_Item_Spec_String

typedef struct _Elm_Prefs_Item_Spec_Date	Elm_Prefs_Item_Spec_Date

typedef struct _Elm_Prefs_Item_Spec_Page	Elm_Prefs_Item_Spec_Page

typedef union _Elm_Prefs_Item_Spec	Elm_Prefs_Item_Spec

typedef struct _Elm_Prefs_Item_Iface	Elm_Prefs_Item_Iface

typedef void(*	Elm_Prefs_Item_Changed_Cb) (Evas_Object *it_obj)
	Elementary prefs' item widget changed function signature.

typedef struct _Elm_Prefs_Item_Iface_Info	Elm_Prefs_Item_Iface_Info

typedef struct _Elm_Prefs_Page_Iface	Elm_Prefs_Page_Iface

typedef struct _Elm_Prefs_Page_Iface_Info	Elm_Prefs_Page_Iface_Info

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

typedef void(*	Elm_Prefs_Data_Event_Cb) (void cb_data, Elm_Prefs_Data_Event_Type type, Elm_Prefs_Data prefs_data, void *event_info)

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_Reset_Mode { ELM_PREFS_RESET_DEFAULTS = 0 , ELM_PREFS_RESET_LAST }
	Modes of resetting a prefs widget. More...

enum	Elm_Prefs_Item_Type { ELM_PREFS_TYPE_UNKNOWN = 0 , ELM_PREFS_TYPE_ACTION , 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_GROUP_AUTOSAVED , ELM_PREFS_DATA_EVENT_ITEM_CHANGED , ELM_PREFS_DATA_EVENT_LAST }
	Types of events a given prefs data handle may issue. More...

Functions
Evas_Object *	elm_prefs_add (Evas_Object *parent)
	Add a new prefs widget. More...

void	elm_prefs_item_iface_register (const Elm_Prefs_Item_Iface_Info *array)
	Mass-register widgets implementing prefs items interfaces. More...

void	elm_prefs_item_iface_unregister (const Elm_Prefs_Item_Iface_Info *array)
	Mass-unregister widgets implementing prefs items interfaces. More...

Eina_Bool	elm_prefs_item_widget_common_add (Evas_Object prefs, Evas_Object obj)

void	elm_prefs_page_iface_register (const Elm_Prefs_Page_Iface_Info *array)
	Mass-register widgets implementing prefs pages interfaces. More...

void	elm_prefs_page_iface_unregister (const Elm_Prefs_Page_Iface_Info *array)
	Mass-unregister widgets implementing prefs pages interfaces. More...

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

EOAPI Eina_Bool	elm_obj_prefs_data_set (Eo obj, Elm_Prefs_Data data)
	Set user data for a given prefs widget. More...

EOAPI Elm_Prefs_Data *	elm_obj_prefs_data_get (const Eo *obj)
	Set user data for a given prefs widget. More...

EOAPI void	elm_obj_prefs_autosave_set (Eo *obj, Eina_Bool autosave)
	Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes. More...

EOAPI Eina_Bool	elm_obj_prefs_autosave_get (const Eo *obj)
	Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes. More...

EOAPI void	elm_obj_prefs_reset (Eo *obj, Elm_Prefs_Reset_Mode mode)
	Reset the values of a given prefs widget to a previous state. More...

EOAPI Eina_Bool	elm_obj_prefs_item_value_set (Eo obj, const char name, const Eina_Value *value)
	Set the value on a given prefs widget's item. More...

EOAPI Eina_Bool	elm_obj_prefs_item_value_get (const Eo obj, const char name, Eina_Value *value)
	Get the value of a given prefs widget's item. More...

EOAPI const Efl_Canvas_Object *	elm_obj_prefs_item_object_get (Eo obj, const char name)
	Get the Elementary widget bound to a given prefs widget's item. More...

EOAPI void	elm_obj_prefs_item_disabled_set (Eo obj, const char name, Eina_Bool disabled)
	Set whether the widget bound to a given prefs widget's item is disabled or not. More...

EOAPI Eina_Bool	elm_obj_prefs_item_disabled_get (const Eo obj, const char name)
	Get whether the widget bound to a given prefs widget's item is disabled or not. More...

EOAPI Eina_Bool	elm_obj_prefs_item_swallow (Eo obj, const char name, Efl_Canvas_Object *child)
	"Swallows" an object into a SWALLOW item of a prefs widget. More...

EOAPI void	elm_obj_prefs_item_editable_set (Eo obj, const char name, Eina_Bool editable)
	Set whether the widget bound to a given prefs widget's item is editable or not. More...

EOAPI Eina_Bool	elm_obj_prefs_item_editable_get (const Eo obj, const char name)
	Get whether the widget bound to a given prefs widget's item is editable or not. More...

EOAPI Efl_Canvas_Object *	elm_obj_prefs_item_unswallow (Eo obj, const char name)
	Unswallow an object from a SWALLOW item of a prefs widget. More...

EOAPI void	elm_obj_prefs_item_visible_set (Eo obj, const char name, Eina_Bool visible)
	Set whether the widget bound to given prefs widget's item should be visible or not. More...

EOAPI Eina_Bool	elm_obj_prefs_item_visible_get (const Eo obj, const char name)
	Get whether the widget bound to a given prefs widget's item is visible or not. More...

Eina_Bool	elm_prefs_page_widget_common_add (Evas_Object prefs, Evas_Object obj)
	Add a page widget to an elm_prefs object.

Eina_Bool	elm_prefs_file_set (Eo obj, const char file, const char *page)
	Set file and page to populate a given prefs widget's interface. More...

Eina_Bool	elm_prefs_file_get (const Eo obj, const char file, const char *page)
	Get file and page bound to a given prefs widget. 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.

Prefs

Prefs is a special widget inside Elementary. It is mainly targeted to configuration dialogs. Its viewport is blank until you associate a definition file to it. That file (usually with .epb extension), is a binary format (Eet) one, coming from a human-readable textual declaration. This textual form, an Elementary prefs collection (usually with .epc extension), is translated to the binary form by means of the prefs_cc compiler.

On it one declares UI elements to populate prefs widgets, which are contained in pages (a prefs widget is always bound to one page). Those elements get properties like:

default value,
maximum and minimum ranges,
acceptance and denial regular expressions, for strings,
visibility,
persistence,
editability, etc.

Once a prefs widget is created, after elm_prefs_file_set() is issued on it, all of its UI elements will get default values, declared on that file. To fetch a user's own, personal set of those values, one gets to pair an Prefs Data handle to the prefs widget.

Personal, prefs data values with keys matching the ones present on the file passed on elm_prefs_file_set() to will have their values applied to the respective UI elements of the widget.

When a prefs widget dies, the values of the elements declared on its .epb file marked as permanent will be written back to the user prefs data handle, if it is writable. One is also able to make this writing event to take place automatically after each UI element modification by using elm_prefs_autosave_set().

This widget emits the following signals:

"page,saved": a given page has had its values saved back on user config file (event info is the page's name)
"page,reset": a given page has had its values reset (event info is the page's name)
"page,changed": a given page has been loaded with user (.cfg) values (event info is the page's name)
"page,loaded": a given page has been loaded with system (.epb) values (event info is the page's name)
"item,changed": a given page's item has changed (event info is the item's full hierarchical name, in the form "page:subpage:subsubpage:item")
"action": an action item has been triggered (event info is the item's full hierarchical name, in the form "page:subpage:subsubpage:item")

epcref

The following are examples on how to use prefs:

Macro Definition Documentation

◆ ELM_PREFS_EVENT_PAGE_CHANGED

#define ELM_PREFS_EVENT_PAGE_CHANGED (&(_ELM_PREFS_EVENT_PAGE_CHANGED))

Called when page changed.

Returns: const char *

◆ ELM_PREFS_EVENT_PAGE_SAVED

#define ELM_PREFS_EVENT_PAGE_SAVED (&(_ELM_PREFS_EVENT_PAGE_SAVED))

Called when page was saved.

Returns: const char *

◆ ELM_PREFS_EVENT_PAGE_LOADED

#define ELM_PREFS_EVENT_PAGE_LOADED (&(_ELM_PREFS_EVENT_PAGE_LOADED))

Called when page got loaded.

Returns: const char *

◆ ELM_PREFS_EVENT_ITEM_CHANGED

#define ELM_PREFS_EVENT_ITEM_CHANGED (&(_ELM_PREFS_EVENT_ITEM_CHANGED))

Called when item changed.

Returns: const char *

◆ ELM_PREFS_EVENT_ACTION

#define ELM_PREFS_EVENT_ACTION (&(_ELM_PREFS_EVENT_ACTION))

Called when action was done.

Returns: const char *

Typedef Documentation

◆ Elm_Prefs_Data

Elm_Prefs_Data

An Elm Prefs Data handle.

Since: 1.8

◆ Elm_Prefs_Data_Event_Changed

Elm_Prefs_Data_Event_Changed

An Elm Prefs ELM_PREFS_DATA_EVENT_ITEM_CHANGED event info data blob.

Since: 1.8

Enumeration Type Documentation

◆ Elm_Prefs_Reset_Mode

enum Elm_Prefs_Reset_Mode

Modes of resetting a prefs widget.

see elm_prefs_reset()

Since: 1.8

Enumerator

ELM_PREFS_RESET_DEFAULTS

reset to default values, declared in its .epb file

ELM_PREFS_RESET_LAST

prefs will keep a small history of changes, so this resets back to last batch of changes on the UI elements.

it does not work on autosave mode

◆ Elm_Prefs_Item_Type

enum Elm_Prefs_Item_Type

Elm Prefs item types.

Since: 1.8

Enumerator
ELM_PREFS_TYPE_UNKNOWN	Unknown type.
ELM_PREFS_TYPE_ACTION	action type, bound to button-like UI elements
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

◆ Elm_Prefs_Data_Event_Type

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

◆ elm_prefs_add()

Evas_Object * elm_prefs_add ( Evas_Object * parent )

Add a new prefs widget.

Parameters

parent The parent widget to hold the new one

Returns: The new object or NULL, on errors

Since: 1.8

References EINA_SAFETY_ON_NULL_RETURN_VAL.

◆ elm_prefs_item_iface_register()

void elm_prefs_item_iface_register ( const Elm_Prefs_Item_Iface_Info * array )

Mass-register widgets implementing prefs items interfaces.

Parameters

array An array of #Elm_Prefs_Iface_Info structs, NULL terminated.

This will register all item interfaces declared on array in Elementary, so that the prefs widget will recognize them on .epc files 'widget:' (item) declarations.

See also: elm_prefs_item_iface_unregister()

Since: 1.8

References _Elm_Prefs_Item_Iface::abi_version, eina_hash_add(), eina_hash_direct_add(), ELM_PREFS_TYPE_UNKNOWN, ERR, _Elm_Prefs_Item_Iface_Info::info, _Elm_Prefs_Item_Iface::types, and _Elm_Prefs_Item_Iface_Info::widget_name.

◆ elm_prefs_item_iface_unregister()

void elm_prefs_item_iface_unregister ( const Elm_Prefs_Item_Iface_Info * array )

Mass-unregister widgets implementing prefs items interfaces.

Parameters

array An array of #Elm_Prefs_Iface_Info structs, NULL terminated.

This will unregister all item interfaces declared on array in Elementary, given they had been previously registered.

See also: elm_prefs_item_iface_register() for more details

Since: 1.8

References eina_hash_del(), ELM_PREFS_TYPE_UNKNOWN, _Elm_Prefs_Item_Iface_Info::info, _Elm_Prefs_Item_Iface::types, and _Elm_Prefs_Item_Iface_Info::widget_name.

◆ elm_prefs_page_iface_register()

void elm_prefs_page_iface_register ( const Elm_Prefs_Page_Iface_Info * array )

Mass-register widgets implementing prefs pages interfaces.

Parameters

array An array of #Elm_Prefs_Iface_Info structs, NULL terminated.

This will register all page interfaces declared on array in Elementary, so that the prefs widget will recognize them on .epc files 'widget:' (page) declarations.

See also: elm_prefs_page_iface_unregister()

Since: 1.8

References _Elm_Prefs_Page_Iface::abi_version, eina_hash_direct_add(), ERR, _Elm_Prefs_Page_Iface_Info::info, and _Elm_Prefs_Page_Iface_Info::widget_name.

◆ elm_prefs_page_iface_unregister()

void elm_prefs_page_iface_unregister ( const Elm_Prefs_Page_Iface_Info * array )

Mass-unregister widgets implementing prefs pages interfaces.

Parameters

array An array of #Elm_Prefs_Iface_Info structs, NULL terminated.

This will unregister all page interfaces declared on array in Elementary, given they had been previously registered.

See also: elm_prefs_page_iface_register() for more details

Since: 1.8

References eina_hash_del(), _Elm_Prefs_Page_Iface_Info::info, and _Elm_Prefs_Page_Iface_Info::widget_name.

◆ elm_prefs_data_new()

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

References EINA_SAFETY_ON_TRUE_RETURN_VAL.

◆ elm_prefs_data_version_set()

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

References EINA_FALSE, and EINA_TRUE.

◆ elm_prefs_data_version_get()

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

◆ elm_prefs_data_ref()

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

◆ elm_prefs_data_unref()

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

◆ elm_prefs_data_value_set()

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

◆ elm_prefs_data_value_get()

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

◆ elm_prefs_data_event_callback_add()

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

◆ elm_prefs_data_event_callback_del()

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_autosave_set()

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

References ecore_poller_add(), ECORE_POLLER_CORE, ecore_poller_del(), and EET_FILE_MODE_READ.

◆ elm_prefs_data_autosave_get()

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

References EINA_FALSE.

◆ elm_prefs_data_save()

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

References ecore_poller_del(), EET_FILE_MODE_READ, EINA_FALSE, EINA_TRUE, and ERR.

◆ elm_obj_prefs_data_set()

EOAPI Eina_Bool elm_obj_prefs_data_set	(	Eo *	obj,
		Elm_Prefs_Data *	data
	)

Set user data for a given prefs widget.

Once a prefs widget is created, after elm_prefs_file_set() is issued on it, all of its UI elements will get default values, when declared on that file. To fetch a user's own, personal set of those values, one gets to pair a prefs data handle to the prefs widget. This is what this call is intended for.

Prefs data values from prefs_data with keys matching the ones present on the file passed on elm_prefs_file_set() to obj will have their values applied to the respective UI elements of the widget.

When obj dies, the values of the elements declared on its $.epb file (the one set on elm_prefs_file_set()) marked as permanent will be written back to prefs_data, if it is writable. One is also able to make this writing event to take place automatically after each UI element modification by using elm_prefs_autosave_set().

Note: obj will keep a reference of its own for prefs_data, but you should still unreference it by yourself, after the widget is gone.

Parameters

[in]	obj	The object.
[in]	data	A valid prefs_data handle

Returns: true, on success, false otherwise

Since: 1.8

◆ elm_obj_prefs_data_get()

EOAPI Elm_Prefs_Data * elm_obj_prefs_data_get ( const Eo * obj )

Set user data for a given prefs widget.

Once a prefs widget is created, after elm_prefs_file_set() is issued on it, all of its UI elements will get default values, when declared on that file. To fetch a user's own, personal set of those values, one gets to pair a prefs data handle to the prefs widget. This is what this call is intended for.

Prefs data values from prefs_data with keys matching the ones present on the file passed on elm_prefs_file_set() to obj will have their values applied to the respective UI elements of the widget.

When obj dies, the values of the elements declared on its $.epb file (the one set on elm_prefs_file_set()) marked as permanent will be written back to prefs_data, if it is writable. One is also able to make this writing event to take place automatically after each UI element modification by using elm_prefs_autosave_set().

Note: obj will keep a reference of its own for prefs_data, but you should still unreference it by yourself, after the widget is gone.

Parameters

[in] obj The object.

Returns: A valid prefs_data handle

Since: 1.8

◆ elm_obj_prefs_autosave_set()

EOAPI void elm_obj_prefs_autosave_set	(	Eo *	obj,
		Eina_Bool	autosave
	)

Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes.

If autosave is true, every call to elm_prefs_item_value_set(), every Elm_Prefs_Data_Event_Type.ELM_PREFS_DATA_EVENT_ITEM_CHANGED event coming for its prefs data and every UI element direct value changing will implicitly make the prefs values to be flushed back to it prefs data. If a prefs data handle with no writing permissions or no prefs data is set on prefs, naturally nothing will happen.

Parameters

[in]	obj	The object.
[in]	autosave	`true` to save automatically, `false` otherwise.

Since: 1.8

◆ elm_obj_prefs_autosave_get()

EOAPI Eina_Bool elm_obj_prefs_autosave_get ( const Eo * obj )

Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes.

If autosave is true, every call to elm_prefs_item_value_set(), every Elm_Prefs_Data_Event_Type.ELM_PREFS_DATA_EVENT_ITEM_CHANGED event coming for its prefs data and every UI element direct value changing will implicitly make the prefs values to be flushed back to it prefs data. If a prefs data handle with no writing permissions or no prefs data is set on prefs, naturally nothing will happen.

Parameters

[in] obj The object.

Returns: true to save automatically, false otherwise.

Since: 1.8

◆ elm_obj_prefs_reset()

EOAPI void elm_obj_prefs_reset	(	Eo *	obj,
		Elm_Prefs_Reset_Mode	mode
	)

Reset the values of a given prefs widget to a previous state.

As can be seen on Elm_Prefs_Reset_Mode, there are two possible actions to be taken by this call – either to reset prefs' values to the defaults (declared on the $.epb file it is bound to) or to reset to the state they were before the last modification it got.

Parameters

[in]	obj	The object.
[in]	mode	The reset mode to apply on `prefs`

Since: 1.8

◆ elm_obj_prefs_item_value_set()

EOAPI Eina_Bool elm_obj_prefs_item_value_set	(	Eo *	obj,
		const char *	name,
		const Eina_Value *	value
	)

Set the value on a given prefs widget's item.

This will change the value of item named name programmatically.

Parameters

[in]	obj	The object.
[in]	name	The name of the item (as declared in the prefs collection)
[in]	value	The value to set on the item. It should be typed as the item expects, preferably, or a conversion will take place

Returns: true, on success, false otherwise

Since: 1.8

◆ elm_obj_prefs_item_value_get()

EOAPI Eina_Bool elm_obj_prefs_item_value_get	(	const Eo *	obj,
		const char *	name,
		Eina_Value *	value
	)

Get the value of a given prefs widget's item.

This will retrieve the value of item named name.

Parameters

[in]	obj	The object.
[in]	name	The name of the item (as declared in the prefs collection) to get value from
[out]	value	Where to store the value of the item. It will be overwritten and setup with the type the item is bound to

Returns: true, on success, false otherwise

Since: 1.8

◆ elm_obj_prefs_item_object_get()

EOAPI const Efl_Canvas_Object * elm_obj_prefs_item_object_get	(	Eo *	obj,
		const char *	name
	)

Get the Elementary widget bound to a given prefs widget's item.

This will retrieve a handle to the real widget implementing a given item of prefs, for read-only actions.

Warning: You should never modify the state of the returned widget, because it's meant to be managed by prefs, solely.

Parameters

[in]	obj	The object.
[in]	name	The name of the item (as declared in the prefs collection) to get object from

Returns: A valid widget handle, on success, or NULL, otherwise

Since: 1.8

◆ elm_obj_prefs_item_disabled_set()

EOAPI void elm_obj_prefs_item_disabled_set	(	Eo *	obj,
		const char *	name,
		Eina_Bool	disabled
	)

Set whether the widget bound to a given prefs widget's item is disabled or not.

Parameters

[in]	obj	The object.
[in]	name	The name of the item (as declared in the prefs collection) to act on
[in]	disabled	`true`, to make it disabled, `false` otherwise

Since: 1.8

◆ elm_obj_prefs_item_disabled_get()

EOAPI Eina_Bool elm_obj_prefs_item_disabled_get	(	const Eo *	obj,
		const char *	name
	)

Get whether the widget bound to a given prefs widget's item is disabled or not.

Parameters

[in]	obj	The object.
[in]	name	The name of the item (as declared in the prefs collection) to get disabled state from

Returns: true, if it is disabled, false otherwise

Since: 1.8

◆ elm_obj_prefs_item_swallow()

EOAPI Eina_Bool elm_obj_prefs_item_swallow	(	Eo *	obj,
		const char *	name,
		Efl_Canvas_Object *	child
	)

"Swallows" an object into a SWALLOW item of a prefs widget.

Parameters

[in]	obj	The object.
[in]	name	The name of the SWALLOW item (as declared in the prefs collection)
[in]	child	The object to occupy the item

Returns: true, on success, false otherwise

Since: 1.8

◆ elm_obj_prefs_item_editable_set()

EOAPI void elm_obj_prefs_item_editable_set	(	Eo *	obj,
		const char *	name,
		Eina_Bool	editable
	)

Set whether the widget bound to a given prefs widget's item is editable or not.

Note: Only TEXT or TEXTAREA items' default widgets implement the 'editable' property. Custom registered widgets may as well implement them.

Parameters

[in]	obj	The object.
[in]	name	The name of the item (as declared in the prefs collection) to act on
[in]	editable	`true`, to make it editable, `false` otherwise

Since: 1.8

◆ elm_obj_prefs_item_editable_get()

EOAPI Eina_Bool elm_obj_prefs_item_editable_get	(	const Eo *	obj,
		const char *	name
	)

Get whether the widget bound to a given prefs widget's item is editable or not.

Parameters

[in]	obj	The object.
[in]	name	The name of the item (as declared in the prefs collection) to get editable state from

Returns: true, if it is editable, false otherwise

Since: 1.8

◆ elm_obj_prefs_item_unswallow()

EOAPI Efl_Canvas_Object * elm_obj_prefs_item_unswallow	(	Eo *	obj,
		const char *	name
	)

Unswallow an object from a SWALLOW item of a prefs widget.

Parameters

[in]	obj	The object.
[in]	name	The name of the SWALLOW item (as declared in the prefs collection)

Returns: The unswallowed object, or NULL on errors

Since: 1.8

◆ elm_obj_prefs_item_visible_set()

EOAPI void elm_obj_prefs_item_visible_set	(	Eo *	obj,
		const char *	name,
		Eina_Bool	visible
	)

Set whether the widget bound to given prefs widget's item should be visible or not.

Each prefs item may have a default visibility state, declared on the $.epb prefs it was loaded with. By this call one may alter that state, programmatically.

Parameters

[in]	obj	The object.
[in]	name	The name of the item (as declared in the prefs collection) to change visibility of
[in]	visible	`true`, to make it visible, `false` otherwise

Since: 1.8

◆ elm_obj_prefs_item_visible_get()

EOAPI Eina_Bool elm_obj_prefs_item_visible_get	(	const Eo *	obj,
		const char *	name
	)

Get whether the widget bound to a given prefs widget's item is visible or not.

Parameters

[in]	obj	The object.
[in]	name	The name of the item (as declared in the prefs collection) to get visibility state from

Returns: true, if it is visible, false otherwise

Since: 1.8

◆ elm_prefs_file_set()

Eina_Bool elm_prefs_file_set	(	Eo *	obj,
		const char *	file,
		const char *	page
	)

Set file and page to populate a given prefs widget's interface.

Returns: EINA_TRUE, on success, EINA_FALSE otherwise

Elm prefs widgets start blank, with no child widgets. It's meant to have its viewport populated with child elements coming from a declaration file. That file (usually with .epb extension), is a binary format (Eet) one, coming from a human-readable textual declaration. This textual form (usually with .epc extension) is translated to the binary form by means of the prefs_cc compiler.

With this function, one thus populates a prefs widget with UI elements.

If file is NULL, "elm_app_data_dir_get()/preferences.epb" will be used, by default. If file is a relative path, the prefix "elm_app_data_dir_get()/" will be implicitly used with it. If page is NULL, it is considered "main", as default.

Warning: If your binary is not properly installed and elm_app_data_dir_get() can't be figured out, a fallback value of "." will be tryed, instead.

See also: elm_prefs_file_get()

Since: 1.8

Parameters

[in]	file	The .epb (binary) file to get contents from
[in]	page	The page, inside file, where to get item contents from

Examples: prefs_example_01.c, prefs_example_02.c, and prefs_example_03.c.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, eina_stringshare_add(), eina_stringshare_printf(), EINA_TRUE, elm_app_data_dir_get(), ELM_PREFS_EVENT_PAGE_LOADED, evil_path_is_absolute(), and WRN.

◆ elm_prefs_file_get()

Eina_Bool elm_prefs_file_get	(	const Eo *	obj,
		const char **	file,
		const char **	page
	)

Get file and page bound to a given prefs widget.

Returns: EINA_TRUE, on success, EINA_FALSE otherwise

Note: Use NULL pointers on the components you're not interested in: they'll be ignored by the function.

See also: elm_prefs_file_set() for more information

Since: 1.8

Parameters

[out]	file	The .epb (binary) file to get contents from
[out]	page	The page, inside file, where to get item contents from

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Prefs Data

Prefs

Macro Definition Documentation

◆ ELM_PREFS_EVENT_PAGE_CHANGED

◆ ELM_PREFS_EVENT_PAGE_SAVED

◆ ELM_PREFS_EVENT_PAGE_LOADED

◆ ELM_PREFS_EVENT_ITEM_CHANGED

◆ ELM_PREFS_EVENT_ACTION

Typedef Documentation

◆ Elm_Prefs_Data

◆ Elm_Prefs_Data_Event_Changed

Enumeration Type Documentation

◆ Elm_Prefs_Reset_Mode

◆ Elm_Prefs_Item_Type

◆ Elm_Prefs_Data_Event_Type

Function Documentation

◆ elm_prefs_add()

◆ elm_prefs_item_iface_register()

◆ elm_prefs_item_iface_unregister()

◆ elm_prefs_page_iface_register()

◆ elm_prefs_page_iface_unregister()

◆ elm_prefs_data_new()

◆ elm_prefs_data_version_set()

◆ elm_prefs_data_version_get()

◆ elm_prefs_data_ref()

◆ elm_prefs_data_unref()

◆ elm_prefs_data_value_set()

◆ elm_prefs_data_value_get()

◆ elm_prefs_data_event_callback_add()

◆ elm_prefs_data_event_callback_del()

◆ elm_prefs_data_autosave_set()

◆ elm_prefs_data_autosave_get()

◆ elm_prefs_data_save()

◆ elm_obj_prefs_data_set()

◆ elm_obj_prefs_data_get()

◆ elm_obj_prefs_autosave_set()

◆ elm_obj_prefs_autosave_get()

◆ elm_obj_prefs_reset()

◆ elm_obj_prefs_item_value_set()

◆ elm_obj_prefs_item_value_get()

◆ elm_obj_prefs_item_object_get()

◆ elm_obj_prefs_item_disabled_set()

◆ elm_obj_prefs_item_disabled_get()

◆ elm_obj_prefs_item_swallow()

◆ elm_obj_prefs_item_editable_set()

◆ elm_obj_prefs_item_editable_get()

◆ elm_obj_prefs_item_unswallow()

◆ elm_obj_prefs_item_visible_set()

◆ elm_obj_prefs_item_visible_get()

◆ elm_prefs_file_set()

◆ elm_prefs_file_get()