Wiki pages preference_tutorial created: 3 tuto pages + 12 images + code c, epc

Signed-off-by: Clément Bénier <clement.benier@openwide.fr>
Signed-off-by: Pierre Le Magourou <pierre.lemagourou@openwide.fr>
Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>
This commit is contained in:
Clément Bénier 2015-07-07 12:26:29 +02:00 committed by Cedric BAIL
parent 5e0f62e4cd
commit 5912b58106
18 changed files with 549 additions and 0 deletions

View File

@ -0,0 +1,82 @@
#include <Elementary.h>
static void
_save_cb(void *data, Evas_Object *obj, void *event_info)
{
Evas_Object *prefs;
Evas_Object *label;
prefs = obj;
label = (Evas_Object *) elm_prefs_item_object_get(prefs, "main:label");
elm_object_text_set(label, "<i>Preferences have been saved.</i>");
}
static void
_action_cb(void *data, Evas_Object *obj, void *event_info)
{
Evas_Object *prefs;
Elm_Prefs_Data *prefs_data;
Elm_Prefs_Item_Type type;
Eina_Value value;
int value_int = -1;
Evas_Object *button;
char buf[64];
prefs = obj;
prefs_data = elm_prefs_data_get(prefs);
if (elm_prefs_data_value_get(prefs_data, "main:universe", &type, &value))
{
eina_value_get(&value, &value_int);
snprintf(buf, sizeof(buf), "Value: %d", value_int);
button = (Evas_Object *) elm_prefs_item_object_get(prefs, "main:buttons:action");
elm_object_text_set(button, buf);
}
}
static void
_changed_cb(void *data, Elm_Prefs_Data_Event_Type type, Elm_Prefs_Data *prefs_data, void *event_info)
{
Evas_Object *prefs;
Elm_Prefs_Data_Event_Changed *event;
int value_int;
Evas_Object *label;
char buf[64];
prefs = data;
event = event_info;
if (strcmp(event->key, "main:another")) return;
eina_value_get(event->value, &value_int);
snprintf(buf, sizeof(buf), "Spinner: %d", value_int);
label = (Evas_Object *) elm_prefs_item_object_get(prefs, "main:label");
elm_object_text_set(label, buf);
}
EAPI_MAIN int
elm_main(int argc, char **argv)
{
Evas_Object *win, *conform;
win = elm_win_util_standard_add("main", "Preferences Tutorial");
elm_win_conformant_set(win, EINA_TRUE);
evas_object_show(win);
evas_object_resize(win, 480, 800);
elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
elm_win_autodel_set(win, EINA_TRUE);
conform = elm_conformant_add(win);
evas_object_size_hint_weight_set(conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_win_resize_object_add(win, conform);
evas_object_show(conform);
Evas_Object *prefs;
prefs = elm_prefs_add(win);
evas_object_size_hint_weight_set(prefs, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_object_content_set(conform, prefs);
evas_object_show(prefs);
elm_prefs_autosave_set(prefs, EINA_FALSE);
elm_prefs_file_set(prefs, "preference.epb", NULL);
Elm_Prefs_Data *prefs_data;
prefs_data = elm_prefs_data_new("preference.cfg", NULL, EET_FILE_MODE_READ_WRITE);
elm_prefs_data_set(prefs, prefs_data);
evas_object_smart_callback_add(prefs, "page,saved", _save_cb, NULL);
evas_object_smart_callback_add(prefs, "action", _action_cb, NULL);
elm_prefs_data_event_callback_add(prefs_data, ELM_PREFS_DATA_EVENT_ITEM_CHANGED, _changed_cb, prefs);
elm_run();
elm_shutdown();
return EXIT_SUCCESS;
}
ELM_MAIN()

View File

@ -0,0 +1,132 @@
collection {
//! [page_main_head]
page {
name: "main";
version: 1;
title: "Main preferences";
subtitle: "Some preferences";
widget: "elm/vertical_box";
//! [page_main_head]
items {
//! [item_int]
item {
name: "universe";
type: INT;
label: "Ultimate Answer of Life, the Universe and Everything";
editable: 1;
int {
min: 0;
max: 100;
default: 42;
}
}
//! [item_int]
//! [item_int_spinner]
item {
name: "another";
type: INT;
label: "Spinner";
widget: "elm/spinner";
int {
min: -50;
max: 200;
}
}
//! [item_int_spinner]
//! [item_float]
item {
name: "floating";
type: FLOAT;
editable: 1;
label: "floating value";
float {
default: 0.6;
min: 0;
max: 1;
}
}
//! [item_float]
//! [item_bool]
item {
name: "boolean";
type: BOOL;
label: "Check here";
bool {
default: true;
}
}
//! [item_bool]
//! [item_display]
item {
name: "sep";
type: SEPARATOR;
}
item {
name: "label";
type: LABEL;
label: "Some other preferences…";
}
//! [item_display]
//! [item_text]
item {
name: "text";
type: TEXT;
editable: 1;
text {
placeholder: "Enter some text here.";
default: "default";
deny: "^[0-9]*$";
}
}
//! [item_text]
//! [item_date]
item {
name: "date";
type: DATE;
label: "First EFL Developer Day";
date {
default: 2012 11 05;
min: 1980 11 1;
max: 2200 12 2;
}
}
//! [item_date]
item {
name: "sep";
type: SEPARATOR;
}
//! [item_page]
item {
name: "buttons";
type: PAGE;
source: "buttons";
}
//! [item_page]
}
}
//! [page_buttons]
page {
name: "buttons";
version: 1;
title: "Actions";
widget: "elm/horizontal_box";
items {
item {
name: "save";
type: SAVE;
label: "Save";
}
item {
name: "reset";
type: RESET;
label: "Reset";
}
item {
name: "action";
type: ACTION;
label: "Action!";
}
}
}
//! [page_buttons]
}

BIN
media/preference_action.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

BIN
media/preference_base.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

BIN
media/preference_bool.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.0 KiB

BIN
media/preference_date.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.3 KiB

BIN
media/preference_float.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.8 KiB

BIN
media/preference_int.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.0 KiB

BIN
media/preference_save.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

BIN
media/preference_text.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.4 KiB

View File

@ -49,6 +49,7 @@ Go check the current available version of EFL on each distro/platform:
* [[tutorial/naviframe_tutorial|Naviframe Tutorial]]
* [[tutorial/popup_tutorial|Popup Tutorial]]
* [[tutorial/gl_2d_tutorial|GL 2D Tutorial]]
* [[tutorial/preference_tutorial|Preference Tutorial]]
----

View File

@ -0,0 +1,121 @@
~~Title: Code Preferences~~
//**__previous page__: **//[[/tutorial/preference/description|Preferences Description]]
==== Code Preferences ====
Now that the preferences is fully described, add them to our application.
<code c>
Evas_Object *prefs;
prefs = elm_prefs_add(win);
evas_object_size_hint_weight_set(prefs, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
elm_object_content_set(conform, prefs);
evas_object_show(prefs);
elm_prefs_autosave_set(prefs, EINA_FALSE);
elm_prefs_file_set(prefs, "preference.epb", NULL);
</code>
{{ :preference_base.png }}
An ''Elm_Prefs'' object is here created, which is the one that will display the
preferences. The automatic saving is then set to false, and the file holding
the compiled preferences is defined.
<code c>
Elm_Prefs_Data *prefs_data;
prefs_data = elm_prefs_data_new("preference.cfg", NULL, EET_FILE_MODE_READ_WRITE);
elm_prefs_data_set(prefs, prefs_data);
</code>
Here, an ''Elm_Prefs_Data'' object is created. It will hold the user-defined
values. The file in which those values will be stored in and read from at
start is set in ''prefs_data''. Finally, it is associated with the preferences
created before.
As you remember, three buttons for three actions were added in preferences: one
saves the form, one resets it, and a last one does an other action.
Elementary will generate some events in the lifetime
of the preferences. For instance, we may want to get notified when the
preferences are saved or when the action button is clicked.
<code c>
evas_object_smart_callback_add(prefs, "page,saved", _save_cb, NULL);
evas_object_smart_callback_add(prefs, "action", _action_cb, NULL);
elm_prefs_data_event_callback_add(prefs_data, ELM_PREFS_DATA_EVENT_ITEM_CHANGED, _changed_cb, prefs);
</code>
Those will call the specified callbacks. A specification for a function to be
called for each and every value change is also added.
<code c>
static void
_save_cb(void *data, Evas_Object *obj, void *event_info)
{
Evas_Object *prefs;
Evas_Object *label;
prefs = obj;
label = (Evas_Object *) elm_prefs_item_object_get(prefs, "main:label");
elm_object_text_set(label, "<i>Preferences have been saved.</i>");
}
</code>
The callback for the save action will simply change the label text.
{{ :preference_save.png }}
However, the one for the action is a bit more complex. It will get the value
from the ''universe'' item, and will set it as the label of the ''action'' button.
Note how ''main:buttons:'' has to be prefixed as if it were in the buttons page,
itself is in the "main" page.
<code c>
static void
_action_cb(void *data, Evas_Object *obj, void *event_info)
{
Evas_Object *prefs;
Elm_Prefs_Data *prefs_data;
Elm_Prefs_Item_Type type;
Eina_Value value;
int value_int = -1;
Evas_Object *button;
char buf[64];
prefs = obj;
prefs_data = elm_prefs_data_get(prefs);
if (elm_prefs_data_value_get(prefs_data, "main:universe", &type, &value))
{
eina_value_get(&value, &value_int);
snprintf(buf, sizeof(buf), "Value: %d", value_int);
button = (Evas_Object *) elm_prefs_item_object_get(prefs, "main:buttons:action");
elm_object_text_set(button, buf);
}
}
</code>
{{ :preference_action.png }}
This last function will receive an event for all preferences change. In this
example, only the ones pertaining to the "another" item are treated: its value
is read and set to the label.
<code c>
static void
_changed_cb(void *data, Elm_Prefs_Data_Event_Type type, Elm_Prefs_Data *prefs_data, void *event_info)
{
Evas_Object *prefs;
Elm_Prefs_Data_Event_Changed *event;
int value_int;
Evas_Object *label;
char buf[64];
prefs = data;
event = event_info;
if (strcmp(event->key, "main:another")) return;
eina_value_get(event->value, &value_int);
snprintf(buf, sizeof(buf), "Spinner: %d", value_int);
label = (Evas_Object *) elm_prefs_item_object_get(prefs, "main:label");
elm_object_text_set(label, buf);
}
</code>
{{ :preference_another.png }}
//**__The whole code__: **//{{ /code_c/tutorial/preference/preference.c }}{{
/code_c/tutorial/preference/preference.epc }}

View File

@ -0,0 +1,195 @@
~~Title: Description Preferences~~
==== Description Preferences ====
A .edc. file contains a collection with one or several page, holding items.
A page is a group of preferences. It has a name, a version number, a title and
subtitle, and has a graphical representation (widget).
<code c>
page {
name: "main";
version: 1;
title: "Main preferences";
subtitle: "Some preferences";
widget: "elm/vertical_box";
</code>
In this example, there is a page called “main”, with a version code of 1,
holding the preferences in a vertical box.
Then, a preference that holds an integer is added.
<code c>
item {
name: "universe";
type: INT;
label: "Ultimate Answer of Life, the Universe and Everything";
editable: 1;
int {
min: 0;
max: 100;
default: 42;
}
}
</code>
Here, an editable integer contains a value between 0 and 100, with a
default value of 42. A label is attached to it.
{{ :preference_int.png }}
The type of graphical interface presented to the user can be specified:
<code c>
item {
name: "another";
type: INT;
label: "Spinner";
widget: "elm/spinner";
int {
min: -50;
max: 200;
}
}
</code>
{{ preference_int-spinner.png }}
If wanted, float values can be added too.
<code c>
item {
name: "floating";
type: FLOAT;
editable: 1;
label: "floating value";
float {
default: 0.6;
min: 0;
max: 1;
}
}
</code>
{{ :preference_float.png }}
Boolean preferences can be represented as checkboxes.
<code c>
item {
name: "boolean";
type: BOOL;
label: "Check here";
bool {
default: true;
}
}
</code>
{{ :preference_bool.png }}
Adding graphical-only items such as separators or label works the same way.
<code c>
item {
name: "sep";
type: SEPARATOR;
}
item {
name: "label";
type: LABEL;
label: "Some other preferences…";
}
</code>
{{ :preference_display.png }}
It is possible to add a text entry. In the following example, we will have a
placeholder text, and a default value. The deny section is filled with a
regular expression that specifies what the user entered text should not match,
otherwise refusing the entry.
<code c>
item {
name: "text";
type: TEXT;
editable: 1;
text {
placeholder: "Enter some text here.";
default: "default";
deny: "^[0-9]*$";
}
}
</code>
{{ :preference_text.png }}
For adding a date section, a minimum and maximum date can be set.
<code c>
item {
name: "date";
type: DATE;
label: "First EFL Developer Day";
date {
default: 2012 11 05;
min: 1980 11 1;
max: 2200 12 2;
}
}
</code>
Let's say that display buttons are wanted to be displayed such as one to save, another
one to reset the form back, and the last one to do some action. They are
wanted to be shown in a horizontal box. A new page needs to be created to hold
those items.
<code c>
page {
name: "buttons";
version: 1;
title: "Actions";
widget: "elm/horizontal_box";
items {
item {
name: "save";
type: SAVE;
label: "Save";
}
item {
name: "reset";
type: RESET;
label: "Reset";
}
item {
name: "action";
type: ACTION;
label: "Action!";
}
}
}
</code>
{{ :preference_buttons.png }}
This page needs to be added to the main one.
<code c>
item {
name: "buttons";
type: PAGE;
source: "buttons";
}
</code>
Our preference collection is now complete, we now have to compile it using
elm_prefs_cc preference.epc, which will generate a compiled preference.epb file.
Our preference collenction is now complete, to compile it use ''elm_prefs_cc
preference.epc'' which will generate a compiled preference.epb file.
\\
//**__The whole code__: **//{{ code_c/tutorial/preference/preference.epc }}
\\
//**__next page__: **//[[/tutorial/preference/code|Preferences Code]]

View File

@ -0,0 +1,18 @@
~~Title: Preference Tutorial~~
==== Preference Tutorial ====
In this tutorial, we will see how to add preferences to an application.
Elementary provides a subset to define preferences, Elm_Prefs. Those are
defined in special .epc files who look a lot like .edc files. They are
compiled to a binary form using elm_prefs_cc.
=== Table of Contents ===
* [[/tutorial/preference/description|Preferences Description]]
* [[/tutorial/preference/code|Preferences Code]]
Preference example: {{ :preference_base.png }}
//**__The whole code__: **//{{ code_c/tutorial/preference/preference.epc }} {{
code_c/tutorial/preference/preference.c}}