TableView

This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Functions

Element under construction. It will be available in future versions of the SDK. API functions might change.

The TableView are controls that display tabulated information organized in rows and columns (Figure 1), (Figure 2), (Figure 3). The control enables scroll bars when needed and allows keyboard navigation. In Hello TableView! you have an example of use.

• Use tableview_create to create a table control.
• Use tableview_new_column_text to add a text column.
• Use tableview_column_width to set the width of the column.

1. Column types

TODO

2. Data connection

Let's think that a table can contain thousands of records and these can change at any time from the data sources of the application. For this reason, the TableView will not store any data locally. It has been designed with the aim of displaying information in the most optimized and fast way possible.

• Use tableview_OnNotify to link the table with the application.
• Use tableview_data_update to update the table data.

When the table must draw its content, it will send the application an event of the type ekEVTBLNROWS in order to correctly size the internal space of the control, as well as its scroll bars (Figure 4). Subsequently, it will launch successive ekEVTBLCELL events so that the application sends the content of each (Figure 5) cell. All these events will be sent through the callback function assigned in tableview_OnNotify (Listing 1).

TableView will only request the content of the visible part at a time.

It is the responsibility of the application to create a data cache if necessary. The response to the TableView must be very fast to avoid delays in drawing the data..

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

static void i_OnTableNotify(App *app, Event *e)
{
    uint32_t etype = event_type(e);
    unref(app);

    switch(etype) {
    case ekEVTBLNROWS:
    {
        uint32_t *n = event_result(e, uint32_t);
        *n = app_num_rows(app);
        break;
    }

    case ekEVTBLCELL:
    {
        const EvTbPos *pos = event_params(e, EvTbPos);
        EvTbCell *cell = event_result(e, EvTbCell);

        switch(pos->col) {
        case 0:
            cell->text = app_text_column0(app, pos->row);
            break;

        case 1:
            cell->text = app_text_column1(app, pos->row);
            break;

        case 2:
            cell->text = app_text_column2(app, pos->row);
            break;
        }

        break;
    }

    }
}
...

TableView *table = tableview_create();
tableview_OnNotify(table, listener(app, i_OnTableNotify, App));
...
tableview_data_update(table);

3. Table notifications

All communication between the application and the TableView will be done through a callback (or listener) function, assigned through the tableview_OnNotify function. Below are all the types of events that can be fired by the (Table 1) control.

tableview_create ()

Create a new table control.

TableView*
tableview_create(void);

Return

The TableView.

tableview_OnNotify ()

Sets a handler for table-application communication.

void
tableview_OnNotify(TableView *view,
                   Listener *listener);

Remarks

See Table notifications.

tableview_size ()

Set the default size of the table control.

void
tableview_size(TableView *view,
               const S2Df size);

Remarks

Corresponds to the Natural sizing of the control. Default 256x128.

tableview_new_column_text ()

Add a new column to the table.

uint32_t
tableview_new_column_text(void);

Return

The column identifier (index).

Remarks

See Column types.

tableview_column_width ()

Sets the width of a column.

void
tableview_column_width(TableView *view,
                       const uint32_t column_id,
                       const real32_t width);

tableview_header_font ()

Sets the font for the table header.

void
tableview_header_font(TableView *view,
                      const Font *font);

tableview_header_title ()

Sets the header text of a column.

void
tableview_header_title(TableView *view,
                       const uint32_t column_id,
                       const char_t *text);

tableview_header_align ()

Sets the alignment of the header text.

void
tableview_header_align(TableView *view,
                       const uint32_t column_id,
                       const align_t align);

tableview_data_update ()

Synchronize the table with the data source.

void
tableview_data_update(TableView *view);

Remarks

We will have to call this function from the application whenever the data linked to the table changes, in order to update the view. See Data connection.