gp_widget_table.h File Reference

A table widget. More...

Go to the source code of this file.

Data Structures
struct	gp_widget_table_cell
	A table cell content. More...
struct	gp_widget_table_col_desc
	A table column description. More...
struct	gp_widget_table_col_ops
	Table operations, defined by the application. More...
struct	gp_widget_table_header
	A table column header. More...
struct	gp_widget_table_col_size
	Cached column size and minimal size, used internally by the widget. More...
struct	gp_widget_table_priv
	A structure to store data for the users of this widget. More...

Typedefs
typedef struct gp_widget_table_cell	gp_widget_table_cell
	A table cell content.
typedef struct gp_widget_table_col_desc	gp_widget_table_col_desc
	A table column description.
typedef struct gp_widget_table_col_ops	gp_widget_table_col_ops
	Table operations, defined by the application.
typedef struct gp_widget_table_header	gp_widget_table_header
	A table column header.
typedef struct gp_widget_table_col_size	gp_widget_table_col_size
	Cached column size and minimal size, used internally by the widget.
typedef struct gp_widget_table_priv	gp_widget_table_priv
	A structure to store data for the users of this widget.

Enumerations
enum	gp_widget_table_row_op { GP_TABLE_ROW_RESET , GP_TABLE_ROW_ADVANCE , GP_TABLE_ROW_MAX }
	Table row operation. More...
enum	gp_widget_table_event_type { GP_WIDGET_TABLE_TRIGGER , GP_WIDGET_TABLE_SELECT }
	A gp_widget_event::sub_type for a table widget. More...

Functions
gp_widget *	gp_widget_table_new (unsigned int cols, unsigned int min_rows, const gp_widget_table_col_ops *col_ops, const gp_widget_table_header *header)
	Creates a new table widget.
void	gp_widget_table_sort_by (gp_widget *self, int desc, unsigned int col)
	Sorts a table widget by a column.
void	gp_widget_table_refresh (gp_widget *self)
	Request table widget refres.
void	gp_widget_table_off_set (gp_widget *self, unsigned int off)
	Sets first row that should be shown by the table.
void	gp_widget_table_sel_set (gp_widget *self, unsigned int row)
	Sets selected row.
unsigned int	gp_widget_table_sel_get (gp_widget *self)
	Gets a selected row.
bool	gp_widget_table_sel_has (gp_widget *self)
	Returns if table has a fow selected.
gp_widget_table_priv *	gp_widget_table_priv_get (gp_widget *self)
	Returns a pointer to user data.

Detailed Description

A table widget.

The table content is not stored in the widget, instead there are callbacks that are called to get the cells content when table is being rendered.

Table example

//SPDX-License-Identifier: LGPL-2.0-or-later
 
/*
 
   Copyright (c) 2021-2023 Cyril Hrubis <metan@ucw.cz>
 
 */
 
#include <widgets/gp_widgets.h>
 
#define TABLE_ROWS 4
 
static const char *const table_data[TABLE_ROWS][3] = {
        {"Apple", "Yes", "1"},
        {"Banana", "Yes", "2"},
        {"Orange", "Yes", "3"},
        {"Dog", "No", "4"}
};
 
enum tbl_ids {
        OBJECT,
        IS_FRUIT,
        NUMBER,
};
 
static int tbl_seek_row(gp_widget *self, int op, unsigned int pos)
{
        gp_widget_table_priv *tbl_priv = gp_widget_table_priv_get(self);
 
        switch (op) {
        case GP_TABLE_ROW_RESET:
                tbl_priv->row_idx = 0;
        break;
        case GP_TABLE_ROW_ADVANCE:
                tbl_priv->row_idx += pos;
        break;
        case GP_TABLE_ROW_MAX:
                return TABLE_ROWS;
        }
 
        if (tbl_priv->row_idx >= TABLE_ROWS)
                return 0;
 
        return 1;
}
 
static int tbl_get_cell(gp_widget *self, gp_widget_table_cell *cell, unsigned int col_id)
{
        gp_widget_table_priv *tbl_priv = gp_widget_table_priv_get(self);
 
        switch (col_id) {
        case OBJECT:
                cell->text = table_data[tbl_priv->row_idx][0];
        break;
        case IS_FRUIT:
                cell->text = table_data[tbl_priv->row_idx][1];
        break;
        case NUMBER:
                cell->text = table_data[tbl_priv->row_idx][2];
        break;
        }
 
        return 1;
}
 
const gp_widget_table_col_ops table_col_ops = {
        .seek_row = tbl_seek_row,
        .get_cell = tbl_get_cell,
        .col_map = {
                {.id = "object", .idx = OBJECT},
                {.id = "is_fruit", .idx = IS_FRUIT},
                {.id = "number", .idx = NUMBER},
                {}
        }
};
 
int table_on_event(gp_widget_event *ev)
{
        if (ev->type != GP_WIDGET_EVENT_WIDGET)
                return 0;
 
        printf("Selected row %u\n", gp_widget_table_sel_get(ev->self));
 
        return 1;
}
 
gp_app_info app_info = {
        .name = "Table Example",
        .desc = "Table widget OPS example",
        .version = "1.0",
        .license = "GPL-2.0-or-later",
        .url = "http://gfxprim.ucw.cz",
        .authors = (gp_app_info_author []) {
                {.name = "Cyril Hrubis", .email = "metan@ucw.cz", .years = "2021-2023"},
                {}
        }
};
 
