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");
elm_layout_file_set
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:3074
elm_layout_add
Evas_Object * elm_layout_add(Evas_Object *parent)
Add a new layout to the parent.
Definition: efl_ui_layout.c:3067

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

prefs = elm_prefs_add(win);
evas_object_size_hint_weight_set(prefs, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_resize(prefs, WIDTH, HEIGHT);
evas_object_show(prefs);
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);
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
EET_FILE_MODE_READ_WRITE
@ EET_FILE_MODE_READ_WRITE
File is for both read and write.
Definition: Eet.h:481
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition: eina_types.h:539
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_add
Evas_Object * elm_prefs_add(Evas_Object *parent)
Add a new prefs widget.
Definition: elm_prefs.c:478
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
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
evas_object_resize
EVAS_API 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_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

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);
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition: eina_types.h:339
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition: Evas_Common.h:185
}

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");
}
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition: eina_types.h:527
eina_value_get
static Eina_Bool eina_value_get(const Eina_Value *value,...)
Gets the generic value.
elm_layout_signal_emit
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:3388
_Eina_Value
defines the contents of a value
Definition: eina_value.h:662

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;
Edje_Message_Float msg;
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;
edje_object_message_send(elm_layout_edje_get(layout), EDJE_MESSAGE_FLOAT,
MSG_ID_VEL, &msg);
}
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
EDJE_MESSAGE_FLOAT
@ EDJE_MESSAGE_FLOAT
A message with a floating pointer number as value.
Definition: Edje_Legacy.h:580
elm_layout_edje_get
Evas_Object * elm_layout_edje_get(const Eo *obj)
Get the edje layout.
Definition: efl_ui_layout.c:1883
_Edje_Message_Float
Structure passed as value on EDJE_MESSAGE_FLOAT messages.
Definition: Edje_Legacy.h:516
_Edje_Message_Float::val
double val
The message's value.
Definition: Edje_Legacy.h:517

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