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.

Header

#include <gui/tableview.h>

Functions

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

• Use tableview_create to create a table view.
• Use tableview_add_column_text to add a column.
• Use tableview_size to set the default size.

1. Tree mode

In addition to the conventional table mode, TableView supports a tree mode that allows displaying hierarchical data. In this mode, rows represent nodes of a tree that can be expanded or collapsed to show or hide their child nodes (Figure 4).

• Use tableview_tree to enable tree mode.

2. Data connection

Let's think that a table can contain thousands of records and these can change at any time from different data sources (disk, network, DBMS, etc). For this reason, the TableView will not maintain any internal cache. It has been designed with the aim of making a quick visualization of the data, but without going into their management. Ultimately, it is the application that must provide this information in a fluid manner.

• Use tableview_OnData to bind the table to the data source.
• Use tableview_update to force an update of the table data.

In table mode, when the table needs to draw its contents it will first ask for the total number of rows via ekGUI_EVENT_TBL_NROWS. With this it will calculate the size of the document and configure the scroll bars (Figure 5). Subsequently it will launch successive ekGUI_EVENT_TBL_CELL events, where it will ask for the content of each visible cell (Figure 6). The EvTbPos::row field indicates the row index. All these requests will be made through the callback function set in tableview_OnData (Listing 1).

In tree mode, ekGUI_EVENT_TBL_NROWS is replaced by ekGUI_EVENT_TBL_NROOTS, which asks for the number of root nodes. Then, for each visible node, the table will launch a ekGUI_EVENT_TBL_NODEINFO event where the application must provide the node pointer and the number of children it has. This process is incremental: only information about currently expanded nodes is requested. When the user expands or collapses a node, it is notified via ekGUI_EVENT_TBL_EXPAND. Finally, as in table mode, the content of the visible cells is requested via ekGUI_EVENT_TBL_CELL. In this case, the EvTbPos::node field will contain the pointer to the node of the row.

TableView will only ask for the content of the visible part at any time.

In tree mode, the application must maintain the state of each node (collapsed or expanded). The control does not cache this, it will only notify when the user expands or collapses a node.

 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
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

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

    switch(etype) {
    /* Only in table mode */
    case ekGUI_EVENT_TBL_NROWS:
    {
        uint32_t *n = event_result(e, uint32_t);
        *n = app_num_rows(app);
        break;
    }

    /* Only in tree mode */
    case ekGUI_EVENT_TBL_NROOTS:
    {
        uint32_t *n = event_result(e, uint32_t);
        *n = app_num_roots(app);
        break;
    }

    case ekGUI_EVENT_TBL_NODEINFO:
    {
        const EvTbNodeInfo *p = event_params(e, EvTbNodeInfo);
        EvTbNode *node = event_result(e, EvTbNode);
        node->node = app_get_child(app, p->node, p->child);
        node->children = app_num_children(app, node->node);
        break;
    }

    case ekGUI_EVENT_TBL_EXPAND:
    {
        const EvTbExpand *p = event_params(e, EvTbExpand);
        app_set_expanded(app, p->node, p->expanded);
        break;
    }

    /* Both modes, cell content */
    case ekGUI_EVENT_TBL_CELL:
    {
        const EvTbPos *pos = event_params(e, EvTbPos);
        EvTbCell *cell = event_result(e, EvTbCell);

        /* Table mode */
        if (pos->node == NULL)
        {
            cell->text = app_table_text(app, pos->col,pos->row);
        }
        /* Tree mode */
        else
        {
            cell->text = app_node_text(app, pos->node, pos->col);
        }

        break;
    }
}

TableView *table = tableview_create();
tableview_OnData(table, listener(app, i_OnTableData, App));
tableview_update(table);

3. Data cache

