Elementary Prefs

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

Typedefs | Enumerations | Functions
Elementary Prefs

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

## Typedefs
typedef enum _Elm_Prefs_Item_Type | Elm_Prefs_Item_Type
| Elm Prefs item types. More...
typedef struct _Elm_Prefs_Data | Elm_Prefs_Data
| An Elm Prefs Data handle. More...
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_Item_Type { , 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_ITEM_CHANGED, ELM_PREFS_DATA_EVENT_LAST }
| Types of events a given prefs data handle may issue. More...

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

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

## Typedef Documentation

Elm_Prefs_Data

An Elm Prefs Data handle.

Since
  1.8

Elm_Prefs_Data_Event_Changed

An Elm Prefs ELM_PREFS_DATA_EVENT_ITEM_CHANGED event info data blob.

Since
  1.8

typedef enum _Elm_Prefs_Item_Type Elm_Prefs_Item_Type

Elm Prefs item types.

Since
  1.8

## Enumeration Type Documentation

enum _Elm_Prefs_Item_Type

Elm Prefs item types.

Since
  1.8

Enumerator
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

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

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

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

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

References ELM_PREFS_DATA_EVENT_LAST.

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

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

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

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

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

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

References ELM_PREFS_DATA_EVENT_ITEM_CHANGED.

unsigned int elm_prefs_data_version_get | ( | 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

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