Macros | Typedefs | Enumerations | Functions
Elementary Prefs

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

Macros

#define ELM_PREFS_EVENT_PAGE_CHANGED   (&(_ELM_PREFS_EVENT_PAGE_CHANGED))
 s
 
#define ELM_PREFS_EVENT_PAGE_SAVED   (&(_ELM_PREFS_EVENT_PAGE_SAVED))
 s
 
#define ELM_PREFS_EVENT_PAGE_RESET   (&(_ELM_PREFS_EVENT_PAGE_RESET))
 s
 
#define ELM_PREFS_EVENT_PAGE_LOADED   (&(_ELM_PREFS_EVENT_PAGE_LOADED))
 s
 
#define ELM_PREFS_EVENT_ITEM_CHANGED   (&(_ELM_PREFS_EVENT_ITEM_CHANGED))
 s
 
#define ELM_PREFS_EVENT_ACTION   (&(_ELM_PREFS_EVENT_ACTION))
 ss
 

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

EOAPI Eina_Bool elm_obj_prefs_data_set (Elm_Prefs_Data *data)
 Set user data for a given prefs widget. More...
 
EOAPI Elm_Prefs_Dataelm_obj_prefs_data_get (void)
 Set user data for a given prefs widget. More...
 
EOAPI void elm_obj_prefs_autosave_set (Eina_Bool autosave)
 Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes. More...
 
EOAPI Eina_Bool elm_obj_prefs_autosave_get (void)
 Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes. More...
 
EOAPI void elm_obj_prefs_reset (Elm_Prefs_Reset_Mode mode)
 Reset the values of a given prefs widget to a previous state. More...
 
EOAPI Eina_Bool elm_obj_prefs_item_value_set (const char *name, const Eina_Value *value)
 Set the value on a given prefs widget's item. More...
 
EOAPI Eina_Bool elm_obj_prefs_item_value_get (const char *name, Eina_Value *value)
 Get the value of a given prefs widget's item. More...
 
EOAPI const Evas_Object * elm_obj_prefs_item_object_get (const char *name)
 Get the Elementary widget bound to a given prefs widget's item. More...
 
EOAPI void elm_obj_prefs_item_disabled_set (const char *name, Eina_Bool disabled)
 Set whether the widget bound to a given prefs widget's item is disabled or not. More...
 
EOAPI Eina_Bool elm_obj_prefs_item_disabled_get (const char *name)
 Get whether the widget bound to a given prefs widget's item is disabled or not. More...
 
EOAPI Eina_Bool elm_obj_prefs_item_swallow (const char *name, Evas_Object *child)
 "Swallows" an object into a SWALLOW item of a prefs widget. More...
 
EOAPI void elm_obj_prefs_item_editable_set (const char *name, Eina_Bool editable)
 Set whether the widget bound to a given prefs widget's item is editable or not. More...
 
EOAPI Eina_Bool elm_obj_prefs_item_editable_get (const char *name)
 Get whether the widget bound to a given prefs widget's item is editable or not. More...
 
EOAPI Evas_Object * elm_obj_prefs_item_unswallow (const char *name)
 Unswallow an object from a SWALLOW item of a prefs widget. More...
 
EOAPI void elm_obj_prefs_item_visible_set (const char *name, Eina_Bool visible)
 Set whether the widget bound to given prefs widget's item should be visible or not. More...
 
EOAPI Eina_Bool elm_obj_prefs_item_visible_get (const char *name)
 Get whether the widget bound to a given prefs widget's item is visible or not. More...
 
Eina_Bool elm_prefs_data_set (Elm_Prefs *obj, Elm_Prefs_Data *data)
 Set user data for a given prefs widget. More...
 
Elm_Prefs_Dataelm_prefs_data_get (const Elm_Prefs *obj)
 Set user data for a given prefs widget. More...
 
void elm_prefs_autosave_set (Elm_Prefs *obj, Eina_Bool autosave)
 Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes. More...
 