As we have already commented, at each instant the table will only show a small portion of the data set. In order to supply this data in the fastest possible way, the application can keep a cache with those that will be displayed next. To do this, before starting to draw the view, the table will send an ekGUI_EVENT_TBL_BEGIN type event where it will indicate the range of rows and columns that need updating (Figure 7). This event will precede any ekGUI_EVENT_TBL_CELL seen in the previous section. In the same way, once all the visible cells have been updated, the ekGUI_EVENT_TBL_END event will be sent, where the application will be able to free the resources in the cache (Listing 2).

 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

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

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

    case ekGUI_EVENT_TBL_BEGIN:
    {
        const EvTbRect *rect = event_params(e, EvTbRect);
        app->cache = app_fill_cache(app, rect->strow, rect->edrow, rect->stcol, rect->edcol);
        break;
    }

    case ekGUI_EVENT_TBL_CELL:
    {
        const EvTbPos *pos = event_params(e, EvTbPos);
        EvTbCell *cell = event_result(e, EvTbCell);
        cell->text = app_get_cache(app->cache, pos->row, pos->col);
        break;
    }

    case ekGUI_EVENT_TBL_END:
        app_delete_cache(app->cache);
        break;
}

TableView *table = tableview_create();
tableview_OnData(table, listener(app, i_OnTableData, App));
tableview_update(table);

4. Multiple selection

When we navigate through a TableView we can activate the multiple selection, which will allow us to mark more than one row of the table (Figure 8).

• Use tableview_multisel to turn multiselect on or off.
• Use tableview_selected to get the selected rows.
• Use tableview_select to select a set of rows.
• Use tableview_deselect to deselect.
• Use tableview_deselect_all to uncheck all rows.
• Use tableview_OnSelect to receive an event when the selection changes.

In tree mode, selection functions work with physical row indices, i.e., the position of the node in the visible list at any given time. Since this position can change when nodes are expanded or collapsed, it may be necessary to convert between index and node.

• Use tableview_node_row to get the current row index of a node.
• Use tableview_row_node to get the node pointer for a specific row.

5. Table navigation

Navigating a TableView works the same as other similar controls, such as the file explorer. We can use the keyboard when the table has focus. It will also respond to mouse events to select rows and move scroll bars.

• Use tableview_focus_row to move keyboard focus to a row.
• Use tableview_get_focus_row to get the row that has keyboard focus.
• Use tableview_hkey_scroll to set horizontal scrolling.
• [UP]/[DOWN] to move row by row.
• [LEFT]/[RIGHT] to scroll horizontally.
• [PAGEUP]/[PAGEDOWN] advance or reverse a page.
• [HOME] goes to the beginning of the table.
• [END] goes to the end of the table.
• [CTRL]+click multiple selection with the mouse.
• [SHIFT]+[UP]/[DOWN] multiple selection with the keyboard.
• [+]/[Numpad+] expands the focused node (tree mode only).
• [-]/[Numpad-] collapses the focused node (tree mode only).

In multiple selection, an automatic de-selection of the rows will occur whenever we click releasing [CTRL] or press any navigation key releasing [SHIFT]. If we want to navigate without losing the previous selection, we must activate the preserve flag in tableview_multisel.

6. Configure columns

We have different options to configure the interaction with the different columns of the table:

• Use tableview_header_title to set the title of a column. Multiple lines are accepted including '\n' characters (Figure 10).
• Use tableview_header_align to set the alignment of a column header.
• Use tableview_header_resizable to allow or disallow column resizing.
• Use tableview_column_width to set the width of a column.
• Use tableview_column_limits to set limits on the width.
• Use tableview_column_resizable to allow the column to be stretched or collapsed.
• Use tableview_column_freeze to freeze columns (Figure 9).
• Use tableview_column_icon to indicate that the column should draw an icon (Figure 11).

7. Notifications in tables

We have different events to capture actions that the user could perform on the (Listing 3) table.

• Use tableview_header_clickable to allow clicking on the header.
• Use tableview_OnRowClick to notify the click on a row.
• Use tableview_OnHeaderClick to notify the click on the header.

