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

Prefs

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