Eina_Bool elm_prefs_autosave_get (const Elm_Prefs *obj)
 Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes. More...
 
void elm_prefs_reset (Elm_Prefs *obj, Elm_Prefs_Reset_Mode mode)
 Reset the values of a given prefs widget to a previous state. More...
 
Eina_Bool elm_prefs_item_value_set (Elm_Prefs *obj, const char *name, const Eina_Value *value)
 Set the value on a given prefs widget's item. More...
 
Eina_Bool elm_prefs_item_value_get (const Elm_Prefs *obj, const char *name, Eina_Value *value)
 Get the value of a given prefs widget's item. More...
 
const Evas_Object * elm_prefs_item_object_get (Elm_Prefs *obj, const char *name)
 Get the Elementary widget bound to a given prefs widget's item. More...
 
void elm_prefs_item_disabled_set (Elm_Prefs *obj, const char *name, Eina_Bool disabled)
 Set whether the widget bound to a given prefs widget's item is disabled or not. More...
 
Eina_Bool elm_prefs_item_disabled_get (const Elm_Prefs *obj, const char *name)
 Get whether the widget bound to a given prefs widget's item is disabled or not. More...
 
Eina_Bool elm_prefs_item_swallow (Elm_Prefs *obj, const char *name, Evas_Object *child)
 "Swallows" an object into a SWALLOW item of a prefs widget. More...
 
void elm_prefs_item_editable_set (Elm_Prefs *obj, const char *name, Eina_Bool editable)
 Set whether the widget bound to a given prefs widget's item is editable or not. More...
 
Eina_Bool elm_prefs_item_editable_get (const Elm_Prefs *obj, const char *name)
 Get whether the widget bound to a given prefs widget's item is editable or not. More...
 
Evas_Object * elm_prefs_item_unswallow (Elm_Prefs *obj, const char *name)
 Unswallow an object from a SWALLOW item of a prefs widget. More...
 
void elm_prefs_item_visible_set (Elm_Prefs *obj, const char *name, Eina_Bool visible)
 Set whether the widget bound to given prefs widget's item should be visible or not. More...
 
Eina_Bool elm_prefs_item_visible_get (const Elm_Prefs *obj, const char *name)
 Get whether the widget bound to a given prefs widget's item is visible or not. More...
 
Elm_Prefs_Dataelm_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 (const Elm_Prefs_Data *prefs_data)
 Get the version field of a given prefs data handle. More...
 
Elm_Prefs_Dataelm_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

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

An Elm Prefs Data handle.

Since
1.8

An Elm Prefs ELM_PREFS_DATA_EVENT_ITEM_CHANGED event info data blob.

Since
1.8

Elm Prefs item types.

Since
1.8

Enumeration Type Documentation

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

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

EOAPI Eina_Bool elm_obj_prefs_autosave_get ( void  )

Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes.

If autosave is true, every call to elm_prefs_item_value_set(), every Elm_Prefs_Data_Event_Type.ELM_PREFS_DATA_EVENT_ITEM_CHANGED event coming for its prefs data and every UI element direct value changing will implicitly make the prefs values to be flushed back to it prefs data. If a prefs data handle with no writing permissions or no prefs data is set on prefs, naturally nothing will happen.

Returns
true to save automatically, false otherwise.
Since
1.8

Referenced by elm_prefs_autosave_get().

EOAPI void elm_obj_prefs_autosave_set ( Eina_Bool  autosave)

Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes.

If autosave is true, every call to elm_prefs_item_value_set(), every Elm_Prefs_Data_Event_Type.ELM_PREFS_DATA_EVENT_ITEM_CHANGED event coming for its prefs data and every UI element direct value changing will implicitly make the prefs values to be flushed back to it prefs data. If a prefs data handle with no writing permissions or no prefs data is set on prefs, naturally nothing will happen.

Parameters
[in]autosavetrue to save automatically, false otherwise.
Since
1.8

Referenced by elm_prefs_autosave_set().

EOAPI Elm_Prefs_Data* elm_obj_prefs_data_get ( void  )

Set user data for a given prefs widget.

Once a prefs widget is created, after elm_prefs_file_set() is issued on it, all of its UI elements will get default values, when declared on that file. To fetch an user's own, personal set of those values, one gets to pair a prefs data handle to the prefs widget. This is what this call is intended for.

Prefs data values from prefs_data with keys matching the ones present on the file passed on elm_prefs_file_set() to obj will have their values applied to the respective UI elements of the widget.

When obj dies, the values of the elements declared on its .epb file (the one set on elm_prefs_file_set()) marked as permanent will be written back to prefs_data, 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().

Note
obj will keep a reference of its own for prefs_data, but you should still unreference it by yourself, after the widget is gone.
Returns
A valid prefs_data handle
Since
1.8

Referenced by elm_prefs_data_get().

EOAPI Eina_Bool elm_obj_prefs_data_set ( Elm_Prefs_Data data)

Set user data for a given prefs widget.

Once a prefs widget is created, after elm_prefs_file_set() is issued on it, all of its UI elements will get default values, when declared on that file. To fetch an user's own, personal set of those values, one gets to pair a prefs data handle to the prefs widget. This is what this call is intended for.

Prefs data values from prefs_data with keys matching the ones present on the file passed on elm_prefs_file_set() to obj will have their values applied to the respective UI elements of the widget.

When obj dies, the values of the elements declared on its .epb file (the one set on elm_prefs_file_set()) marked as permanent will be written back to prefs_data, 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().

Note
obj will keep a reference of its own for prefs_data, but you should still unreference it by yourself, after the widget is gone.
Parameters
[in]dataA valid prefs_data handle
Returns
true, on success, false otherwise
Since
1.8

Referenced by elm_prefs_data_set().

EOAPI Eina_Bool elm_obj_prefs_item_disabled_get ( const char *  name)

Get whether the widget bound to a given prefs widget's item is disabled or not.

Parameters
[in]nameThe name of the item (as declared in the prefs collection) to get disabled state from
Returns
true, if it is disabled, false otherwise
Since
1.8

Referenced by elm_prefs_item_disabled_get().

EOAPI void elm_obj_prefs_item_disabled_set ( const char *  name,
Eina_Bool  disabled 
)

Set whether the widget bound to a given prefs widget's item is disabled or not.

Parameters
[in]disabledtrue, to make it disabled, false otherwise
Since
1.8

Referenced by elm_prefs_item_disabled_set().

EOAPI Eina_Bool elm_obj_prefs_item_editable_get ( const char *  name)

Get whether the widget bound to a given prefs widget's item is editable or not.

Parameters
[in]nameThe name of the item (as declared in the prefs collection) to get editable state from
Returns
true, if it is editable, false otherwise
Since
1.8

Referenced by elm_prefs_item_editable_get().

EOAPI void elm_obj_prefs_item_editable_set ( const char *  name,
Eina_Bool  editable 
)

Set whether the widget bound to a given prefs widget's item is editable or not.

Note
Only TEXT or TEXTAREA items' default widgets implement the 'editable' property. Custom registered widgets may as well implement them.
Parameters
[in]editabletrue, to make it editable, false otherwise
Since
1.8

Referenced by elm_prefs_item_editable_set().

EOAPI const Evas_Object* elm_obj_prefs_item_object_get ( const char *  name)

Get the Elementary widget bound to a given prefs widget's item.

This will retrieve a handle to the real widget implementing a given item of prefs, for read-only actions.

Warning
You should never modify the state of the returned widget, because it's meant to be managed by prefs, solely.
Parameters
[in]nameThe name of the item (as declared in the prefs collection) to get object from
Returns
A valid widget handle, on success, or NULL, otherwise
Since
1.8

Referenced by elm_prefs_item_object_get().

EOAPI Eina_Bool elm_obj_prefs_item_swallow ( const char *  name,
Evas_Object *  child 
)

"Swallows" an object into a SWALLOW item of a prefs widget.

Parameters
[in]childThe object to occupy the item
Returns
true, on success, false otherwise
Since
1.8

Referenced by elm_prefs_item_swallow().

EOAPI Evas_Object* elm_obj_prefs_item_unswallow ( const char *  name)

Unswallow an object from a SWALLOW item of a prefs widget.

Parameters
[in]namethe name of the SWALLOW item (as declared in the prefs collection)
Returns
The unswallowed object, or NULL on errors
Since
1.8

Referenced by elm_prefs_item_unswallow().

EOAPI Eina_Bool elm_obj_prefs_item_value_get ( const char *  name,
Eina_Value *  value 
)

Get the value of a given prefs widget's item.

This will retrieve the value of item named name.

Parameters
[out]valueWhere to store the value of the item. It will be overwritten and setup with the type the item is bound to
Returns
true, on success, false otherwise
Since
1.8

Referenced by elm_prefs_item_value_get().

EOAPI Eina_Bool elm_obj_prefs_item_value_set ( const char *  name,
const Eina_Value *  value 
)

Set the value on a given prefs widget's item.

This will change the value of item named name programatically.

Parameters
[in]valueThe value to set on the item. It should be typed as the item expects, preferably, or a conversion will take place
Returns
true, on success, false otherwise
Since
1.8

Referenced by elm_prefs_item_value_set().

EOAPI Eina_Bool elm_obj_prefs_item_visible_get ( const char *  name)

Get whether the widget bound to a given prefs widget's item is visible or not.

Parameters
[in]nameThe name of the item (as declared in the prefs collection) to get visibility state from
Returns
true, if it is visible, false otherwise
Since
1.8

Referenced by elm_prefs_item_visible_get().

EOAPI void elm_obj_prefs_item_visible_set ( const char *  name,
Eina_Bool  visible 
)

Set whether the widget bound to given prefs widget's item should be visible or not.

Each prefs item may have a default visibility state, declared on the $.epb prefs it was loaded with. By this call one may alter that state, programatically.

Parameters
[in]visibletrue, to make it visible, false otherwise
Since
1.8

Referenced by elm_prefs_item_visible_set().

EOAPI void elm_obj_prefs_reset ( Elm_Prefs_Reset_Mode  mode)

Reset the values of a given prefs widget to a previous state.

As can be seen on Elm_Prefs_Reset_Mode, there are two possible actions to be taken by this call – either to reset prefs' values to the defaults (declared on the $.epb file it is bound to) or to reset to the state they were before the last modification it got.

Parameters
[in]modeThe reset mode to apply on prefs
Since
1.8

Referenced by elm_prefs_reset().

Eina_Bool elm_prefs_autosave_get ( const Elm_Prefs *  obj)

Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes.

If autosave is true, every call to elm_prefs_item_value_set(), every Elm_Prefs_Data_Event_Type.ELM_PREFS_DATA_EVENT_ITEM_CHANGED event coming for its prefs data and every UI element direct value changing will implicitly make the prefs values to be flushed back to it prefs data. If a prefs data handle with no writing permissions or no prefs data is set on prefs, naturally nothing will happen.

Returns
true to save automatically, false otherwise.
Since
1.8

References elm_obj_prefs_autosave_get().

void elm_prefs_autosave_set ( Elm_Prefs *  obj,
Eina_Bool  autosave 
)

Control whether a given prefs widget should save its values back (on the user data file, if set) automatically on every UI element changes.

If autosave is true, every call to elm_prefs_item_value_set(), every Elm_Prefs_Data_Event_Type.ELM_PREFS_DATA_EVENT_ITEM_CHANGED event coming for its prefs data and every UI element direct value changing will implicitly make the prefs values to be flushed back to it prefs data. If a prefs data handle with no writing permissions or no prefs data is set on prefs, naturally nothing will happen.

Parameters
[in]autosavetrue to save automatically, false otherwise.
Since
1.8

