Cross-platform C SDK logo
EspañolEnglish
Cross-platform C SDK

GUI Data binding

❮ Back
Next ❯

By GUI Data Binding we mean automatic mapping between program variables and user interface controls (Figure 1). In this way both will be synchronized without the programmer having to do any extra work such as capturing events, assigning values, checking ranges, etc. In Hello Gui Binding! you have the complete source code of the example that we will show below.

Figure 1: Automatic data synchronization with the user interface.

#1. Basic type binding

We start from a data structure composed of several basic types fields (Listing 1), where no other structures or objects are nested.

Listing 1: Simple data model.
typedef enum _myenum_t
{
    ekRED,
    ekBLUE,
    ekGREEN,
    ekBLACK,
    ekMAGENTA,
    ekCYAN,
    ekYELLOW,
    ekWHITE
} myenum_t;

typedef struct _basictypes_t BasicTypes;

struct _basictypes_t
{
    bool_t bool_val;
    uint16_t uint16_val;
    real32_t real32_val;
    myenum_t enum_val;
    gui_state_t enum3_val;
    String *str_val;
};

The first thing we must do is register the fields of the structure with dbind (Listing 2):

Listing 2: Register in dbind de los campos de la estructura.
dbind_enum(gui_state_t, ekGUI_OFF, "");
dbind_enum(gui_state_t, ekGUI_ON, "");
dbind_enum(gui_state_t, ekGUI_MIXED, "");
dbind_enum(myenum_t, ekRED, "Red");
dbind_enum(myenum_t, ekBLUE, "Blue");
dbind_enum(myenum_t, ekGREEN, "Green");
dbind_enum(myenum_t, ekBLACK, "Black");
dbind_enum(myenum_t, ekMAGENTA, "Magenta");
dbind_enum(myenum_t, ekCYAN, "Cyan");
dbind_enum(myenum_t, ekYELLOW, "Yellow");
dbind_enum(myenum_t, ekWHITE, "White");
dbind(BasicTypes, bool_t, bool_val);
dbind(BasicTypes, uint16_t, uint16_val);
dbind(BasicTypes, real32_t, real32_val);
dbind(BasicTypes, gui_state_t, enum3_val);
dbind(BasicTypes, myenum_t, enum_val);
dbind(BasicTypes, String*, str_val);
dbind_range(BasicTypes, real32_t, real32_val, -50, 50);
dbind_increment(BasicTypes, real32_t, real32_val, 5);
DBind is a registry, within the application, that allows automating certain operations on the data, as well as establishing ranges, precisions or aliases. Its use goes beyond graphical user interfaces. More information in Data binding.

On the other hand, we build a Layout that hosts the different controls of the user interface (Listing 3). For clarity, we show a reduced version of the example. In Hello Gui Binding! it is extended with more controls, organized in several sub-layouts.

Listing 3: Interface controls organized in a layout (Figure 1).
static Layout *i_layout(void)
{
    Layout *layout1 = layout_create(3, 9);
    Layout *layout2 = i_radio_layout();
    Label *label = label_create();
    Edit *edit = edit_create();
    Button *check1 = button_check();
    Button *check2 = button_check3();
    PopUp *popup = popup_create();
    ListBox *listbox = listbox_create();
    Slider *slider = slider_create();
    UpDown *updown = updown_create();
    layout_label(layout1, label, 1, 0);
    layout_edit(layout1, edit, 1, 1);
    layout_button(layout1, check1, 1, 2);
    layout_button(layout1, check2, 1, 3);
    layout_layout(layout1, layout2, 1, 4);
    layout_popup(layout1, popup, 1, 5);
    layout_listbox(layout1, listbox, 1, 6);
    layout_slider(layout1, slider, 1, 7);
    layout_updown(layout1, updown, 1, 8);
    layout_halign(layout1, 1, 0, ekJUSTIFY);
    layout_halign(layout1, 1, 8, ekLEFT);
    return layout1;
}

Now we will link the cells of our layout with the fields of the structure (Listing 4). Pay attention that we have not yet created any object of type BasicTypes. Therefore, it is a semantic link where memory positions do not intervene, but the displacements (offset) of the fields within the data structure.

When linking a data structure with layout_dbind() we must bear in mind that the cells of said layout can only be associated with fields of the same structure. Otherwise, we will get a run-time error, due to the data inconsistency that would occur. In other words, we cannot mix structures within the same layout.

Isolated variables cannot be used in Data Binding. They must all belong to a struct since, internally, the relations (Layout = Struct) and (Cell = Field or Variable) are established.

Finally, we will associate an object of type BasicTypes with the layout created previously (Listing 5).

  • Use layout_dbind_obj to bind an object to the user interface.
  • Use layout_dbind_get_obj to get the binded object.
  • Listing 5: Binding an object to the interface.
    BasicTypes *data = heap_new(BasicTypes);
    data->bool_val = TRUE;
    data->uint16_val = 4;
    data->real32_val = 15.5f;
    data->enum3_val = ekGUI_MIXED;
    data->enum_val = ekCYAN;
    data->str_val = str_c("Text String");
    layout_dbind_obj(layout1, data, BasicTypes);
    
  • You can change the object being "edited" at any time, with a new call to layout_dbind_obj() (Figure 2).
  • If we pass NULL to layout_dbind_obj() the cells linked to fields of the structure will be disabled.
  • Figure 2: When we assign an object to a Layout, the values of its fields are synchronized with the interface.

#2. Limits and ranges

Keep in mind that the expressiveness of controls will, generally, be well below the range of values ​​supported by data types (Listing 6). For example, if we link a uint16_t with a RadioGroup the latter will only support values ​​between 0 and n-1, where n is the total number of radios. The controls are set up to handle out-of-range values ​​as consistently as possible, but this does not exempt the programmer from getting it right. In (Table 1) you have a summary of the data types and ranges supported by the standard controls.

Listing 6: Value not representable in the RadioGroup of (Figure 1).
data->uint16_val = 1678;
cell_dbind(layout_cell(layout1, 1, 4), BasicTypes, uint16_t, uint16_val);
Table 1: Data types and ranges of GUI controls.
Control Data Type
Label String, Number, Enum, Bool
Edit String, Number
Button (CheckBox) Boolean
Button (CheckBox3) Enum (3 values), Integer (0,1,2)
RadioGroup Enum, Integer (0,1,2...n-1)
PopUp Enum, Integer (0,1,2...n-1)
Combo String, Enum, Integer (0,1,2...n-1)
ListBox Enum, Integer (0,1,2...n-1)
TableView Enum, Integer (0,1,2...n-1)
Slider Number (min..max)
UpDown Enum, Number
ImageView Image
DateView Integer int32_t (days since 1970-01-01)

#3. Control-specific behavior

In most controls, the relationship between the field value and what the control shows is obvious: a text in an Edit, a boolean in a checkbox. But there are controls whose value has a specific meaning that the C data type does not describe by itself. In (Table 1) you have the summary of types; the particular cases are detailed here.

  • PopUp, ListBox, TableView, RadioGroup: An integer or enum field represents the index of the selected element (0..n-1). An out-of-range index leaves the control without selection. For enums, the position of the value within the enum is used, not its numeric value.
  • Automatic filling: If a PopUp, ListBox or Combo is empty when bound to an enum field, it is filled with the aliases registered with dbind_enum. A TableView is not filled, since it gets its data through tableview_OnData.
  • ListBox and TableView: Binding only works with single selection. If multiple selection is enabled (listbox_multisel, tableview_multisel), the control stops synchronizing with the field in both directions. There is no binding either in a TableView in tree mode (tableview_tree), since row indices change when nodes are expanded or collapsed.
  • ComboBox: With a String field, the text is synchronized in both directions: both what the user types and the text of the item chosen from the list. With an integer or enum field the index is synchronized, as in a PopUp. If the user types a text that matches an item in the list, its index is taken; if it does not match any, the field is left without selection.
  • Slider: A numeric field is normalized within the range set with dbind_range. An enum field is evenly distributed along the track.
  • ImageView: It is bound to Image* fields (Image).
  • DateView: It is bound to int32_t fields that represent the number of days elapsed since January 1, 1970, which is day 0. Previous days are negative and later days are positive. Use date_to_days and date_from_days to convert between this value and a Date.

