A grid to position widgets. More...

#include <stdint.h>

Enumerations
enum	gp_widget_grid_flags { GP_WIDGET_GRID_FRAME = 0x01 , GP_WIDGET_GRID_UNIFORM = 0x02 }
	A widget grid flags. More...

Functions
gp_widget *	gp_widget_grid_new (unsigned int cols, unsigned int rows, enum gp_widget_grid_flags flags)
	Allocates and initializes a widget grid.

gp_widget *	gp_widget_grid_put (gp_widget self, unsigned int col, unsigned int row, gp_widget child)
	Puts a child widget into a frame widget.

gp_widget *	gp_widget_grid_rem (gp_widget *self, unsigned int col, unsigned int row)
	Removes child widget at col, row from a grid.

gp_widget *	gp_widget_grid_get (gp_widget *self, unsigned int col, unsigned int row)
	Returns a pointer to a widget at col, row.

static void	gp_widget_grid_del (gp_widget *self, unsigned col, unsigned int row)
	Deletes a child widget at col, row from a grid.

void	gp_widget_grid_rows_ins (gp_widget *self, unsigned int row, unsigned int rows)
	Inserts new (empty) rows to the grid.

static void	gp_widget_grid_row_ins (gp_widget *self, unsigned int row)
	Inserts new (empty) row to the grid.

unsigned int	gp_widget_grid_rows_append (gp_widget *self, unsigned int rows)
	Appends a new (empty) rows at the bottom of the grid.

static unsigned int	gp_widget_grid_row_append (gp_widget *self)
	Appends a new (empty) row at the bottom of the grid.

void	gp_widget_grid_rows_prepend (gp_widget *self, unsigned int rows)
	Prepends a new (empty) rows at the top of the grid.

static void	gp_widget_grid_row_prepend (gp_widget *self)
	Prepends a new (empty) row at the top of the grid.

void	gp_widget_grid_rows_del (gp_widget *self, unsigned int row, unsigned int rows)
	Delete rows from the grid.

static void	gp_widget_grid_row_del (gp_widget *self, unsigned int row)
	Removes row from the grid.

void	gp_widget_grid_cols_ins (gp_widget *self, unsigned int col, unsigned int cols)
	Inserts new (empty) columns to the grid.

static void	gp_widget_grid_col_ins (gp_widget *self, unsigned int col)
	Inserts new (empty) column to the grid.

unsigned int	gp_widget_grid_cols_append (gp_widget *self, unsigned int cols)
	Appends a new (empty) colums at the right side of the grid.

static unsigned int	gp_widget_grid_col_append (gp_widget *self)
	Appends a new (empty) colum at the right side of the grid.

void	gp_widget_grid_cols_prepend (gp_widget *self, unsigned int cols)
	Prepends a new (empty) columns at the left side of the grid.

static void	gp_widget_grid_col_prepend (gp_widget *self)
	Prepends a new (empty) column at the left side of the grid.

void	gp_widget_grid_cols_del (gp_widget *self, unsigned int col, unsigned int cols)
	Delete columns from the grid.

static void	gp_widget_grid_col_del (gp_widget *self, unsigned int col)
	Delete column from the grid.

void	gp_widget_grid_border_set (gp_widget *self, enum gp_widget_border border, int padd, int fill)
	Sets border padd or fill coeficients.

static void	gp_widget_grid_no_border (gp_widget *self)
	Disables grid padd and fill.

void	gp_widget_grid_col_fill_set (gp_widget *self, unsigned int col, uint8_t fill)
	Sets grid cell column fill coeficient.

void	gp_widget_grid_row_fill_set (gp_widget *self, unsigned int row, uint8_t fill)
	Sets grid cell row fill coeficient.

Detailed Description

A grid to position widgets.

By far the most complex widget is the grid widget which is basically a table to organize widgets.

Grid widget distributes the space into columns and rows, i.e. all cells in a given row have the same height as well as all cells in a given column have the same width. The grid can have border around it and padding between cells. The border and padding consists of a constant part called padd and resizable part called fill. The constant padding is accounted for in the grid widget minimal size, while the resizable fill is accounted for when leftover space is being distributed.

Note: See gp_widget_hvbox.h for one dimensional variants.

Grid JSON Example

