Data Structures
struct	N_GUI_GRID_CALLBACKS
	What the grid asks of its caller. More...

Functions
int	n_gui_grid_cell_rect (N_GUI_CTX ctx, int widget_id, size_t index, float x, float y, float w, float *h)
	Where a cell is on screen, whether or not it is scrolled into view.
int	n_gui_grid_columns (N_GUI_CTX *ctx, int widget_id)
	How many cells a row holds at the grid's width.
float	n_gui_grid_get_scroll (N_GUI_CTX *ctx, int widget_id)
	The scroll offset, in pixels from the top of the content.
int	n_gui_grid_index_at (N_GUI_CTX ctx, int widget_id, float x, float y, size_t index)
	Which cell is at a point on screen.
int	n_gui_grid_new (N_GUI_CTX ctx, int window_id, const N_GUI_GRID_CALLBACKS callbacks, void *user_data)
	Add a grid, and its scrollbar, to a window.
void	n_gui_grid_scroll_to (N_GUI_CTX *ctx, int widget_id, size_t index)
	Scroll the least that brings a cell's whole row into view.
int	n_gui_grid_scrollbar (N_GUI_CTX *ctx, int widget_id)
	The grid's scrollbar widget.
int	n_gui_grid_scrollbar_showing (N_GUI_CTX *ctx, int widget_id)
	Whether the scrollbar is shown, which is whether the rows overflow.
void	n_gui_grid_set_cell_size (N_GUI_CTX *ctx, int widget_id, float cell_w, float cell_h, float gap)
	Set the size of a cell and the gap around cells.
void	n_gui_grid_set_count (N_GUI_CTX *ctx, int widget_id, size_t count)
	Set how many cells there are.
void	n_gui_grid_set_rect (N_GUI_CTX *ctx, int widget_id, float x, float y, float w, float h, float bar_w)
	Place the grid and its scrollbar in a rectangle of the window.
void	n_gui_grid_set_scroll (N_GUI_CTX *ctx, int widget_id, float scroll)
	Set the scroll offset, clamped to the content.
void	n_gui_grid_set_visible (N_GUI_CTX *ctx, int widget_id, int visible)
	Show or hide the grid and its scrollbar together.

Detailed Description

Data Structure Documentation

◆ N_GUI_GRID_CALLBACKS

struct N_GUI_GRID_CALLBACKS

What the grid asks of its caller.

Only draw_cell is required.

Examples: ex_gui_grid.c.

Definition at line 69 of file n_gui_grid.h.

Collaboration diagram for N_GUI_GRID_CALLBACKS:

Data Fields
void()(int widget_id, float x, float y, float w, float h, void user_data)	draw_background	Draw behind the cells, over the whole grid, before any cell; with no cells, the only thing drawn. May be NULL.
void()(int widget_id, size_t index, float x, float y, float w, float h, void user_data)	draw_cell	Draw cell `index` in the box at x, y, w by h, on screen. The clipping rectangle is the grid's, so a cell partly scrolled off is cut there.
void()(int widget_id, size_t index, int button, float x, float y, void user_data)	press	A press of `button` (1 or 2) on cell `index`, at screen x, y. Not called for a press between cells or past the last. May be NULL.
void()(int widget_id, size_t first, size_t last, void user_data)	visible	Called after each draw with the cells drawn and one row beyond, first included and last excluded: what to have ready. May be NULL.
int()(int widget_id, int dz, int modifiers, void user_data)	wheel	A wheel turn of `dz` notches over the grid, positive away from the user, with the modifier keys held (ALLEGRO_KEYMOD_* ORed, see n_gui_get_key_modifiers()). Asked before the grid scrolls: return non-zero to take the turn, for a Ctrl+wheel zoom say, and the grid does not scroll; zero and it scrolls as usual. May be NULL.

Function Documentation

◆ n_gui_grid_cell_rect()

int n_gui_grid_cell_rect	(	N_GUI_CTX *	ctx,
		int	widget_id,
		size_t	index,
		float *	x,
		float *	y,
		float *	w,
		float *	h )

Where a cell is on screen, whether or not it is scrolled into view.

Parameters

ctx	the GUI context.
widget_id	the grid.
index	the cell.
x	receives its left. May be NULL.
y	receives its top. May be NULL.
w	receives its width. May be NULL.
h	receives its height. May be NULL.

Returns: TRUE when the cell exists and at least part of it is inside the grid, FALSE otherwise (the rectangle is still written).

Definition at line 411 of file n_gui_grid.c.

References _grid_columns_for(), _grid_of(), _grid_step(), _N_GUI_GRID::cell_h, _N_GUI_GRID::cell_w, _N_GUI_GRID::count, _N_GUI_GRID::gap, _N_GUI_GRID::inner_w, n_gui_widget_screen_rect(), and _N_GUI_GRID::scroll.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_columns()

int n_gui_grid_columns	(	N_GUI_CTX *	ctx,
		int	widget_id )

How many cells a row holds at the grid's width.

Parameters

ctx	the GUI context.
widget_id	the grid.

Returns: 1 or more, or 0 when widget_id is not a grid.

Definition at line 361 of file n_gui_grid.c.

References _grid_columns_for(), _grid_of(), and _N_GUI_GRID::inner_w.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_get_scroll()

float n_gui_grid_get_scroll	(	N_GUI_CTX *	ctx,
		int	widget_id )

The scroll offset, in pixels from the top of the content.

Parameters

ctx	the GUI context.
widget_id	the grid.

Returns: the offset, 0 when widget_id is not a grid.

Definition at line 367 of file n_gui_grid.c.

References _grid_of(), and _N_GUI_GRID::scroll.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_index_at()