Some more details about binding a DateView. In (Listing 7) we add to BasicTypes a date_val field, bound to a calendar, and a calculated field date_str, which shows the date as text in a Label:

  • The value INT32_MIN represents "no date": the calendar is shown without any selection. By default, int32_t fields are initialized to 0 (January 1, 1970). If you want them to start without a date, use dbind_default.
  • Any year between -32768 and 32767 can be represented, according to the proleptic Gregorian calendar with astronomical numbering (year 0 is 1 BC). Values outside this range are shown clamped to the nearest limit.
  • The same field can be bound to other controls: an UpDown will move one day forward or backward and an Edit or a Label will show the number of days. To show the date as text, use a calculated field Notifications and calculated fields.
  • If you limit the field with dbind_range, the value INT32_MIN will be out of range and it will not be possible to leave the field without a date.
  • Listing 7: Binding a DateView to an int32_t field and calculated field with the date as text.
    struct _basictypes_t
    {
        ...
        int32_t date_val;
        String *date_str;
    };
    
    dbind(BasicTypes, int32_t, date_val);
    dbind(BasicTypes, String*, date_str);
    
    static void i_date_str(BasicTypes *data)
    {
        str_destopt(&data->date_str);
        if (data->date_val != INT32_MIN)
        {
            Date date = date_from_days(data->date_val);
            data->date_str = str_printf("%d/%02d/%02d", date.year, date.month, date.mday);
        }
        else
        {
            data->date_str = str_c("No date");
        }
    }
    
    static void i_OnDataChange(BasicTypes *data, Event *e)
    {
        Layout *layout = event_sender(e, Layout);
        if (evbind_modify(e, BasicTypes, int32_t, date_val) == TRUE)
        {
            i_date_str(data);
            layout_dbind_update(layout, BasicTypes, String*, date_str);
        }
    }
    
    cell_dbind(layout_cell(layout1, 1, 9), BasicTypes, int32_t, date_val);
    cell_dbind(layout_cell(layout1, 1, 10), BasicTypes, String*, date_str);
    layout_dbind(layout1, listener(data, i_OnDataChange, BasicTypes), BasicTypes);
    ...
    Date today = date_system();
    data->date_val = date_to_days(&today);
    data->date_str = NULL;
    i_date_str(data);
    layout_dbind_obj(layout1, data, BasicTypes);
    

#4. Nested structures

Let's now look at a somewhat more complicated data model, which includes nested structures in addition to the basic types (Figure 3). In this case we have a structure called StructTypes that contains instances of another structure called Vector (Listing 8). You can find the complete source code for this second example at Hello Struct Binding!.

Figure 3: Data binding with substructures.
Listing 8: Data model with nested structures and registry in dbind.
typedef struct _vector_t Vector;
typedef struct _structtypes_t StructTypes;

struct _vector_t
{
    real32_t x;
    real32_t y;
    real32_t z;
};

struct _structtypes_t
{
    String *name;
    Vector vec1;
    Vector vec2;
    Vector vec3;
    Vector *pvec1;
    Vector *pvec2;
    Vector *pvec3;
    real32_t length1;
    real32_t length2;
    real32_t length3;
    real32_t length4;
    real32_t length5;
    real32_t length6;
};

dbind(Vector, real32_t, x);
dbind(Vector, real32_t, y);
dbind(Vector, real32_t, z);
dbind(StructTypes, String*, name);
dbind(StructTypes, Vector, vec1);
dbind(StructTypes, Vector, vec2);
dbind(StructTypes, Vector, vec3);
dbind(StructTypes, Vector*, pvec1);
dbind(StructTypes, Vector*, pvec2);
dbind(StructTypes, Vector*, pvec3);
dbind(StructTypes, real32_t, length1);
dbind(StructTypes, real32_t, length2);
dbind(StructTypes, real32_t, length3);
dbind(StructTypes, real32_t, length4);
dbind(StructTypes, real32_t, length5);
dbind(StructTypes, real32_t, length6);
dbind_range(Vector, real32_t, x, -5, 5);
dbind_range(Vector, real32_t, y, -5, 5);
dbind_range(Vector, real32_t, z, -5, 5);
dbind_increment(Vector, real32_t, x, .1f);
dbind_increment(Vector, real32_t, y, .1f);
dbind_increment(Vector, real32_t, z, .1f);

We started with the same methodology that we used with the first example. We create a layout and link it with the Vector structure (Listing 9). This does not present problems, as it is composed exclusively of basic types real32_t.

