A virtualised grid of cells for N_GUI, scrolled vertically. More...

#include <math.h>
#include <stdlib.h>
#include <string.h>
#include "nilorea/n_common.h"
#include "nilorea/n_log.h"
#include "nilorea/n_gui_grid.h"

Include dependency graph for n_gui_grid.c:

Data Structures
struct	_N_GUI_GRID
	a grid's state, owned by its custom widget More...

Functions
static void	_grid_clamp (_N_GUI_GRID *g)
	helper: keep the view inside the content
static int	_grid_columns_for (const _N_GUI_GRID *g, float w)
	helper: cells across a width
static float	_grid_content_h_for (const _N_GUI_GRID *g, float w)
	helper: content height at a width: the gap above the first row, then each row with its gap
static void	_grid_destroy (void *user_data)
	the widget's destroy callback.
static void	_grid_draw (N_GUI_WIDGET widget, float x, float y, ALLEGRO_FONT font, void *user_data)
	custom draw callback
static int	_grid_index_local (const _N_GUI_GRID g, float w, float lx, float ly, size_t index)
	helper: the cell at a widget-local point, the rules of n_gui_grid_index_at
static int	_grid_mouse (int widget_id, const N_GUI_MOUSE_EVENT ev, void user_data)
	custom mouse callback
static _N_GUI_GRID *	_grid_of (N_GUI_CTX *ctx, int widget_id)
	helper: find a grid's state behind a widget id, or NULL
static void	_grid_on_bar (int widget_id, double pos, void *user_data)
	the scrollbar's callback: the view follows a drag of the bar
static void	_grid_place (_N_GUI_GRID *g)
	helper: decide whether the bar shows, and place the grid and the bar
static size_t	_grid_rows_for (const _N_GUI_GRID *g, int columns)
	helper: rows the cells make at a column count
static float	_grid_step (const _N_GUI_GRID *g)
	helper: one row and the gap below it
static void	_grid_sync_bar (_N_GUI_GRID *g)
	helper: tell the scrollbar where the view is
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

A virtualised grid of cells for N_GUI, scrolled vertically.

Author: Castagnier Mickael

Version: 1.0

Date: 24/09/2026

Definition in file n_gui_grid.c.

Data Structure Documentation

◆ _N_GUI_GRID

struct _N_GUI_GRID

a grid's state, owned by its custom widget

Definition at line 39 of file n_gui_grid.c.

Collaboration diagram for _N_GUI_GRID:

Data Fields
int	bar	its scrollbar
int	bar_showing	whether the bar is shown
float	bar_w	width of the scrollbar's strip
N_GUI_GRID_CALLBACKS	cb	what the caller asked for
float	cell_h	cell height
float	cell_w	cell width
size_t	count	how many cells
N_GUI_CTX *	ctx	the context, for the callbacks that are handed only an id
float	gap	gap between and around cells
int	id	the grid widget
float	inner_w	the grid's own width, the strip taken off when the bar shows
float	outer_h
float	outer_w
float	outer_x	the rectangle n_gui_grid_set_rect() was given, scrollbar included
float	outer_y
int	placing	set while the bar is being told where it is, so its callback is not taken for a drag
float	scroll	pixels from the top of the content to the top of the view
void *	user_data	handed back to the callbacks
int	visible	whether the caller wants it shown

Function Documentation

◆ _grid_clamp()

void _grid_clamp ( _N_GUI_GRID * g )

static

helper: keep the view inside the content

Definition at line 99 of file n_gui_grid.c.

References _grid_content_h_for(), _N_GUI_GRID::inner_w, _N_GUI_GRID::outer_h, and _N_GUI_GRID::scroll.

Referenced by _grid_mouse(), _grid_on_bar(), _grid_place(), n_gui_grid_scroll_to(), and n_gui_grid_set_scroll().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _grid_columns_for()

int _grid_columns_for	(	const _N_GUI_GRID *	g,
		float	w )

static

helper: cells across a width

Definition at line 76 of file n_gui_grid.c.

References _N_GUI_GRID::cell_w, and _N_GUI_GRID::gap.

Referenced by _grid_content_h_for(), _grid_draw(), _grid_index_local(), n_gui_grid_cell_rect(), n_gui_grid_columns(), and n_gui_grid_scroll_to().

Here is the caller graph for this function:

◆ _grid_content_h_for()

float _grid_content_h_for	(	const _N_GUI_GRID *	g,
		float	w )

static

helper: content height at a width: the gap above the first row, then each row with its gap

Definition at line 94 of file n_gui_grid.c.

References _grid_columns_for(), _grid_rows_for(), _grid_step(), and _N_GUI_GRID::gap.

Referenced by _grid_clamp(), _grid_place(), and _grid_sync_bar().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _grid_destroy()

void _grid_destroy ( void * user_data )

static

the widget's destroy callback.

The scrollbar is a widget of the same window and is only ever destroyed with it, by n_gui_destroy_ctx(), which calls no scrollbar callback, so nothing reaches the state once it is freed.

Definition at line 265 of file n_gui_grid.c.

Referenced by n_gui_grid_new().

Here is the caller graph for this function: