Elementary provides a prefs (for "preferences") infrastructure, which consists of two sets of APIs: More...
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... | |
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 void(* | Elm_Prefs_Item_Changed_Cb) (Evas_Object *it_obj) |
Elementary prefs' item widget changed function signature. | |
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_Reset_Mode { ELM_PREFS_RESET_DEFAULTS, ELM_PREFS_RESET_LAST } |
Modes of resetting a prefs widget. More... | |
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_Data * | elm_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_Data * | elm_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... | |
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... | |
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 (const 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... | |
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... | |
Elementary provides a prefs (for "preferences") infrastructure, which consists of two sets of APIs:
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.
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:
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"
)The following are examples on how to use prefs:
An Elm Prefs Data handle.
An Elm Prefs ELM_PREFS_DATA_EVENT_ITEM_CHANGED event info data blob.
typedef enum _Elm_Prefs_Item_Type Elm_Prefs_Item_Type |
Elm Prefs item types.
enum _Elm_Prefs_Item_Type |
Elm Prefs item types.
Types of events a given prefs data handle may issue.
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 |
enum Elm_Prefs_Reset_Mode |
Modes of resetting a prefs widget.
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.
true
to save automatically, false
otherwise.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.
[in] | autosave | true to save automatically, false otherwise. |
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().
obj
will keep a reference of its own for prefs_data
, but you should still unreference it by yourself, after the widget is gone.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().
obj
will keep a reference of its own for prefs_data
, but you should still unreference it by yourself, after the widget is gone.[in] | data | A valid prefs_data handle |
true
, on success, false
otherwiseReferenced 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.
[in] | name | The name of the item (as declared in the prefs collection) to get disabled state from |
true
, if it is disabled, false
otherwiseReferenced 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.
[in] | disabled | true , to make it disabled, false otherwise |
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.
[in] | name | The name of the item (as declared in the prefs collection) to get editable state from |
true
, if it is editable, false
otherwiseReferenced 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.
TEXT
or TEXTAREA
items' default widgets implement the 'editable' property. Custom registered widgets may as well implement them.[in] | editable | true , to make it editable, false otherwise |
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.
prefs
, solely.[in] | name | The name of the item (as declared in the prefs collection) to get object from |
NULL
, otherwiseReferenced 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.
[in] | child | The object to occupy the item |
true
, on success, false
otherwiseReferenced 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.
[in] | name | the name of the SWALLOW item (as declared in the prefs collection) |
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
.
[out] | value | Where to store the value of the item. It will be overwritten and setup with the type the item is bound to |
true
, on success, false
otherwiseReferenced 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.
[in] | value | The value to set on the item. It should be typed as the item expects, preferably, or a conversion will take place |
true
, on success, false
otherwiseReferenced 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.
[in] | name | The name of the item (as declared in the prefs collection) to get visibility state from |
true
, if it is visible, false
otherwiseReferenced 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.
[in] | visible | true , to make it visible, false otherwise |
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.
[in] | mode | The reset mode to apply on prefs |
Referenced by elm_prefs_reset().
Evas_Object* elm_prefs_add | ( | Evas_Object * | parent | ) |
Add a new prefs widget.
parent | The parent widget to hold the new one |
NULL
, on errorsEina_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.
true
to save automatically, false
otherwise.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.
[in] | autosave | true to save automatically, false otherwise. |
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.
prefs_data | A valid prefs data handle |
EINA_TRUE
if prefs_data is saving automatically, EINA_FALSE
otherwise.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.
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.
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.
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 |
EINA_TRUE
on success, EINA_FALSE
otherwiseReferences 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.
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 |
EINA_TRUE
on success, EINA_FALSE
otherwiseElm_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().
obj
will keep a reference of its own for prefs_data
, but you should still unreference it by yourself, after the widget is gone.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.
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 |
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.
Elm_Prefs_Data* elm_prefs_data_ref | ( | Elm_Prefs_Data * | prefs_data | ) |
Increment reference count on a given prefs data handle.
prefs_data | A valid prefs data handle |
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.
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.
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) |
EINA_TRUE
on success, EINA_FALSE
otherwise.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().
obj
will keep a reference of its own for prefs_data
, but you should still unreference it by yourself, after the widget is gone.[in] | data | A valid prefs_data handle |
true
, on success, false
otherwiseReferences elm_obj_prefs_data_set().
void elm_prefs_data_unref | ( | Elm_Prefs_Data * | prefs_data | ) |
Decrement reference count on a given prefs data handle.
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.
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).
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. |
EINA_TRUE
on success, EINA_FALSE
otherwiseThis will retrieve one of 's values, by name. The value itself will be written to value, which will be overriden.
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.
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. |
EINA_TRUE
on success, EINA_FALSE
otherwiseA 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.
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.
prefs_data | A valid prefs data handle |
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.
prefs_data | A valid prefs data handle |
version | The version number |
EINA_TRUE
on success, EINA_FALSE
otherwiseEina_Bool elm_prefs_file_get | ( | const Eo * | obj, |
const char ** | file, | ||
const char ** | page | ||
) |
Get file and page bound to a given prefs widget.
EINA_TRUE
, on success, EINA_FALSE
otherwiseNULL
pointers on the components you're not interested in: they'll be ignored by the function.[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.
EINA_TRUE
, on success, EINA_FALSE
otherwiseElm 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.
[in] | file | The .epb (binary) file to get contents from |
[in] | page | The page, inside file, where to get item contents from |
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.
[in] | name | The name of the item (as declared in the prefs collection) to get disabled state from |
true
, if it is disabled, false
otherwiseReferences 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.
[in] | disabled | true , to make it disabled, false otherwise |
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.
[in] | name | The name of the item (as declared in the prefs collection) to get editable state from |
true
, if it is editable, false
otherwiseReferences 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.
TEXT
or TEXTAREA
items' default widgets implement the 'editable' property. Custom registered widgets may as well implement them.[in] | editable | true , to make it editable, false otherwise |
References elm_obj_prefs_item_editable_set().
void elm_prefs_item_iface_register | ( | const Elm_Prefs_Item_Iface_Info * | array | ) |
Mass-register widgets implementing prefs items interfaces.
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.
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.
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.
References _Elm_Prefs_Item_Iface_Info::info, _Elm_Prefs_Item_Iface::types, and _Elm_Prefs_Item_Iface_Info::widget_name.
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.
prefs
, solely.[in] | name | The name of the item (as declared in the prefs collection) to get object from |
NULL
, otherwiseReferences 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.
[in] | child | The object to occupy the item |
true
, on success, false
otherwiseReferences 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.
[in] | name | the name of the SWALLOW item (as declared in the prefs collection) |
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
.
[out] | value | Where to store the value of the item. It will be overwritten and setup with the type the item is bound to |
true
, on success, false
otherwiseReferences 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.
[in] | value | The value to set on the item. It should be typed as the item expects, preferably, or a conversion will take place |
true
, on success, false
otherwiseReferences 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.
[in] | name | The name of the item (as declared in the prefs collection) to get visibility state from |
true
, if it is visible, false
otherwiseReferences 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.
[in] | visible | true , to make it visible, false otherwise |
References elm_obj_prefs_item_visible_set().
void elm_prefs_page_iface_register | ( | const Elm_Prefs_Page_Iface_Info * | array | ) |
Mass-register widgets implementing prefs pages interfaces.
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.
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.
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.
References _Elm_Prefs_Page_Iface_Info::info, and _Elm_Prefs_Page_Iface_Info::widget_name.
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.
[in] | mode | The reset mode to apply on prefs |
References elm_obj_prefs_reset().