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

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

Enumerations
enum	Elm_Prefs_Reset_Mode { ELM_PREFS_RESET_DEFAULTS, ELM_PREFS_RESET_LAST }
	Modes of resetting a prefs widget. 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...

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

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

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 minumum 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 an 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")

Elementary Prefs Data Collection Reference

The following are examples on how to use prefs:

Enumeration Type Documentation

enum Elm_Prefs_Reset_Mode

Modes of resetting a prefs widget.

See also: 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

Function Documentation

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

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

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.

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, _Elm_Prefs_Item_Iface_Info::info, _Elm_Prefs_Item_Iface::types, and _Elm_Prefs_Item_Iface_Info::widget_name.

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 _Elm_Prefs_Item_Iface_Info::info, _Elm_Prefs_Item_Iface::types, and _Elm_Prefs_Item_Iface_Info::widget_name.

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, _Elm_Prefs_Page_Iface_Info::info, and _Elm_Prefs_Page_Iface_Info::widget_name.

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 _Elm_Prefs_Page_Iface_Info::info, and _Elm_Prefs_Page_Iface_Info::widget_name.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Prefs

Enumeration Type Documentation

Function Documentation