Cross-platform C SDK logo

Cross-platform C SDK

TableView

❮ Back
Next ❯
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

TableView*tableview_create (void)
voidtableview_OnNotify (...)
voidtableview_size (...)
uint32_ttableview_new_column_text (void)
voidtableview_column_width (...)
voidtableview_header_font (...)
voidtableview_header_title (...)
voidtableview_header_align (...)
voidtableview_data_update (...)

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.


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.

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..
Graphically displays the request event for the number of rows.
Figure 4: Request for the number of rows (data set).
Graphically display the request event in cells.
Figure 5: Request of the data of a cell.
Listing 1: Data connection example.
 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.

Table 1: List of all table events.
Event Type Parameters Response
Get the number of rows in the table ekEVTBLNROWS - uint32_t
Get the content of a cell ekEVTBLCELL EvTbPos EvTbCell
... ... ... ...

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);
view

The TableView.

listener

Callback function that will be called every time the application should be notified of some event on the table.

Remarks

See Table notifications.


tableview_size ()

Set the default size of the table control.

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

The TableView.

size

The 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);
view

The TableView.

column_id

The column identifier.

width

Column width.


tableview_header_font ()

Sets the font for the table header.

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

The TableView.

font

The 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);
view

The TableView.

column_id

The column identifier.

text

The text in UTF-8 or the identifier of the resource. Resources.


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);
view

The TableView.

column_id

The column identifier.

align

The alignment.


tableview_data_update ()

Synchronize the table with the data source.

void
tableview_data_update(TableView *view);
view

The TableView.

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.

❮ Back
Next ❯