In tree mode, clicking on the expand/collapse marker does not trigger tableview_OnRowClick, it only expands or collapses the node. The event is received when clicking on any other part of the row. In that case, EvTbRow::row contains the physical row index; to get the node pointer use tableview_row_node.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

static void i_OnRowClick(App *app, Event *e)
{
    const EvTbRow *p = event_params(e, EvRow);
    on_row_click(app, p->row, p->sel);
}

static void i_OnHeaderClick(App *app, Event *e)
{
    const EvButton *p = event_params(e, EvButton);
    on_header_click(app, p->index);
}

tableview_OnRowClick(table, listener(app, i_OnRowClick, App));
tableview_OnHeaderClick(table, listener(app, i_OnRowClick, App));

8. Table appearance

There are different options to change the appearance of the table.

• Use tableview_font to change the font.
• Use tableview_header_visible to show or hide the header.
• Use tableview_scroll_visible to show or hide the scroll bars.
• Use tableview_grid to show or hide the inner lines (Figure 12), (Figure 13).
• Use tableview_header_height to force the header height.
• Use tableview_row_height to force the row height.

tableview_create ()

Creates a new table view.

TableView*
tableview_create(void);

Return

The table.

tableview_OnData ()

Sets up a handler to read data from the application.

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

Remarks

See Data connection.

tableview_OnSelect ()

Notifies that the selection has changed.

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

Remarks

See Multiple selection.

tableview_OnRowClick ()

Notify each time a row is clicked.

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

Remarks

See Notifications in tables.

tableview_OnHeaderClick ()

Notifies each time a header is clicked.

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

Remarks

See Notifications in tables.

tableview_font ()

Sets the general font for the entire table.

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

Remarks

See Table appearance.

tableview_size ()

Sets the default size of the table control.

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

Remarks

Corresponds to the Natural sizing of the control. By default 256x128.

tableview_add_column_text ()

Adds a new column to the table.

uint32_t
tableview_add_column_text(TableView *view);

Return

The column identifier (index).

Remarks

See Configure columns.

tableview_tree ()

Enables tree mode on the table.

void
tableview_tree(TableView *view,
               const uint32_t column_id);

Remarks

See Tree mode.

tableview_del_column ()

Deletes a column from the table.

void
tableview_del_column(TableView *view,
                     const uint32_t column_id);

tableview_column_count ()

Returns the number of columns in the table.

uint32_t
tableview_column_count(const TableView *view);

Return

The number of columns.

tableview_column_icon ()

Indicates that a column will display an icon.

void
tableview_column_icon(TableView *view,
                      const uint32_t column_id,
                      const real32_t icon_height,
                      const uint32_t hmargin);

Remarks

The column is ready to draw an icon together with the text. This icon must be sent in the const Image *EvTbCell::icon field in response to the ekGUI_EVENT_TBL_CELL event. It is not mandatory that all lines have icon, you can ignore the icon field or assign NULL.

tableview_column_width ()

Sets the width of a column.

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

Remarks

See Configure columns.

tableview_column_limits ()

Sets the size limits of a column.

void
tableview_column_limits(TableView *view,
                        const uint32_t column_id,
                        const real32_t min,
                        const real32_t max);

Remarks

See Configure columns.

tableview_column_align ()

Sets the default text alignment for the column data.

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

Remarks

See Configure columns.

tableview_column_resizable ()

Sets whether a column is resizable or not.

void
tableview_column_resizable(TableView *view,
                           const uint32_t column_id,
                           const bool_t resizable);

Remarks

See Configure columns.

tableview_column_freeze ()

Allows to freeze the first columns of the table. During horizontal movement they will remain fixed.

void
tableview_column_freeze(TableView *view,
                        const uint32_t last_column_id);

Remarks

See Configure columns.

tableview_header_title ()

Sets the text of a column header.

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

Remarks