int main(int argc, char *argv[])
{
        gp_widget *layout = gp_widget_layout_json("table_example.json", NULL, NULL);
        if (!layout)
                return 0;
 
        gp_widgets_main_loop(layout, NULL, argc, argv);
 
        return 0;
}

{
 "info": {"version": 1, "license": "GPL-2.0-or-later"},
 "layout": {
  "widgets": [
   {
    "type": "table",
    "min_rows": 4,
    "col_ops": "table_col_ops",
    "on_event": "table_on_event",
    "header": [
     {"label": "Object", "min_size": 8, "id": "object"},
     {"label": "Fruit?", "min_size": 3, "id": "is_fruit"}
    ]
   }
  ]
 }
}

Table JSON attributes

Attribute	Type	Default	Description
col_ops	string		An column ops id.
header	array		Array of table header objects.
min_rows	uint		Minimal number of table rows.

Table Header JSON attributes

Attribute	Type	Default	Description
fill	uint	0	Column fill coeficient.
id	string		Column id to match againts gp_widget_table_col_desc::id.
label	string		If set it's the the column header label.
min_size	uint		Minimal column width in text letters.
order	string		If column is sortable it can be sorted as asc or desc.
tattr	string	bold	Column header label text attribute see gp_widget_tattr.

Definition in file gp_widget_table.h.

Typedef Documentation

gp_widget_table_col_desc

typedef struct gp_widget_table_col_desc gp_widget_table_col_desc

A table column description.

Describes:

• An human readable id to index mapping, the human readable id is used by the widget JSON parser to match the column in the table header.
• Sortable flag, set if column could be sorted by gp_widget_table_col_ops::sort()

gp_widget_table_col_ops

typedef struct gp_widget_table_col_ops gp_widget_table_col_ops

Table operations, defined by the application.

This defines operations for all possible columns in the table. The table header then chooses which columns to display based on this description.

gp_widget_table_header

typedef struct gp_widget_table_header gp_widget_table_header

A table column header.

Defines a single widget column that is shown on the screen. The table that is shown in the widget is described by an array of these entries.

Enumeration Type Documentation

gp_widget_table_event_type

enum gp_widget_table_event_type

A gp_widget_event::sub_type for a table widget.

Enumerator
GP_WIDGET_TABLE_TRIGGER	Emitted on enter or double click presseed.
GP_WIDGET_TABLE_SELECT	Emitted when table entry is selected.

Definition at line 242 of file gp_widget_table.h.

gp_widget_table_row_op

enum gp_widget_table_row_op

Table row operation.

Enumerator
GP_TABLE_ROW_RESET	Sets current row to 0, i.e. the first row in the table.
GP_TABLE_ROW_ADVANCE	Moves the current row forward. Moves the current row by the op parameter elements forward. Returns non-zero if resulting row is valid and zero if not.
GP_TABLE_ROW_MAX	Returns the number of table rows. Returns the number of rows in a table i.e. max_index + 1. May return -1 if the size is unknown.

Definition at line 47 of file gp_widget_table.h.

Function Documentation

gp_widget_table_new()

gp_widget * gp_widget_table_new	(	unsigned int	cols,
		unsigned int	min_rows,
		const gp_widget_table_col_ops *	col_ops,
		const gp_widget_table_header *	header
	)

Creates a new table widget.

Parameters

cols	A number of table columns.
min_rows	A minimal number of rows shown in the widget.
col_ops	Columns description and callbacks to get retrieve table cells.
header	Description on which rows and in which order should be shown in the widget.

Returns

A newly allocated and initialid table widget.

gp_widget_table_off_set()

void gp_widget_table_off_set	(	gp_widget *	self,
		unsigned int	off
	)

Sets first row that should be shown by the table.

Parameters

self	A table widget.
off	A row offset.

gp_widget_table_priv_get()

gp_widget_table_priv * gp_widget_table_priv_get

(

gp_widget *

self

)

Returns a pointer to user data.

Parameters

self	A table widget.

Returns

A pointer to user data storage for the iterator based API.

gp_widget_table_refresh()

void gp_widget_table_refresh

(

gp_widget *

self

)

Request table widget refres.

Application calls this when table content has changed and table needs to be rerendered.

Parameters

self	A table widget.

gp_widget_table_sel_get()

unsigned int gp_widget_table_sel_get

(

gp_widget *

self

)

Gets a selected row.

Return valid result only if a row is selected, i.e. gp_widget_table_sel_has() returns True.

Parameters

self	A table widget.

Returns

A selected row index.

gp_widget_table_sel_has()

bool gp_widget_table_sel_has

(

gp_widget *

self

)

Returns if table has a fow selected.

Parameters

self	A table widget.

Returns

True if table has a selected row.

gp_widget_table_sel_set()

void gp_widget_table_sel_set	(	gp_widget *	self,
		unsigned int	row
	)

Sets selected row.

Parameters

self	A table widget.
row	A row to be selected.

gp_widget_table_sort_by()

void gp_widget_table_sort_by	(	gp_widget *	self,
		int	desc,
		unsigned int	col
	)

Sorts a table widget by a column.

This only works for a sortable columns, if column is not sortable the call is no-op.

Parameters

self	A table widget.
desc	If non-zero the table is sorted in descending order.
col	A column index to sort the table by.