{
 "info": {"version": 1, "license": "GPL-2.0-or-later"},
 "layout": {
  "cols": 2, "rows": 3,
  "align": "fill",
  "cfill": "2 * 1",
  "rfill": "1, 2, 1",
  "widgets": [
   {
    "align": "fill",
    "widgets": [
     {"type": "button", "label": "right-bottom", "halign": "right", "valign": "bottom"}
    ]
   },
   {"type": "button", "label": "left-bottom", "halign": "left", "valign": "bottom"},
   {"type": "button", "label": "left-top", "halign": "left", "valign": "top"},
   {"type": "button", "label": "right-top", "halign": "right", "valign": "top"},
   {"type": "button", "label": "fill", "align": "fill"},
   {"type": "button", "label": "vfill-right", "halign": "right", "valign": "fill"}
  ]
 }
}

Note: Pass '-d layout' on application command line to highlight grid columns and rows.

Grid JSON attributes

Attribute	Type	Default	Description
cols	uint	`1`	Number of columns.
rows	uint	`1`	Number of rows.
border	string	all `1`	See below.
cpad	string	all `1`	Horizontal border and padding size multiples.
rpad	string	all `1`	Vertical border and padding size multiples.
cpadf	string	all `0`	Horizontal border and padding fill coeficients.
rpadf	string	all `0`	Vertical border and padding fill coeficients.
cfill	string	all `1`	Horizontal cell fill coeficients.
rfill	string	all `1`	Vertical cell fill coeficients.
pad	uint	`1`	Horizontal and vertical padding size multiples.
frame	bool	false	Draws frame around grid.
uniform	bool	false	The minimal sizes are distributed uniformly.
widgets	array		Array of `cols` * `rows` widget objects.

The pad attribute is set before the cpad and rpad.

Border

The boder can be one of none, all, horiz, vert, top, bottom, left, right and can be combined with "border": uint.

Border examples

JSON border	Description
"border": "none"	Sets all border padds to 0
"border": 4	Sets all border padds to 4.
"border": "vert"	Sets vertical border to 1 and clears horizontal border.
"border": top, "border": 4	Sets top border to 4 clears rest of the borders.

Padding and fill

Numbers are divided with comma (,)
Repetition can be done with number and asterisk (*)

For example 1, 1, 1 is the same as 3 * 1

Definition in file gp_widget_grid.h.

Enumeration Type Documentation

◆ gp_widget_grid_flags

enum gp_widget_grid_flags

A widget grid flags.

Enumerator
GP_WIDGET_GRID_FRAME	Draw a frame around the grid
GP_WIDGET_GRID_UNIFORM	Make the cells uniform i.e. all cells have the same size

Definition at line 89 of file gp_widget_grid.h.

Function Documentation

◆ gp_widget_grid_border_set()

void gp_widget_grid_border_set	(	gp_widget *	self,
		enum gp_widget_border	border,
		int	padd,
		int	fill
	)

Sets border padd or fill coeficients.

Parameters

self	A grid widget.
border	Which border(s) are set.
padd	Padding coeficient no change on -1 clamped to 255.
fill	A filling coeficient no change on -1 clamped to 255.

Referenced by gp_widget_grid_no_border().

◆ gp_widget_grid_col_append()

static unsigned int gp_widget_grid_col_append ( gp_widget * self )

inlinestatic

Appends a new (empty) colum at the right side of the grid.

Parameters

self	A grid widget.

Returns: A column index to the appended column.

Definition at line 325 of file gp_widget_grid.h.

References gp_widget_grid_cols_append().

◆ gp_widget_grid_col_del()

static void gp_widget_grid_col_del	(	gp_widget *	self,
		unsigned int	col
	)

inlinestatic

Delete column from the grid.

If there are any widgets in the deleted rows they are freed with gp_widget_free().

Parameters

self	A grid widget.
col	Where to delete column.

Definition at line 369 of file gp_widget_grid.h.

References gp_widget_grid_cols_del().

◆ gp_widget_grid_col_fill_set()

void gp_widget_grid_col_fill_set	(	gp_widget *	self,
		unsigned int	col,
		uint8_t	fill
	)

Sets grid cell column fill coeficient.

Sets cell column fill coeficient. When fill is set to 0 the respective column or row is always set to its minimal width. When greater than zero the coeficient describes how aggresively is any leftover space allocated, the higher the coeficient the more space is allocated. When grid is created all column and row fill coeficients are set to 1.

Parameters

self	A grid widget.
col	A column.
fill	A fill coeficient.

◆ gp_widget_grid_col_ins()

static void gp_widget_grid_col_ins	(	gp_widget *	self,
		unsigned int	col
	)

inlinestatic

Inserts new (empty) column to the grid.

Parameters

self	A grid widget.
col	Where to insert column.

Definition at line 303 of file gp_widget_grid.h.

References gp_widget_grid_cols_ins().

◆ gp_widget_grid_col_prepend()

