Prefs Example 03

This example shows how to create a prefs widget with Elementary, where some prefs item values are changed, some actions take place on an object different than the prefs widget (an Edge object). With this new object, we're also exemplifying the prefs SWALLOW item type, as the Edje object is put inside the prefs widget's viewport.

It also shows how subpages can be created using the prefs PAGE item type.

Explain step by step the .EDC file is out of scope, the source code can be found at prefs_example_03.edc

Creating items on EPC file

First we'll create prefs items on .EPC file that we'll use later on the .C file.

collection
{
page
{
name: "main";
version: 1;
title: "Preferences Widget";
subtitle: "Example 03";
widget: "elm/vertical_frame";

In the following part, we create an item of the PAGE type, that will create a subpage inside the main page. The source parameter is used to set which page will be used to fill the subpage, in this example, the page named "configpage" will be used.

items {
item {
name: "config";
type: PAGE;
source: "configpage";
}
item {
name: "sep";
type: SEPARATOR;
}

Now we create a SWALLOW type item, that, as the name suggests, will swallow an Evas_Object.

item {
name: "swal";
type: SWALLOW;
}

Now we create the page that will be used to fill the item "config" of the main page. It has another two subpages and a SEPARATOR item arranged horizontally so we could achieve the desired layout.

page
{
name: "configpage";
version: 1;
title: "Preferences";
widget: "elm/horizontal_box";
items {
item {
name: "options";
type: PAGE;
source: "optionspage";
}
item {
name: "sep2";
type: SEPARATOR;
}
item {
name: "buttons";
type: PAGE;
source: "buttonspage";
}
}
}

Then we create the pages used by the "configpage" page, whose items were covered in Prefs Example 01 and Prefs Example 02.

page
{
name: "optionspage";
version: 1;
title: "Options";
widget: "elm/vertical_box";
items {
item {
name: "animation";
type: BOOL;
persistent: 1;
label: "Animation";
bool {
default: true;
}
}
item {
name: "animation_time";
type: FLOAT;
persistent: 1;
label: "Animation Time";
float {
default: 0.6;
min: 0.0;
max: 1.0;
}
}
}
}
page
{
name: "buttonspage";
version: 1;
title: "Actions";
widget: "elm/vertical_box";
items {
item {
name: "save";
type: SAVE;
label: "Save";
}
item {
name: "reset";
type: RESET;
label: "Reset";
}
}
}

Handling items on C File

Now we're handling the .C file and first we'll create a layout setting the edje file to after a prefs item swallows it.

layout = elm_layout_add(win);
elm_layout_file_set(layout, "prefs_example_03.edj", "prefs_edje");

Here we create the prefs widget, add smart callbacks and create the prefs data handle.

prefs = elm_prefs_add(win);
evas_object_resize(prefs, WIDTH, HEIGHT);
evas_object_smart_callback_add(prefs, "page,loaded", _page_loaded_cb,
layout);
evas_object_smart_callback_add(prefs, "item,changed", _item_changed_cb,
layout);
elm_prefs_autosave_set(prefs, EINA_TRUE);
prefs_data =
elm_prefs_data_new("./prefs_example_03.cfg", NULL, EET_FILE_MODE_READ_WRITE);
elm_prefs_file_set(prefs, "prefs_example_03.epb", NULL);
elm_prefs_data_set(prefs, prefs_data);

Now we "swallow" the layout into the SWALLOW item of the prefs widget.

elm_prefs_item_swallow(prefs, "main:swal", layout);

Page loaded and item changed callbacks will call update functions.

_page_loaded_cb(void *data, Evas_Object *obj, void *event_info EINA_UNUSED)
{
Evas_Object *layout = data;
_update(obj, layout);
}
static void
_item_changed_cb(void *data, Evas_Object *obj, void *event_info)
{
const char *item = event_info;
Evas_Object *layout = data;
if (!strcmp(item, "main:config:options:animation_time"))
_update_animation_time(obj, layout);
else if (!strcmp(item, "main:config:options:animation"))
_update_animation(obj, layout);
}

These update functions will be called in order to get the new value from the items and pass it as signal to edje handle it and affects on animation.

_update(Evas_Object *prefs, Evas_Object *layout)
{
_update_animation(prefs, layout);
_update_animation_time(prefs, layout);
}

In this function we'll get the checkbox (bool) value and start or stop the animation on edje.

_update_animation(Evas_Object *prefs, Evas_Object *layout)
{
Eina_Value value;
Eina_Bool animation;
elm_prefs_item_value_get(prefs, "main:config:options:animation", &value);
eina_value_get(&value, &animation);
if (animation)
elm_layout_signal_emit(layout, "start", "animation");
else
elm_layout_signal_emit(layout, "stop", "animation");
}

In this function we'll get the slider (float item) value and send it as animation time to edje.

_update_animation_time(Evas_Object *prefs, Evas_Object *layout)
{
Eina_Value value;
float animation_time;
elm_prefs_item_value_get(prefs, "main:config:options:animation_time", &value);
eina_value_get(&value, &animation_time);
if (animation_time < 0.01) animation_time = 0.01;
msg.val = animation_time;
MSG_ID_VEL, &msg);
}

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

EDJE_MESSAGE_FLOAT
@ EDJE_MESSAGE_FLOAT
A message with a floating pointer number as value.
Definition: Edje_Legacy.h:558
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
EINA_UNUSED
#define EINA_UNUSED
Definition: eina_types.h:339
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:292
evas_object_smart_callback_add
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
Evas_Object
Efl_Canvas_Object Evas_Object
Definition: Evas_Common.h:180
elm_prefs_data_new
EAPI 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
_Edje_Message_Float
Structure passed as value on EDJE_MESSAGE_FLOAT messages.
Definition: Edje_Legacy.h:494
evas_object_resize
void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h)
Changes the size of the given Evas object.
Definition: evas_object_main.c:1236
evas_object_size_hint_weight_set
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
elm_layout_signal_emit
EAPI void elm_layout_signal_emit(Eo *obj, const char *emission, const char *source)
Send a (Edje) signal to a given layout widget's underlying Edje object.
Definition: efl_ui_layout.c:3373
edje_object_message_send
void edje_object_message_send(Evas_Object *obj, Edje_Message_Type type, int id, void *msg)
Sends an (Edje) message to a given Edje object.
Definition: edje_message_queue.c:1016
elm_prefs_add
EAPI Evas_Object * elm_prefs_add(Evas_Object *parent)
Add a new prefs widget.
Definition: elm_prefs.c:478
eina_value_get
static Eina_Bool eina_value_get(const Eina_Value *value,...)
Gets the generic value.
elm_layout_file_set
EAPI Eina_Bool elm_layout_file_set(Eo *obj, const char *file, const char *group)
Set the file that will be used as layout.
Definition: efl_ui_layout.c:3079
_Edje_Message_Float::val
double val
The message's value.
Definition: Edje_Legacy.h:495
evas_object_show
void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition: evas_object_main.c:1814
EINA_TRUE
#define EINA_TRUE
Definition: eina_types.h:539
elm_layout_edje_get
EAPI Evas_Object * elm_layout_edje_get(const Eo *obj)
Get the edje layout.
Definition: efl_ui_layout.c:1888
Eina_Bool
unsigned char Eina_Bool
Definition: eina_types.h:527
elm_layout_add
EAPI Evas_Object * elm_layout_add(Evas_Object *parent)
Add a new layout to the parent.
Definition: efl_ui_layout.c:3072
_Eina_Value
Definition: eina_value.h:662
EET_FILE_MODE_READ_WRITE
@ EET_FILE_MODE_READ_WRITE
File is for both read and write.
Definition: Eet.h:477