Prefs Example 01

This example shows how to create a simple prefs widget with Elementary, where the items values are "reset" on each timer tick.

We do that programmatically, to demonstrate that by touching a given prefs widgets prefs data values, the changes reflect instantly on the UI.

We'll create items on the .EPC file and after handle it on the .C file.

# Creating items on EPC file

First we'll create prefs items on .EPC file that we'll use later on the .C file. Note that the code is similar to .EDC (edje) files.

collection
{
page
{
name: "main";
version: 1;
title: "Preferences Widget";
subtitle: "Example 01";

Here we define a page item. Pages are group of items grouped together, on a given prefs widget.

widget: "elm/vertical_box";

In this part, we create a `INT` type item, that by default will become a spinner widget in the UI, and default, min and max parameters are optional as well as in `FLOAT` type.

items {
item {
name: "universe";
type: INT;
label: "Ultimate Answer of Life, the Universe and Everything";
editable: 1;
int {
default: 42;
min: 0;
max: 150;
}
}

Other `INT` type widget implementations may exist, as is exemplified on the item that follows.

item {
name: "another int";
type: INT;
widget: "elm/spinner";
int {
min: 0;
}
}

Now we create a LABEL type item and by default will become a read-only label in UI.

item {
name: "label";
type: LABEL;
label: "Just a label...";
}

Now we create a TEXT type item and by default will become a single-line text entry in UI. Note that we use a Regular Expression to deny only entries with numbers.

item {
name: "text";
type: TEXT;
editable: 1;
text {
placeholder: "This is a text field (:";
default: "default str.";
deny: "^[0-9]*$";
}
}

In this part we create a DATE type item, by default will become a datetime in UI, and default, min and max parameters are optional.

item {
name: "date";
type: DATE;
label: "First EFL Developer Day";
date {
default: 2012 11 05;
min: 1980 11 1;
max: 2200 12 2;
}

Here we create a SEPARATOR type item, it has no value bound, serves only to divide and organize prefs items.

item {
name: "sep";
type: SEPARATOR;
}

In this part, we create a SAVE type item that will get all the values bounded to items and save it on CFG file. Next time you execute the application, all the values that you saved before will be loaded.

item {
name: "save";
type: SAVE;
label: "Save";
}

Here we create a RESET type item that will return all the values bounded to items as default declared on .EPC file.

item {
name: "reset";
type: RESET;
label: "Reset";
}

Pages and items have default implementation widgets, but, with the tag 'widget', you can use different widgets for prefs items. To a list of default widgets supported by each type, by default, refer to the Elementary Prefs Collection reference sheet. One can also register, at run time, custom item widget handlers too.

# Handling items on C File

Now we're handling the .C file and first we'll create a prefs widget.

prefs = elm_prefs_add(win);
evas_object_size_hint_weight_set(prefs, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_win_resize_object_add(win, prefs);
evas_object_show(prefs);
EVAS_HINT_EXPAND
#define EVAS_HINT_EXPAND
Use with evas_object_size_hint_weight_set(), evas_object_size_hint_weight_get(), evas_object_size_hin...
Definition: Evas_Common.h:297
elm_prefs_add
Evas_Object * elm_prefs_add(Evas_Object *parent)
Add a new prefs widget.
Definition: elm_prefs.c:478
elm_win_resize_object_add
void elm_win_resize_object_add(Eo *obj, Evas_Object *subobj)
Add subobj as a resize object of window obj.
Definition: efl_ui_win.c:8992
evas_object_show
EVAS_API void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition: evas_object_main.c:1814
evas_object_size_hint_weight_set
EVAS_API void evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y)
Sets the hints for an object's weight.
Definition: evas_object_main.c:2638

Here we add some specific callbacks, for example "item,changed" that will be called when any item that we created on EPC file changes.

evas_object_smart_callback_add(prefs, "page,saved", _page_saved_cb, NULL);
evas_object_smart_callback_add(prefs, "page,loaded", _page_loaded_cb, NULL);
evas_object_smart_callback_add(prefs, "item,changed", _item_changed_cb, win);
evas_object_smart_callback_add
EVAS_API void evas_object_smart_callback_add(Evas_Object *eo_obj, const char *event, Evas_Smart_Cb func, const void *data)
Add (register) a callback function to the smart event specified by event on the smart object obj.
Definition: evas_object_smart.c:1040

Here we set the prefs to save its values back (on the user data file) automatically on every UI element changes.

elm_prefs_autosave_set(prefs, EINA_TRUE);
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition: eina_types.h:539

In this part we create the prefs data handle and set the .EPB file (.EPC compiled). This .EPB file contains all the default values from the items that we created, this file will be loaded when the program starts or when clicked on a RESET type item. There is another file created when the values from prefs items are saved, the .CFG file, that contains all the non-standard saved values from the prefs items, this file will be loaded when program starts as well.

Elm_Prefs_Data *prefs_data;
Elm_Prefs_Data
struct _Elm_Prefs_Data Elm_Prefs_Data
An Elm Prefs Data handle.
Definition: elm_prefs_data.h:89
prefs_data = elm_prefs_data_new("./prefs_example_01.cfg", NULL,
EET_FILE_MODE_READ_WRITE);
elm_prefs_file_set(prefs, "prefs_example_01.epb", NULL);
elm_prefs_data_set(prefs, prefs_data);
EET_FILE_MODE_READ_WRITE
@ EET_FILE_MODE_READ_WRITE
File is for both read and write.
Definition: Eet.h:481
elm_prefs_data_new
Elm_Prefs_Data * elm_prefs_data_new(const char *data_file, const char *key, Eet_File_Mode mode)
Create a new prefs data handle.
Definition: elm_prefs_data.c:329
elm_prefs_file_set
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.
Definition: elm_prefs.c:1794

Here we just create a notify widget to appear when the values are reset.

label = elm_label_add(win);
elm_object_text_set(label, "Setting Values Programmatically");
evas_object_size_hint_align_set(label, 0.5, 0.5);
notify = elm_notify_add(win);
elm_notify_align_set(notify, 0.5, 1);
elm_notify_timeout_set(notify, 2);
elm_object_content_set(notify, label);
evas_object_size_hint_weight_set(notify, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_show(notify);
elm_label_add
Evas_Object * elm_label_add(Evas_Object *parent)
Add a new label to the parent.
Definition: elm_label.c:421
elm_notify_add
Evas_Object * elm_notify_add(Evas_Object *parent)
Add a new notify to the parent.
Definition: elm_notify.c:478
elm_notify_align_set
void elm_notify_align_set(Elm_Notify *obj, double horizontal, double vertical)
Set the alignment of the notify object.
Definition: elm_notify_eo.legacy.c:3
elm_notify_timeout_set
void elm_notify_timeout_set(Elm_Notify *obj, double timeout)
Set the time interval after which the notify window is going to be hidden.
Definition: elm_notify_eo.legacy.c:27
evas_object_size_hint_align_set
EVAS_API void evas_object_size_hint_align_set(Evas_Object *obj, double x, double y)
Sets the hints for an object's alignment.
Definition: evas_object_main.c:2650

Now we add a timer to reset the items values on each 5.0 seconds and show the notify.

evas_object_data_set(notify, "prefs_data", prefs_data);
evas_object_data_set
EVAS_API void evas_object_data_set(Evas_Object *eo_obj, const char *key, const void *data)
Set an attached data pointer to an object with a given string key.
Definition: evas_data.c:5
_elm_prefs_data_change(void *data)
{
Evas_Object *notify = data;
Elm_Prefs_Data *prefs_data;
Elm_Prefs_Item_Type type;
Eina_Value value;
prefs_data = evas_object_data_get(notify, "prefs_data");
if (elm_prefs_data_value_get(prefs_data, "main:universe", &type, &value))
{
eina_value_set(&value, 42);
elm_prefs_data_value_set(prefs_data, "main:universe", type, &value);
}
if (elm_prefs_data_value_get(prefs_data, "main:text", &type, &value))
{
eina_value_set(&value, "This is a text field (:");
elm_prefs_data_value_set(prefs_data, "main:text", type, &value);
}
evas_object_show(notify);
return ECORE_CALLBACK_RENEW;
ECORE_CALLBACK_RENEW
#define ECORE_CALLBACK_RENEW
Return value to keep a callback.
Definition: Ecore_Common.h:153
eina_value_set
static Eina_Bool eina_value_set(Eina_Value *value,...)
Sets the generic value.
elm_prefs_data_value_get
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).
Definition: elm_prefs_data.c:748
Elm_Prefs_Item_Type
Elm_Prefs_Item_Type
Elm Prefs item types.
Definition: elm_prefs_data.h:51
elm_prefs_data_value_set
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.
Definition: elm_prefs_data.c:660
evas_object_data_get
EVAS_API void * evas_object_data_get(const Evas_Object *obj, const char *key)
Return an attached data pointer on an Evas object by its given string key.
Definition: evas_data.c:12
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition: Evas_Common.h:185
_Eina_Value
defines the contents of a value
Definition: eina_value.h:662
}

Here we finish the example. The full source code can be found on prefs_example_01.c and prefs_example_01.epc