References elm_obj_prefs_autosave_set().

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_dataA 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_dataA valid prefs data handle
autosaveEINA_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_dataA valid prefs data handle
typeThe type of event to register to
cbThe callback function to issue on this event
cb_dataThe 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_dataA valid prefs data handle
typeThe type of event to unregister
cbThe callback function being used to this event
cb_dataThe 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_get ( const Elm_Prefs *  obj)

Set user data for a given prefs widget.

Once a prefs widget is created, after elm_prefs_file_set() is issued on it, all of its UI elements will get default values, when declared on that file. To fetch an user's own, personal set of those values, one gets to pair a prefs data handle to the prefs widget. This is what this call is intended for.

Prefs data values from prefs_data with keys matching the ones present on the file passed on elm_prefs_file_set() to obj will have their values applied to the respective UI elements of the widget.

When obj dies, the values of the elements declared on its .epb file (the one set on elm_prefs_file_set()) marked as permanent will be written back to prefs_data, 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().

Note
obj will keep a reference of its own for prefs_data, but you should still unreference it by yourself, after the widget is gone.
Returns
A valid prefs_data handle
Since
1.8

References elm_obj_prefs_data_get().

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_fileThe (user) file where to read data from
keyThe key where the data is stored under
modeThe 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_dataA 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_dataA valid prefs data handle
fileThe file (path) to save to (NULL means same file as it was opened with)
keyThe 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
Eina_Bool elm_prefs_data_set ( Elm_Prefs *  obj,
Elm_Prefs_Data data 
)

Set user data for a given prefs widget.

Once a prefs widget is created, after elm_prefs_file_set() is issued on it, all of its UI elements will get default values, when declared on that file. To fetch an user's own, personal set of those values, one gets to pair a prefs data handle to the prefs widget. This is what this call is intended for.

Prefs data values from prefs_data with keys matching the ones present on the file passed on elm_prefs_file_set() to obj will have their values applied to the respective UI elements of the widget.

When obj dies, the values of the elements declared on its .epb file (the one set on elm_prefs_file_set()) marked as permanent will be written back to prefs_data, 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().

Note
obj will keep a reference of its own for prefs_data, but you should still unreference it by yourself, after the widget is gone.
Parameters
[in]dataA valid prefs_data handle
Returns
true, on success, false otherwise
Since
1.8

References elm_obj_prefs_data_set().

void elm_prefs_data_unref ( Elm_Prefs_Data prefs_data)

Decrement reference count on a given prefs data handle.

Parameters
prefs_dataA 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_dataA valid prefs data handle
pathThe (unique) name (key) of the given value
typeThe item type associated with the value
valueA 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_dataA valid prefs data handle
pathThe (unique) name (key) of the given value
typeThe item type to which the value is to be associated
valueThe 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 ( const Elm_Prefs_Data prefs_data)

Get the version field of a given prefs data handle.

Parameters
prefs_dataA 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_dataA valid prefs data handle
versionThe version number
Returns
EINA_TRUE on success, EINA_FALSE otherwise
See also
elm_prefs_data_version_get()
Since
1.8
Eina_Bool elm_prefs_item_disabled_get ( const Elm_Prefs *  obj,
const char *  name 
)

Get whether the widget bound to a given prefs widget's item is disabled or not.

Parameters
[in]nameThe name of the item (as declared in the prefs collection) to get disabled state from
Returns
true, if it is disabled, false otherwise
Since
1.8

References elm_obj_prefs_item_disabled_get().

void elm_prefs_item_disabled_set ( Elm_Prefs *  obj,
const char *  name,
Eina_Bool  disabled 
)

Set whether the widget bound to a given prefs widget's item is disabled or not.

Parameters
[in]disabledtrue, to make it disabled, false otherwise
Since
1.8

References elm_obj_prefs_item_disabled_set().

Eina_Bool elm_prefs_item_editable_get ( const Elm_Prefs *  obj,
const char *  name 
)

Get whether the widget bound to a given prefs widget's item is editable or not.

Parameters
[in]nameThe name of the item (as declared in the prefs collection) to get editable state from
Returns
true, if it is editable, false otherwise
Since
1.8