See Configure columns.

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

Remarks

See Configure columns.

tableview_header_visible ()

Sets whether the table header is visible or not.

void
tableview_header_visible(TableView *view,
                         const bool_t visible);

Remarks

See Table appearance.

tableview_header_clickable ()

Sets whether the table header can be clicked as a button.

void
tableview_header_clickable(TableView *view,
                           const bool_t clickable);

Remarks

See Notifications in tables.

tableview_header_resizable ()

Sets whether the header allows column resizing.

void
tableview_header_resizable(TableView *view,
                           const bool_t resizable);

Remarks

See Configure columns.

tableview_header_height ()

Force the height of the header.

void
tableview_header_height(TableView *view,
                        const real32_t height);

Remarks

The height of the header is automatically calculated from the content. Forcing this value may cause the table to not display correctly. Its use is not recommended. See Table appearance.

tableview_row_height ()

Force the height of the row.

void
tableview_row_height(TableView *view,
                     const real32_t height);

Remarks

The row height is automatically calculated from the content. Forcing this value may cause the table to not display correctly. its use is not recommended. See Table appearance.

tableview_hkey_scroll ()

Sets the horizontal scrolling when pressing the [LEFT] and [RIGHT] keys.

void
tableview_hkey_scroll(TableView *view,
                      const bool_t force_column,
                      const real32_t scroll);

Remarks

See Table navigation.

tableview_multisel ()

Sets the row selection mode.

void
tableview_multisel(TableView *view,
                   const bool_t multisel,
                   const bool_t preserve);

Remarks

See Multiple selection.

tableview_grid ()

Sets the drawing of the interior lines.

void
tableview_grid(TableView *view,
               const bool_t hlines,
               const bool_t vlines);

Remarks

See Table appearance.

tableview_update ()

Synchronizes the table with the data source.

void
tableview_update(TableView *view);

Remarks

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

tableview_node_row ()

Gets the physical row index of a node in tree mode.

uint32_t
tableview_node_row(const TableView *view,
                   void *node);

Return

The row index. UINT32_MAX if the node is not visible or tree mode is not active.

Remarks

See Multiple selection.

tableview_row_node ()

Gets the node pointer for a specific row in tree mode.

void*
tableview_row_node(const TableView *view,
                   const uint32_t row);

Return

Pointer to the node. NULL if tree mode is not active.

Remarks

See Multiple selection.

tableview_select ()

Selects rows in the table.

void
tableview_select(TableView *view,
                 const uint32_t *rows,
                 const uint32_t n);

Remarks

See Multiple selection.

tableview_deselect ()

Deselects rows in the table.

void
tableview_deselect(TableView *view,
                   const uint32_t *rows,
                   const uint32_t n);

Remarks

See Multiple selection.

tableview_deselect_all ()

Deselects all rows in the table.

void
tableview_deselect_all(TableView *view);

Remarks

See Multiple selection.

tableview_selected ()

Returns the currently selected rows.

const ArrSt(uint32_t)*
tableview_selected(const TableView *view);

Return

Array with the indices of the selected rows.

Remarks

See Multiple selection.

tableview_focus_row ()

Set keyboard focus to a specific row.

void
tableview_focus_row(TableView *view,
                    const uint32_t row,
                    const align_t align);

Remarks

Setting keyboard focus to a row only has effects on navigation, but does not involve selecting the row. The table is automatically scrolled so that the row is visible. In this case, align indicates where the vertical scroll is adjusted (up, down or centered). See Table navigation.

tableview_get_focus_row ()

Gets the row that has keyboard focus.

uint32_t
tableview_get_focus_row(const TableView *view);

Return

The row that has the focus.

Remarks

See Table navigation.

tableview_scroll_visible ()

Show or hide scroll bars.

void
tableview_scroll_visible(TableView *view,
                         const bool_t horizontal,
                         const bool_t vertical);

Remarks

See Table appearance.