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

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
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
struct _Eina_Value Eina_Value
Store generic values.
Definition eina_value.h:307
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

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_Message_Float
struct _Edje_Message_Float Edje_Message_Float
Alias for _Edje_Message_Float.
Definition Edje_Legacy.h:496
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::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