Listing 9: Layout for editing objects of type Vector.
static Layout *i_vector_layout(void)
{
    Layout *layout = layout_create(3, 3);
    Label *label1 = label_create();
    Label *label2 = label_create();
    Label *label3 = label_create();
    Edit *edit1 = edit_create();
    Edit *edit2 = edit_create();
    Edit *edit3 = edit_create();
    UpDown *updown1 = updown_create();
    UpDown *updown2 = updown_create();
    UpDown *updown3 = updown_create();
    label_text(label1, "X:");
    label_text(label2, "Y:");
    label_text(label3, "Z:");
    edit_align(edit1, ekRIGHT);
    edit_align(edit2, ekRIGHT);
    edit_align(edit3, ekRIGHT);
    layout_label(layout, label1, 0, 0);
    layout_label(layout, label2, 0, 1);
    layout_label(layout, label3, 0, 2);
    layout_edit(layout, edit1, 1, 0);
    layout_edit(layout, edit2, 1, 1);
    layout_edit(layout, edit3, 1, 2);
    layout_updown(layout, updown1, 2, 0);
    layout_updown(layout, updown2, 2, 1);
    layout_updown(layout, updown3, 2, 2);
    cell_dbind(layout_cell(layout, 1, 0), Vector, real32_t, x);
    cell_dbind(layout_cell(layout, 1, 1), Vector, real32_t, y);
    cell_dbind(layout_cell(layout, 1, 2), Vector, real32_t, z);
    cell_dbind(layout_cell(layout, 2, 0), Vector, real32_t, x);
    cell_dbind(layout_cell(layout, 2, 1), Vector, real32_t, y);
    cell_dbind(layout_cell(layout, 2, 2), Vector, real32_t, z);
    layout_dbind(layout, NULL, Vector);
    return layout;
}

The idea now is to use this function to create Sub-layouts and associate them to cells of a higher level layout, which can support objects of type StructTypes (Listing 10). Sub-layouts of type Vector are linked to the fields {Vector vec1, Vector * pvec1, ...} using cell_dbind, so similar to how we did it with the basic types.

Listing 10: Layout that supports objects of type StructTypes.
static Layout *i_struct_types_layout(void)
{
    Layout *layout1 = i_create_layout();
    Layout *layout2 = i_vector_layout();
    Layout *layout3 = i_vector_layout();
    Layout *layout4 = i_vector_layout();
    Layout *layout5 = i_vector_layout();
    Layout *layout6 = i_vector_layout();
    Layout *layout7 = i_vector_layout();
    Label *label1 = label_create();
    Label *label2 = label_create();
    Label *label3 = label_create();
    layout_layout(layout1, layout2, 0, 0);
    layout_layout(layout1, layout3, 1, 0);
    layout_layout(layout1, layout4, 2, 0);
    layout_layout(layout1, layout5, 0, 1);
    layout_layout(layout1, layout6, 1, 1);
    layout_layout(layout1, layout7, 2, 1);
    layout_label(layout1, label1, 0, 2);
    layout_label(layout1, label2, 1, 2);
    layout_label(layout1, label3, 2, 2);
    cell_dbind(layout_cell(layout1, 0, 0), StructTypes, Vector, vec1);
    cell_dbind(layout_cell(layout1, 1, 0), StructTypes, Vector, vec2);
    cell_dbind(layout_cell(layout1, 2, 0), StructTypes, Vector, vec3);
    cell_dbind(layout_cell(layout1, 0, 1), StructTypes, Vector*, pvec1);
    cell_dbind(layout_cell(layout1, 1, 1), StructTypes, Vector*, pvec2);
    cell_dbind(layout_cell(layout1, 2, 1), StructTypes, Vector*, pvec3);
    cell_dbind(layout_cell(layout1, 0, 2), StructTypes, real32_t, length1);
    cell_dbind(layout_cell(layout1, 1, 2), StructTypes, real32_t, length2);
    cell_dbind(layout_cell(layout1, 2, 2), StructTypes, real32_t, length3);
    layout_dbind(layout1, NULL, StructTypes);
    return layout1;
}