static void gp_widget_grid_col_prepend ( gp_widget * self )

inlinestatic

Prepends a new (empty) column at the left side of the grid.

Parameters

self	A grid widget.

Definition at line 343 of file gp_widget_grid.h.

References gp_widget_grid_cols_prepend().

◆ gp_widget_grid_cols_append()

unsigned int gp_widget_grid_cols_append	(	gp_widget *	self,
		unsigned int	cols
	)

Appends a new (empty) colums at the right side of the grid.

Parameters

self	A grid widget.
cols	How many columns to append.

Returns: A column index to the first appended column.

Referenced by gp_widget_grid_col_append().

◆ gp_widget_grid_cols_del()

void gp_widget_grid_cols_del	(	gp_widget *	self,
		unsigned int	col,
		unsigned int	cols
	)

Delete columns from the grid.

If there are any widgets in the deleted columns they are freed with gp_widget_free().

Parameters

self	A grid widget.
col	Where to delete columns.
cols	How may columns to delete.

Referenced by gp_widget_grid_col_del().

◆ gp_widget_grid_cols_ins()

void gp_widget_grid_cols_ins	(	gp_widget *	self,
		unsigned int	col,
		unsigned int	cols
	)

Inserts new (empty) columns to the grid.

Parameters

self	A grid widget.
col	Where to insert columns.
cols	How many columns to insert.

Referenced by gp_widget_grid_col_ins().

◆ gp_widget_grid_cols_prepend()

void gp_widget_grid_cols_prepend	(	gp_widget *	self,
		unsigned int	cols
	)

Prepends a new (empty) columns at the left side of the grid.

Parameters

self	A grid widget.
cols	How many columns to append.

Referenced by gp_widget_grid_col_prepend().

◆ gp_widget_grid_del()

static void gp_widget_grid_del	(	gp_widget *	self,
		unsigned	col,
		unsigned int	row
	)

inlinestatic

Deletes a child widget at col, row from a grid.

Parameters

self	A grid widget.
col	Grid column.
row	Grid row.

Definition at line 195 of file gp_widget_grid.h.

References gp_widget_free(), and gp_widget_grid_rem().

◆ gp_widget_grid_get()

gp_widget * gp_widget_grid_get	(	gp_widget *	self,
		unsigned int	col,
		unsigned int	row
	)

Returns a pointer to a widget at col, row.

Parameters

self	A grid widget.
col	Grid column.
row	Grid row.

Returns: A child widget occupying the slot or NULL if it's empty.

◆ gp_widget_grid_new()

gp_widget * gp_widget_grid_new	(	unsigned int	cols,
		unsigned int	rows,
		enum gp_widget_grid_flags	flags
	)

Allocates and initializes a widget grid.

Both the cols and rows could be 0 as the grid can be resized later.

Parameters

cols	Number of grid columns.
rows	Number of grid rows.
flags	Bitwise or of the enum gp_widget_grid_flags.

Returns: A widget grid.

Referenced by gp_widget_hbox_new(), and gp_widget_vbox_new().

◆ gp_widget_grid_no_border()

static void gp_widget_grid_no_border ( gp_widget * self )

inlinestatic

Disables grid padd and fill.

Shortcut for gp_widget_grid_border_set(self, GP_WIDGET_BORDER_ALL, 0, 0).

Parameters

self	A grid widget.

Definition at line 393 of file gp_widget_grid.h.

References GP_WIDGET_BORDER_ALL, and gp_widget_grid_border_set().

◆ gp_widget_grid_put()

gp_widget * gp_widget_grid_put	(	gp_widget *	self,
		unsigned int	col,
		unsigned int	row,
		gp_widget *	child
	)

Puts a child widget into a frame widget.

Inserts a child widget at specified column and row into the grid and returns previous child occupying the slot. Passing a NULL child pointer makes the call equivalent to the gp_widget_grid_rem().

Parameters

self	A grid widget.
col	Grid column.
row	Grid row.
child	A child widget.

Returns: Previous child occupying the slot or NULL if it was empty.

◆ gp_widget_grid_rem()

gp_widget * gp_widget_grid_rem	(	gp_widget *	self,
		unsigned int	col,
		unsigned int	row
	)

Removes child widget at col, row from a grid.

Parameters

self	A grid widget.
col	Grid column.
row	Grid row.

Returns: A child widget removed from the slot or NULL if it was empty.

Referenced by gp_widget_grid_del().

◆ gp_widget_grid_row_append()

static unsigned int gp_widget_grid_row_append ( gp_widget * self )

inlinestatic

Appends a new (empty) row at the bottom of the grid.

Parameters