References elm_obj_prefs_item_editable_get().

void elm_prefs_item_editable_set ( Elm_Prefs *  obj,
const char *  name,
Eina_Bool  editable 
)

Set whether the widget bound to a given prefs widget's item is editable or not.

Note
Only TEXT or TEXTAREA items' default widgets implement the 'editable' property. Custom registered widgets may as well implement them.
Parameters
[in]editabletrue, to make it editable, false otherwise
Since
1.8

References elm_obj_prefs_item_editable_set().

const Evas_Object* elm_prefs_item_object_get ( Elm_Prefs *  obj,
const char *  name 
)

Get the Elementary widget bound to a given prefs widget's item.

This will retrieve a handle to the real widget implementing a given item of prefs, for read-only actions.

Warning
You should never modify the state of the returned widget, because it's meant to be managed by prefs, solely.
Parameters
[in]nameThe name of the item (as declared in the prefs collection) to get object from
Returns
A valid widget handle, on success, or NULL, otherwise
Since
1.8

References elm_obj_prefs_item_object_get().

Eina_Bool elm_prefs_item_swallow ( Elm_Prefs *  obj,
const char *  name,
Evas_Object *  child 
)

"Swallows" an object into a SWALLOW item of a prefs widget.

Parameters
[in]childThe object to occupy the item
Returns
true, on success, false otherwise
Since
1.8

References elm_obj_prefs_item_swallow().

Evas_Object* elm_prefs_item_unswallow ( Elm_Prefs *  obj,
const char *  name 
)

Unswallow an object from a SWALLOW item of a prefs widget.

Parameters
[in]namethe name of the SWALLOW item (as declared in the prefs collection)
Returns
The unswallowed object, or NULL on errors
Since
1.8

References elm_obj_prefs_item_unswallow().

Eina_Bool elm_prefs_item_value_get ( const Elm_Prefs *  obj,
const char *  name,
Eina_Value *  value 
)

Get the value of a given prefs widget's item.

This will retrieve the value of item named name.

Parameters
[out]valueWhere to store the value of the item. It will be overwritten and setup with the type the item is bound to
Returns
true, on success, false otherwise
Since
1.8

References elm_obj_prefs_item_value_get().

Eina_Bool elm_prefs_item_value_set ( Elm_Prefs *  obj,
const char *  name,
const Eina_Value *  value 
)

Set the value on a given prefs widget's item.

This will change the value of item named name programatically.

Parameters
[in]valueThe value to set on the item. It should be typed as the item expects, preferably, or a conversion will take place
Returns
true, on success, false otherwise
Since
1.8

References elm_obj_prefs_item_value_set().

Eina_Bool elm_prefs_item_visible_get ( const Elm_Prefs *  obj,
const char *  name 
)

Get whether the widget bound to a given prefs widget's item is visible or not.

Parameters
[in]nameThe name of the item (as declared in the prefs collection) to get visibility state from
Returns
true, if it is visible, false otherwise
Since
1.8

References elm_obj_prefs_item_visible_get().

void elm_prefs_item_visible_set ( Elm_Prefs *  obj,
const char *  name,
Eina_Bool  visible 
)

Set whether the widget bound to given prefs widget's item should be visible or not.

Each prefs item may have a default visibility state, declared on the $.epb prefs it was loaded with. By this call one may alter that state, programatically.

Parameters
[in]visibletrue, to make it visible, false otherwise
Since
1.8

References elm_obj_prefs_item_visible_set().

void elm_prefs_reset ( Elm_Prefs *  obj,
Elm_Prefs_Reset_Mode  mode 
)

Reset the values of a given prefs widget to a previous state.

As can be seen on Elm_Prefs_Reset_Mode, there are two possible actions to be taken by this call – either to reset prefs' values to the defaults (declared on the $.epb file it is bound to) or to reset to the state they were before the last modification it got.

Parameters
[in]modeThe reset mode to apply on prefs
Since
1.8

References elm_obj_prefs_reset().