Navigation C API Pages Python bindings Applications

Grid widget

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

Grid widget distributes the space evenly, 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.

Grid widget constructor
enum gp_widget_grid_flags {
        /** Draw a frame around the grid */
        GP_WIDGET_GRID_FRAME = 0x01,
        /** Make the cells uniform i.e. same size */
        GP_WIDGET_GRID_UNIFORM = 0x02,
};

gp_widget *gp_widget_grid_new(unsigned int cols, unsigned int rows, int flags);

Creates a new grid widget, both the cols and rows could be 0 as the grid can be resized later.

The flags argument can be passed a bitwise or of the enum gp_widget_grid_flags.

Child widget manipulation

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

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

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

Returns a pointer to a child occupying slot at the column and row. If slot is empty NULL is returned.

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

Removes and returns a pointer to a child widget at the column and row.

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

Removes widget from the slot at the column and row and frees it with gp_widget_free().

Row manipulation

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

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

These two functions insert empty row(s) at a given offset to the grid.

Row indexes start at 0 and the last valid row index is self->grid->rows - 1.

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

unsigned int gp_widget_grid_row_append(gp_widget *self);

These two functions append empty row(s) at the bottom of the grid and return an index to the first appended row.

Prepending rows
void gp_widget_grid_rows_prepend(gp_widget *self, unsigned int rows);

void gp_widget_grid_row_prepend(gp_widget *self);

These two functions prepend empty row(s) at the top of the grid.

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

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

These two functions delete row(s) at given offset from the grid. All widgets in the deleted rows are freed recursively with gp_widget_free().

Row indexes start at 0 and the last valid row index is self->grid->rows - 1.

Column manipulation

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

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

These two functions insert empty column(s) at a given offset to the grid.

Column indexes start at 0 and the last valid column index is self->grid->cols - 1.

Appending columns
unsigned int gp_widget_grid_cols_append(gp_widget *self, unsigned int cols);

unsigned int gp_widget_grid_col_append(gp_widget *self);

These two functions append empty column(s) at the right side of the grid and return an index to the first appended column.

Prepending columns
void gp_widget_grid_cols_prepend(gp_widget *self, unsigned int cols);

void gp_widget_grid_col_prepend(gp_widget *self);

These two functions prepend empty column(s) at the left side of the grid.

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

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

These two functions delete column(s) at given offset from the grid. All widgets in the deleted columns are freed recursively with gp_widget_free().

Column indexes start at 0 and the last valid column index is self->grid->cols - 1.

Border padding and fill

void gp_widget_grid_border_set(gp_widget *self, unsigned int padd, unsigned int fill);

void gp_widget_grid_hborder_set(gp_widget *self, unsigned int padd, unsigned int fill);

void gp_widget_grid_vborder_set(gp_widget *self, unsigned int padd, unsigned int fill);

Sets a grid border padding and fill coeficients, most common usage is to make the grid borderless with passing 0 for both padd and fill.

See the detailed description below on padding and fill.

Grid JSON Example

Grid widget

{
 "version": 1,
 "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"
  }
 ]
}
Table 1. Grid JSON attributes
Attribute Type Default Description

cols

uint

1

Number of columns

rows

uint

1

Number of rows

border

string

all

Border one of horiz, vert, none, all.

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

json

cols * rows widgets.

The pad attribute is set before the cpad and rpad.

Padding and fill string

  • Numbers are divided with comma (,)

  • Repetition can be done with number and asterisk (*)

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