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:9002
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

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_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_add
Evas_Object * elm_notify_add(Evas_Object *parent)
Add a new notify to the parent.
Definition elm_notify.c:478
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
struct _Eina_Value Eina_Value
Store generic values.
Definition eina_value.h:307
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
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition Evas_Common.h:185
}

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