diff --git a/media/code_c/tutorial/preference/preference.c b/media/code_c/tutorial/preference/preference.c new file mode 100644 index 000000000..94f44b5c2 --- /dev/null +++ b/media/code_c/tutorial/preference/preference.c @@ -0,0 +1,82 @@ +#include + +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, "Preferences have been saved."); +} + +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() + diff --git a/media/code_c/tutorial/preference/preference.epc b/media/code_c/tutorial/preference/preference.epc new file mode 100644 index 000000000..0612a4d93 --- /dev/null +++ b/media/code_c/tutorial/preference/preference.epc @@ -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] +} diff --git a/media/preference_action.png b/media/preference_action.png new file mode 100644 index 000000000..fe2d16a11 Binary files /dev/null and b/media/preference_action.png differ diff --git a/media/preference_another.png b/media/preference_another.png new file mode 100644 index 000000000..92d560788 Binary files /dev/null and b/media/preference_another.png differ diff --git a/media/preference_base.png b/media/preference_base.png new file mode 100644 index 000000000..a49c00f86 Binary files /dev/null and b/media/preference_base.png differ diff --git a/media/preference_bool.png b/media/preference_bool.png new file mode 100644 index 000000000..e57f5245f Binary files /dev/null and b/media/preference_bool.png differ diff --git a/media/preference_buttons.png b/media/preference_buttons.png new file mode 100644 index 000000000..a7170ad69 Binary files /dev/null and b/media/preference_buttons.png differ diff --git a/media/preference_date.png b/media/preference_date.png new file mode 100644 index 000000000..1e41562be Binary files /dev/null and b/media/preference_date.png differ diff --git a/media/preference_display.png b/media/preference_display.png new file mode 100644 index 000000000..078022d15 Binary files /dev/null and b/media/preference_display.png differ diff --git a/media/preference_float.png b/media/preference_float.png new file mode 100644 index 000000000..44e84f335 Binary files /dev/null and b/media/preference_float.png differ diff --git a/media/preference_int-spinner.png b/media/preference_int-spinner.png new file mode 100644 index 000000000..2633c4a51 Binary files /dev/null and b/media/preference_int-spinner.png differ diff --git a/media/preference_int.png b/media/preference_int.png new file mode 100644 index 000000000..2cddb4413 Binary files /dev/null and b/media/preference_int.png differ diff --git a/media/preference_save.png b/media/preference_save.png new file mode 100644 index 000000000..b98c887f9 Binary files /dev/null and b/media/preference_save.png differ diff --git a/media/preference_text.png b/media/preference_text.png new file mode 100644 index 000000000..156de23ea Binary files /dev/null and b/media/preference_text.png differ diff --git a/pages/docs.txt b/pages/docs.txt index 93ac435c0..2f1625b78 100644 --- a/pages/docs.txt +++ b/pages/docs.txt @@ -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]] ---- diff --git a/pages/tutorial/preference/code.txt b/pages/tutorial/preference/code.txt new file mode 100644 index 000000000..98d787356 --- /dev/null +++ b/pages/tutorial/preference/code.txt @@ -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. + + +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); + + +{{ :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. + + +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); + + +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. + + +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); + + +Those will call the specified callbacks. A specification for a function to be +called for each and every value change is also added. + + +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, "Preferences have been saved."); +} + + +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. + + +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); + } +} + + +{{ :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. + + +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); +} + + +{{ :preference_another.png }} + +//**__The whole code__: **//{{ /code_c/tutorial/preference/preference.c }}{{ +/code_c/tutorial/preference/preference.epc }} diff --git a/pages/tutorial/preference/description.txt b/pages/tutorial/preference/description.txt new file mode 100644 index 000000000..5ee68af46 --- /dev/null +++ b/pages/tutorial/preference/description.txt @@ -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). + + + page { + name: "main"; + version: 1; + title: "Main preferences"; + subtitle: "Some preferences"; + widget: "elm/vertical_box"; + + +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. + + + item { + name: "universe"; + type: INT; + label: "Ultimate Answer of Life, the Universe and Everything"; + editable: 1; + int { + min: 0; + max: 100; + default: 42; + } + } + + +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: + + + item { + name: "another"; + type: INT; + label: "Spinner"; + widget: "elm/spinner"; + int { + min: -50; + max: 200; + } + } + + +{{ preference_int-spinner.png }} + +If wanted, float values can be added too. + + + item { + name: "floating"; + type: FLOAT; + editable: 1; + label: "floating value"; + float { + default: 0.6; + min: 0; + max: 1; + } + } + + +{{ :preference_float.png }} + +Boolean preferences can be represented as checkboxes. + + + item { + name: "boolean"; + type: BOOL; + label: "Check here"; + bool { + default: true; + } + } + + +{{ :preference_bool.png }} + +Adding graphical-only items such as separators or label works the same way. + + + item { + name: "sep"; + type: SEPARATOR; + } + item { + name: "label"; + type: LABEL; + label: "Some other preferences…"; + } + + +{{ :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. + + + item { + name: "text"; + type: TEXT; + editable: 1; + text { + placeholder: "Enter some text here."; + default: "default"; + deny: "^[0-9]*$"; + } + } + + +{{ :preference_text.png }} + +For adding a date section, a minimum and maximum date can be set. + + + item { + name: "date"; + type: DATE; + label: "First EFL Developer Day"; + date { + default: 2012 11 05; + min: 1980 11 1; + max: 2200 12 2; + } + } + + +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. + + + 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!"; + } + } + } + + +{{ :preference_buttons.png }} + +This page needs to be added to the main one. + + + item { + name: "buttons"; + type: PAGE; + source: "buttons"; + } + + +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]] diff --git a/pages/tutorial/preference_tutorial.txt b/pages/tutorial/preference_tutorial.txt new file mode 100644 index 000000000..167a899b8 --- /dev/null +++ b/pages/tutorial/preference_tutorial.txt @@ -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}}