self	A grid widget.

Returns: A row index to the appended row.

Definition at line 239 of file gp_widget_grid.h.

References gp_widget_grid_rows_append().

◆ gp_widget_grid_row_del()

static void gp_widget_grid_row_del	(	gp_widget *	self,
		unsigned int	row
	)

inlinestatic

Removes row from the grid.

If there are any widgets in the deleted rows they are freed with gp_widget_free().

Parameters

self	A grid widget.
row	Where to delete row.

Definition at line 283 of file gp_widget_grid.h.

References gp_widget_grid_rows_del().

◆ gp_widget_grid_row_fill_set()

void gp_widget_grid_row_fill_set	(	gp_widget *	self,
		unsigned int	row,
		uint8_t	fill
	)

Sets grid cell row fill coeficient.

Sets cell row fill coeficient. When fill is set to 0 the respective column or row is always set to its minimal height. When greater than zero the coeficient describes how aggresively is any leftover space allocated, the higher the coeficient the more space is allocated. When grid is created all column and row fill coeficients are set to 1.

Parameters

self	A grid widget.
row	A row.
fill	A fill coeficient.

◆ gp_widget_grid_row_ins()

static void gp_widget_grid_row_ins	(	gp_widget *	self,
		unsigned int	row
	)

inlinestatic

Inserts new (empty) row to the grid.

Parameters

self	A grid widget.
row	Where to insert row.

Definition at line 217 of file gp_widget_grid.h.

References gp_widget_grid_rows_ins().

◆ gp_widget_grid_row_prepend()

static void gp_widget_grid_row_prepend ( gp_widget * self )

inlinestatic

Prepends a new (empty) row at the top of the grid.

Parameters

self	A grid widget.

Definition at line 257 of file gp_widget_grid.h.

References gp_widget_grid_rows_prepend().

◆ gp_widget_grid_rows_append()

unsigned int gp_widget_grid_rows_append	(	gp_widget *	self,
		unsigned int	rows
	)

Appends a new (empty) rows at the bottom of the grid.

Parameters

self	A grid widget.
rows	How many rows to append.

Returns: A row index to the first appended row.

Referenced by gp_widget_grid_row_append().

◆ gp_widget_grid_rows_del()

void gp_widget_grid_rows_del	(	gp_widget *	self,
		unsigned int	row,
		unsigned int	rows
	)

Delete rows from the grid.

If there are any widgets in the deleted rows they are freed with gp_widget_free().

Parameters

self	A grid widget.
row	Where to delete rows.
rows	How may rows to delete.

Referenced by gp_widget_grid_row_del().

◆ gp_widget_grid_rows_ins()

void gp_widget_grid_rows_ins	(	gp_widget *	self,
		unsigned int	row,
		unsigned int	rows
	)

Inserts new (empty) rows to the grid.

Parameters

self	A grid widget.
row	Where to insert rows.
rows	How many rows to insert.

Referenced by gp_widget_grid_row_ins().

◆ gp_widget_grid_rows_prepend()

void gp_widget_grid_rows_prepend	(	gp_widget *	self,
		unsigned int	rows
	)

Prepends a new (empty) rows at the top of the grid.

Parameters

self	A grid widget.
rows	How many rows to append.

Referenced by gp_widget_grid_row_prepend().

Enumerations

Functions

Detailed Description

Grid JSON Example

Grid JSON attributes

Border

Border examples

Padding and fill

Enumeration Type Documentation

◆ gp_widget_grid_flags

Function Documentation

◆ gp_widget_grid_border_set()

◆ gp_widget_grid_col_append()

◆ gp_widget_grid_col_del()

◆ gp_widget_grid_col_fill_set()

◆ gp_widget_grid_col_ins()

◆ gp_widget_grid_col_prepend()

◆ gp_widget_grid_cols_append()

◆ gp_widget_grid_cols_del()

◆ gp_widget_grid_cols_ins()

◆ gp_widget_grid_cols_prepend()

◆ gp_widget_grid_del()

◆ gp_widget_grid_get()

◆ gp_widget_grid_new()

◆ gp_widget_grid_no_border()

◆ gp_widget_grid_put()

◆ gp_widget_grid_rem()

◆ gp_widget_grid_row_append()

◆ gp_widget_grid_row_del()

◆ gp_widget_grid_row_fill_set()

◆ gp_widget_grid_row_ins()

◆ gp_widget_grid_row_prepend()

◆ gp_widget_grid_rows_append()

◆ gp_widget_grid_rows_del()

◆ gp_widget_grid_rows_ins()

◆ gp_widget_grid_rows_prepend()