2D bitmap graphics library with emphasis on speed and correctness
No Matches
Data Structures | Typedefs | Enumerations | Functions
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...


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.


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...


gp_widgetgp_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.

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 <>
#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 {
static int tbl_seek_row(gp_widget *self, int op, unsigned int pos)
switch (op) {
self->tbl->row_idx = 0;
self->tbl->row_idx += pos;
return TABLE_ROWS;
if (self->tbl->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)
unsigned int row = self->tbl->row_idx;
switch (col_id) {
case OBJECT:
cell->text = table_data[row][0];
case IS_FRUIT:
cell->text = table_data[row][1];
case NUMBER:
cell->text = table_data[row][2];
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)
return 0;
printf("Selected row %u\n", ev->self->tbl->selected_row);
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 = "",
.authors = (gp_app_info_author []) {
{.name = "Cyril Hrubis", .email = "", .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;
Widget specific event.
gp_widget * gp_widget_layout_json(const char *fname, const gp_widget_json_callbacks *const callbacks, gp_htable **uids)
Loads a widget layout given a path to a JSON layout description.
void gp_widgets_main_loop(struct gp_widget *layout, void(*init)(int argc, char *argv[]), int argc, char *argv[]) __attribute__((noreturn))
Widgets main loop.
Sets current row to 0, i.e. the first row in the table.
Returns the number of table rows.
Moves the current row forward.
Description of the app author.
Definition gp_app_info.h:31
An application information.
Definition gp_app_info.h:64
const char * name
Application name.
Definition gp_app_info.h:66
Event structure passed to widget event handler.
gp_widget * self
The widget the event is for.
uint16_t type
An event type, enum gp_widget_event_type.
A table cell content.
const char * text
An utf8 string.
Table operations, defined by the application.
int(* seek_row)(gp_widget *self, int op, unsigned int pos)
Seek function for the table rows.
A widget base.
Definition gp_widget.h:28
"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

A table column description.


  • 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

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

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

A gp_widget_event::sub_type for a table widget.


Emitted on enter or double click presseed.


Emitted when table entry is selected.

Definition at line 226 of file gp_widget_table.h.

◆ gp_widget_table_row_op

Table row operation.


Sets current row to 0, i.e. the first row in the table.


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.


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.

colsA number of table columns.
min_rowsA minimal number of rows shown in the widget.
col_opsColumns description and callbacks to get retrieve table cells.
headerDescription on which rows and in which order should be shown in the widget.
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.

selfA table widget.
offA row offset.

◆ 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.

selfA table widget.

◆ gp_widget_table_sel_set()

void gp_widget_table_sel_set ( gp_widget self,
unsigned int  row 

Sets selected row.

selfA table widget.
rowA 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.

selfA table widget.
descIf non-zero the table is sorted in descending order.
colA column index to sort the table by.