int n_gui_grid_index_at	(	N_GUI_CTX *	ctx,
		int	widget_id,
		float	x,
		float	y,
		size_t *	index )

Which cell is at a point on screen.

Parameters

ctx	the GUI context.
widget_id	the grid.
x	screen x.
y	screen y.
index	receives the cell. Must not be NULL.

Returns: TRUE when a cell is there: the point is inside the grid, which is visible, and not past the last cell. A cell owns the gap to its right and the gap below it, and the last column owns whatever is left at the right edge, so there is no dead space between cells.

Definition at line 400 of file n_gui_grid.c.

References __n_assert, _grid_index_local(), _grid_of(), _N_GUI_GRID::count, n_gui_widget_screen_rect(), and _N_GUI_GRID::visible.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_new()

int n_gui_grid_new	(	N_GUI_CTX *	ctx,
		int	window_id,
		const N_GUI_GRID_CALLBACKS *	callbacks,
		void *	user_data )

Add a grid, and its scrollbar, to a window.

Both start at 16 by 16 pixels; place them with n_gui_grid_set_rect().

Parameters

ctx	the GUI context. Must not be NULL.
window_id	the window.
callbacks	what the grid asks; copied. draw_cell must not be NULL.
user_data	handed back to every callback.

Returns: the grid's widget id, or -1 on error. Its state is freed with it.

Definition at line 281 of file n_gui_grid.c.

References __n_assert, _grid_destroy(), _grid_draw(), _grid_mouse(), _grid_on_bar(), _N_GUI_GRID::bar, _N_GUI_GRID::bar_w, _N_GUI_GRID::cb, _N_GUI_GRID::cell_h, _N_GUI_GRID::cell_w, _N_GUI_GRID::ctx, N_GUI_GRID_CALLBACKS::draw_cell, _N_GUI_GRID::gap, _N_GUI_GRID::id, _N_GUI_GRID::inner_w, LOG_ERR, n_gui_add_custom(), n_gui_add_scrollbar(), n_gui_custom_set_destroy(), n_gui_custom_set_mouse(), N_GUI_SCROLLBAR_V, n_gui_set_widget_visible(), N_GUI_SHAPE_ROUNDED, n_log, _N_GUI_GRID::outer_h, _N_GUI_GRID::outer_w, _N_GUI_GRID::user_data, and _N_GUI_GRID::visible.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_scroll_to()

void n_gui_grid_scroll_to	(	N_GUI_CTX *	ctx,
		int	widget_id,
		size_t	index )

Scroll the least that brings a cell's whole row into view.

Parameters

ctx	the GUI context.
widget_id	the grid.
index	the cell. Past the last does nothing.

Definition at line 383 of file n_gui_grid.c.

References _grid_clamp(), _grid_columns_for(), _grid_of(), _grid_step(), _grid_sync_bar(), _N_GUI_GRID::count, _N_GUI_GRID::gap, _N_GUI_GRID::inner_w, n_gui_mark_dirty(), _N_GUI_GRID::outer_h, row(), and _N_GUI_GRID::scroll.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_scrollbar()

int n_gui_grid_scrollbar	(	N_GUI_CTX *	ctx,
		int	widget_id )

The grid's scrollbar widget.

Parameters

ctx	the GUI context.
widget_id	the grid.

Returns: the scrollbar's widget id, or -1 when widget_id is not a grid.

Definition at line 428 of file n_gui_grid.c.

References _grid_of(), and _N_GUI_GRID::bar.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_scrollbar_showing()

int n_gui_grid_scrollbar_showing	(	N_GUI_CTX *	ctx,
		int	widget_id )

Whether the scrollbar is shown, which is whether the rows overflow.

Parameters

ctx	the GUI context.
widget_id	the grid.

Returns: 1 when shown.

Definition at line 434 of file n_gui_grid.c.

References _grid_of(), and _N_GUI_GRID::bar_showing.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_set_cell_size()

void n_gui_grid_set_cell_size	(	N_GUI_CTX *	ctx,
		int	widget_id,
		float	cell_w,
		float	cell_h,
		float	gap )

Set the size of a cell and the gap around cells.

The first row and the first column are one gap in from the edge, and each row is cell_h plus a gap below the one before.

Parameters

ctx	the GUI context.
widget_id	the grid.
cell_w	cell width, over 0.
cell_h	cell height, over 0.
gap	space between cells and around them, 0 or more.

Definition at line 333 of file n_gui_grid.c.

References _grid_of(), _grid_place(), _N_GUI_GRID::cell_h, _N_GUI_GRID::cell_w, and _N_GUI_GRID::gap.

Referenced by main(), and wheel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_set_count()

void n_gui_grid_set_count	(	N_GUI_CTX *	ctx,
		int	widget_id,
		size_t	count )

Set how many cells there are.

The view is clamped to them.

Parameters

ctx	the GUI context.
widget_id	the grid.
count	how many.

Definition at line 343 of file n_gui_grid.c.

References _grid_of(), _grid_place(), and _N_GUI_GRID::count.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ n_gui_grid_set_rect()

void n_gui_grid_set_rect	(	N_GUI_CTX *	ctx,
		int	widget_id,
		float	x,
		float	y,
		float	w,
		float	h,
		float	bar_w )

Place the grid and its scrollbar in a rectangle of the window.

The scrollbar takes a strip of bar_w on the right when, and only when, the rows do not fit; the grid has the rest. Call it again after a change of count or of cell size that may change that answer; n_gui_grid_set_count() and n_gui_grid_set_cell_size() do so themselves.

Parameters

ctx	the GUI context.
widget_id	the grid.
x	left, relative to the window.
y	top, relative to the window.
w	width, scrollbar included.
h	height.
bar_w	width of the scrollbar's strip.