Prefs

- Main Page
- Related Pages
- Data Structures
- Files
- Examples

Data Structures | Typedefs | Enumerations | Functions
Prefs

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

- Prefs Example 01
- Prefs Example 02
- Prefs Example 03

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