gp_widget_grid.h File Reference

A grid to position widgets. More...

#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	gp_widget_grid_gap
	Describes a row or a column border or a gap between cells. More...

Typedefs
typedef struct gp_widget_grid_gap	gp_widget_grid_gap
	Describes a row or a column border or a gap between cells.

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.
unsigned int	gp_widget_grid_cols_get (gp_widget *self)
	Returns number of grid columns.
unsigned int	gp_widget_grid_rows_get (gp_widget *self)
	Returns number of grid rows.
const gp_widget_grid_gap *	gp_widget_grid_cols_gaps_get (gp_widget *self)
	Returns a widget grid horizontal borders.
const gp_widget_grid_gap *	gp_widget_grid_rows_gaps_get (gp_widget *self)
	Returns a widget grid vertical borders.
enum gp_widget_grid_flags	gp_widget_grid_flags_get (gp_widget *self)
void	gp_widget_grid_flags_set (gp_widget *self, enum gp_widget_grid_flags flags)
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 375 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 419 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 353 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 393 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_gaps_get()

const gp_widget_grid_gap * gp_widget_grid_cols_gaps_get

(

gp_widget *

self

)

Returns a widget grid horizontal borders.

Returns a pointer to an array that describes the outher border and gaps between grid cells.

The size of the array is columns + 1 and the first and last element of the array describes grid left and right border while the inner elements describe the gaps between columns.

Parameters

self	A grid widget.

Returns

An array of columns + 1.

gp_widget_grid_cols_get()

unsigned int gp_widget_grid_cols_get

(

gp_widget *

self

)

Returns number of grid columns.

Parameters

self	A grid widget.

Returns

A number of grid columns.

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 245 of file gp_widget_grid.h.

References gp_widget_free(), and gp_widget_grid_rem().

gp_widget_grid_flags_get()

enum gp_widget_grid_flags gp_widget_grid_flags_get

(

gp_widget *

self

)

Returns widget grid flags.

Parameters

self	A grid widget.

Returns

Widget grid flags.

gp_widget_grid_flags_set()

void gp_widget_grid_flags_set	(	gp_widget *	self,
		enum gp_widget_grid_flags	flags
	)

Sets widget grid flags.

Parameters

self	A grid widget.
flags	Widget grid flags.

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 443 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 289 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 333 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 267 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 307 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_gaps_get()

const gp_widget_grid_gap * gp_widget_grid_rows_gaps_get

(

gp_widget *

self

)

Returns a widget grid vertical borders.

Returns a pointer to an array that describes the outher border and gaps between grid cells.

The size of the array is rows + 1 and the first and last element of the array describes grid top and bottom border while the inner elements describe the gaps between rows.

Parameters

self	A grid widget.

Returns

An array of rows + 1.

gp_widget_grid_rows_get()

unsigned int gp_widget_grid_rows_get

(

gp_widget *

self

)

Returns number of grid rows.

Parameters

self	A grid widget.

Returns

A number of grid rows.

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