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

Prefs

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)
| Retrieve 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

## Function Documentation

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

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