And finally, we only have to link objects of type StructTypes with the main layout (Listing 11). DBind will detect sub-layouts of type Vector and will automatically associate the corresponding sub-objects (by value or by pointer). Therefore, only one call to layout_dbind_obj will be necessary (the one of the main object).

Listing 11: Associate object and sub-objects to a layout.
StructTypes *data = heap_new(StructTypes);
Layout *layout = i_struct_types_layout();
data->name = str_c("Generic Object");
data->pvec1 = heap_new(Vector);
data->pvec2 = heap_new(Vector);
data->pvec3 = heap_new(Vector);
data->vec1 = i_vec_init(1.2f, 2.1f, -3.4f);
data->vec2 = i_vec_init(-0.2f, 1.8f, 2.3f);
data->vec3 = i_vec_init(-3.2f, 4.9f, -4.7f);
*data->pvec1 = i_vec_init(0.9f, 7.9f, -2.0f);
*data->pvec2 = i_vec_init(-6.9f, 2.2f, 8.6f);
*data->pvec3 = i_vec_init(3.9f, -5.5f, 0.3f);
data->length1 = i_vec_length(&data->vec1);
data->length2 = i_vec_length(&data->vec2);
data->length3 = i_vec_length(&data->vec3);
data->length4 = i_vec_length(data->pvec1);
data->length5 = i_vec_length(data->pvec2);
data->length6 = i_vec_length(data->pvec3);

layout_dbind_obj(layout, data, StructTypes);

In summary:

  • For each sub-structure we create a sub-layout, linking the fields locally.
  • The cells that contain these sub-layouts will be linked to the main structure.
  • We assign the object to edit to the main layout.

#5. Notifications and calculated fields

If we apply what was seen in the previous sections, the synchronization between data and interface is carried out in these two situations:

  • When the program calls layout_dbind_obj. At that time the interface will reflect the state of the object.
  • When the user manipulates any control, then the object's value will be updated.

However, it is possible that the program must be notified when the user modifies the object, in order to carry out certain actions (update drawings, save data in files, launch calculus algorithms, etc.). This will be resolved by events, as reflected in (Figure 4). On the other hand, the program can alter the values ​​of certain fields of the object and must notify the changes to the interface (layout) so that it remains updated.

Figure 4: Notification of value change to main program.
  • Use layout_dbind to include a listener that notifies changes to the application.
  • Use evbind_object to obtain, within the callback, the object that is being edited.
  • Use event_sender to obtain, within the callback, the layout that sent the notification.
  • Use evbind_modify to know, inside the callback, if a field of the object has changed or not.
  • Use layout_dbind_update to notify the layout that a field of the object has been modified by the application.

All of this can be seen in (Listing 12). Every time the user changes any StructTypes value, a notification of type ekGUI_EVENT_OBJCHANGE will be launched that will check if the vec1 field has changed. If so, its length will be recalculated and the GUI controls associated with that variable will be updated.

Listing 12: Notification of object values ​​modification.
static void i_OnDataChange(App *app, Event *e)
{
    StructTypes *data = evbind_object(e, StructTypes);
    Layout *layout = event_sender(e, Layout);
    cassert(event_type(e) == ekGUI_EVENT_OBJCHANGE);

    if (evbind_modify(e, StructTypes, Vector, vec1) == TRUE)
    {
        app_update_drawing(app);
        data->length1 = i_vec_length(&data->vec1);
        layout_dbind_update(layout, StructTypes, real32_t, length1);
    }
}

layout_dbind(layout, listener(app, i_OnDataChange, App), StructTypes);

If, for some reason, the modified value is not allowed by the application, it can be reverted by returning FALSE as a result of the event (Listing 13).

Listing 13: Canceling changes made by the user.
static void i_OnDataChange(App *app, Event *e)
{
    StructTypes *data = evbind_object(e, StructTypes);
    Layout *layout = event_sender(e, Layout);

    if (evbind_modify(e, StructTypes, Vector, vec1) == TRUE)
    {
        real32_t length = i_vec_length(&data->vec1);
        if (length < 5.f)
        {
            app_update_drawing(app);
            data->length1 = length;
            layout_dbind_update(layout, StructTypes, real32_t, length1);
        }
        else
        {
            // This will REVERT the changes in 'vec1' variable
            bool_t *res = event_result(e, bool_t);
            *res = FALSE;
        }
    }
}
❮ Back
Next ❯