Prefs Example 01

This example shows how to create a simple prefs widget with Elementary, where the items values are "reset" on each timer tick.

We do that programmatically, to demonstrate that by touching a given prefs widgets prefs data values, the changes reflect instantly on the UI.

We'll create items on the .EPC file and after handle it on the .C file.

Creating items on EPC file

First we'll create prefs items on .EPC file that we'll use later on the .C file. Note that the code is similar to .EDC (edje) files.

collection
{
   page
   {
      name: "main";
      version: 1;
      title: "Preferences Widget";
      subtitle: "Example 01";

Here we define a page item. Pages are group of items grouped together, on a given prefs widget.

      widget: "elm/vertical_box";

In this part, we create a INT type item, that by default will become a spinner widget in the UI, and default, min and max parameters are optional as well as in FLOAT type.

      items {
         item {
            name: "universe";
            type: INT;
            label: "Ultimate Answer of Life, the Universe and Everything";
            editable: 1;
 
            int {
               default: 42;
               min: 0;
               max: 150;
            }
         }

Other INT type widget implementations may exist, as is exemplified on the item that follows.

         item {
            name: "another int";
            type: INT;
            widget: "elm/spinner";
 
            int {
               min: 0;
            }
         }

Now we create a LABEL type item and by default will become a read-only label in UI.

         item {
            name: "label";
            type: LABEL;
            label: "Just a label...";
         }

Now we create a TEXT type item and by default will become a single-line text entry in UI. Note that we use a Regular Expression to deny only entries with numbers.

         item {
            name: "text";
            type: TEXT;
            editable: 1;
 
            text {
               placeholder: "This is a text field (:";
               default: "default str.";
               deny: "^[0-9]*$";
            }
         }

In this part we create a DATE type item, by default will become a datetime in UI, and default, min and max parameters are optional.

         item {
            name: "date";
            type: DATE;
            label: "First EFL Developer Day";
 
            date {
               default: 2012 11 05;
               min: 1980 11 1;
               max: 2200 12 2;
            }

Here we create a SEPARATOR type item, it has no value bound, serves only to divide and organize prefs items.

         item {
            name: "sep";
            type: SEPARATOR;
         }

In this part, we create a SAVE type item that will get all the values bounded to items and save it on CFG file. Next time you execute the application, all the values that you saved before will be loaded.

         item {
            name: "save";
            type: SAVE;
            label: "Save";
         }

Here we create a RESET type item that will return all the values bounded to items as default declared on .EPC file.

         item {
            name: "reset";
            type: RESET;
            label: "Reset";
         }

Pages and items have default implementation widgets, but, with the tag 'widget', you can use different widgets for prefs items. To a list of default widgets supported by each type, by default, refer to the Elementary Prefs Collection reference sheet. One can also register, at run time, custom item widget handlers too.

Handling items on C File

Now we're handling the .C file and first we'll create a prefs widget.

   prefs = elm_prefs_add(win);
   evas_object_size_hint_weight_set(prefs, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   elm_win_resize_object_add(win, prefs);
   evas_object_show(prefs);

Here we add some specific callbacks, for example "item,changed" that will be called when any item that we created on EPC file changes.

   evas_object_smart_callback_add(prefs, "page,saved", _page_saved_cb, NULL);
   evas_object_smart_callback_add(prefs, "page,loaded", _page_loaded_cb, NULL);
   evas_object_smart_callback_add(prefs, "item,changed", _item_changed_cb, win);

Here we set the prefs to save its values back (on the user data file) automatically on every UI element changes.

   elm_prefs_autosave_set(prefs, EINA_TRUE);

In this part we create the prefs data handle and set the .EPB file (.EPC compiled). This .EPB file contains all the default values from the items that we created, this file will be loaded when the program starts or when clicked on a RESET type item. There is another file created when the values from prefs items are saved, the .CFG file, that contains all the non-standard saved values from the prefs items, this file will be loaded when program starts as well.

   Elm_Prefs_Data *prefs_data;
   prefs_data = elm_prefs_data_new("./prefs_example_01.cfg", NULL,
                                   EET_FILE_MODE_READ_WRITE);
 
   elm_prefs_file_set(prefs, "prefs_example_01.epb", NULL);
   elm_prefs_data_set(prefs, prefs_data);

Here we just create a notify widget to appear when the values are reset.

   label = elm_label_add(win);
   elm_object_text_set(label, "Setting Values Programmatically");
   evas_object_size_hint_align_set(label, 0.5, 0.5);
 
   notify = elm_notify_add(win);
   elm_notify_align_set(notify, 0.5, 1);
   elm_notify_timeout_set(notify, 2);
   elm_object_content_set(notify, label);
   evas_object_size_hint_weight_set(notify, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   evas_object_show(notify);

Now we add a timer to reset the items values on each 5.0 seconds and show the notify.

   evas_object_data_set(notify, "prefs_data", prefs_data);

_elm_prefs_data_change(void *data)
{
   Evas_Object *notify = data;
   Elm_Prefs_Data *prefs_data;
   Elm_Prefs_Item_Type type;
   Eina_Value value;
 
   prefs_data = evas_object_data_get(notify, "prefs_data");
 
   if (elm_prefs_data_value_get(prefs_data, "main:universe", &type, &value))
     {
        eina_value_set(&value, 42);
        elm_prefs_data_value_set(prefs_data, "main:universe", type, &value);
     }
 
   if (elm_prefs_data_value_get(prefs_data, "main:text", &type, &value))
     {
        eina_value_set(&value, "This is a text field (:");
        elm_prefs_data_value_set(prefs_data, "main:text", type, &value);
     }
 
   evas_object_show(notify);
 
   return ECORE_CALLBACK_RENEW;
}

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