Book-card + book-grid leaf widget for the ra8_widget tree (#145 Phase 2). More...

#include "ra8_widget_book.h"
#include "ra8_check.h"
#include "ra8_ui.h"
#include "ra8_widget.h"
#include "ra8_widget_internal.h"

Include dependency graph for ra8_widget_book.c:

Enumerations
enum	ra8_widget_book_geom_t : uint16_t { k_ra8_widget_book_min_cols = 1U , k_ra8_widget_book_pct_full = 100U , k_ra8_widget_book_none = 0U }
	Grid geometry constants (no magic numbers). More...

Functions
static ra8_ui_rect_t	internal_bg_content (const ra8_ui_rect_t *rect, int16_t pad)
	Inset the grid rect by its padding to the content rectangle.
static ra8_ui_rect_t	internal_bg_cell (const ra8_ui_rect_t *content, uint16_t idx, uint16_t cols, uint16_t rows, int16_t gap)
	Compute card `idx's` cell inside the content rect.
static void	internal_bg_label (const ra8_widget_paint_t paint, const ra8_ui_rect_t row, const char *text, uint32_t fg, uint32_t bg)
	Draw one card label (title / author) left-aligned in its row.
static void	internal_bg_card (const ra8_widget_book_grid_t g, const ra8_widget_book_t book, const ra8_ui_rect_t *cell)
	Paint one book card (cover / title / author / progress) into a cell.
static uint16_t	internal_bg_rows (uint16_t count, uint16_t cols)
	Row count for `count` cards laid `cols` wide (ceil division).
static void	internal_bg_render (ra8_widget_t *w)
	Book-grid vtable render: fill the background, tile + paint the cards.
static bool	internal_bg_on_input (ra8_widget_t w, const ra8_widget_event_t ev)
	Book-grid vtable input: route a touch to the card it hit.
const ra8_widget_vtable_t *	ra8_widget_book_grid_vtable (void)
	Return the shared vtable backing every book-grid widget.
ra8_err_t	ra8_widget_book_grid_init (ra8_widget_t w, ra8_widget_book_grid_t grid)
	Bind a widget instance to a book grid.

Variables
static const char *	s_tag = "ra8_widget_book_grid"
	Logging / check tag.
static const ra8_widget_vtable_t	s_bg_vt
	The single immutable vtable shared by every book grid.

Detailed Description

Book-card + book-grid leaf widget for the ra8_widget tree (#145 Phase 2).

Extracts the e-reader Library book grid into a reusable ra8_widget leaf. The grid geometry (internal_bg_content, internal_bg_cell) is shared between render (paint each card) and the hit maths (internal_bg_on_input), so a tap opens the card it looks like it opens. Each card stacks a cover swatch, a title row, an author row, and a progress bar, painted through the injected ra8_widget_paint_t backend – so the file carries no ra8_gfx dependency and the whole grid is host-testable with a recording mock paint. The card progress bar reuses the shared priv_widget_fill_frac helper.

[Ring 5 / UI] {World: NS}

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file ra8_widget_book.c.

Enumeration Type Documentation

◆ ra8_widget_book_geom_t

enum ra8_widget_book_geom_t : uint16_t

Grid geometry constants (no magic numbers).

Enumerator
k_ra8_widget_book_min_cols	Minimum columns; cols == 0 -> 1.
k_ra8_widget_book_pct_full	Full read-progress percentage.
k_ra8_widget_book_none	Empty grid (no cards).

Definition at line 38 of file ra8_widget_book.c.

Function Documentation

◆ internal_bg_card()

void internal_bg_card	(	const ra8_widget_book_grid_t *	g,
		const ra8_widget_book_t *	book,
		const ra8_ui_rect_t *	cell )

static

Paint one book card (cover / title / author / progress) into a cell.

Stacks a cover swatch (the remaining height above the labels), the label_h-tall title and author rows, and the bar_h-tall progress bar at the bottom. The cover is skipped when the cell is too short to hold one; the labels only draw when the backend has draw_text.

Parameters

[in]	g	The book grid descriptor (non-NULL; paint non-NULL).
[in]	book	The card's data record (non-NULL).
[in]	cell	The card's cell rectangle (non-NULL).

Returns: Nothing.

Precondition: g, book, cell are non-NULL; g->paint is non-NULL.; None.

Postcondition: At most a cover fill, two label draws, and two bar fills run.; No pixels spill outside cell.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 164 of file ra8_widget_book.c.

References ra8_ui_rect_t::h, internal_bg_label(), k_ra8_widget_book_pct_full, priv_widget_fill_box(), priv_widget_fill_frac(), ra8_ui_rect_t::w, ra8_ui_rect_t::x, and ra8_ui_rect_t::y.

Referenced by internal_bg_render().

◆ internal_bg_cell()

ra8_ui_rect_t internal_bg_cell	(	const ra8_ui_rect_t *	content,
		uint16_t	idx,
		uint16_t	cols,
		uint16_t	rows,
		int16_t	gap )

static

Compute card idx's cell inside the content rect.

Tiles content into cols x rows equal cells separated by gap; card idx sits at column idx % cols, row idx / cols. Shared by render and hit-testing so the drawn card and its tap target coincide.

Parameters

[in]	content	The grid content rect (non-NULL).
[in]	idx	Card index.
[in]	cols	Column count (>= 1).
[in]	rows	Row count (>= 1).
[in]	gap	Gap between cells, pixels.

Returns: The card's cell rectangle.

Return values

cell	The `idx-th` card cell.

Precondition: content is non-NULL; cols >= 1; rows >= 1.; None.

Postcondition: The returned cell lies within content.; No state is modified.

Note: Pure.

Since: 0.1.0

Definition at line 93 of file ra8_widget_book.c.

References ra8_ui_rect_t::h, ra8_ui_rect_t::w, ra8_ui_rect_t::x, and ra8_ui_rect_t::y.

Referenced by internal_bg_on_input(), and internal_bg_render().

◆ internal_bg_content()

ra8_ui_rect_t internal_bg_content	(	const ra8_ui_rect_t *	rect,
		int16_t	pad )

static

Inset the grid rect by its padding to the content rectangle.

Shrinks rect by pad on every side, so the cards tile inside the padded content area rather than against the grid edge. Split out so render and hit-testing derive the same content rect.

Parameters

[in]	rect	The grid widget rect (non-NULL).
[in]	pad	Inner padding, pixels.

Returns: The content rectangle (grid rect inset by pad on every side).

Return values

r	The inset content rect.

Precondition: rect is non-NULL.; None.

Postcondition: The returned rect lies within rect.; No state is modified.

Note: Pure.

Since: 0.1.0

Definition at line 61 of file ra8_widget_book.c.

References ra8_ui_rect_t::h, ra8_ui_rect_t::w, ra8_ui_rect_t::x, and ra8_ui_rect_t::y.

Referenced by internal_bg_on_input(), and internal_bg_render().

◆ internal_bg_label()

void internal_bg_label	(	const ra8_widget_paint_t *	paint,
		const ra8_ui_rect_t *	row,
		const char *	text,
		uint32_t	fg,
		uint32_t	bg )

static

Draw one card label (title / author) left-aligned in its row.

Places text at the left inset of row via priv_widget_text_pos and draws it, skipping a NULL text. The title and author rows share this one branch-coverable helper.

Parameters

[in]	paint	Draw backend (non-NULL; draw_text already checked non-NULL).
[in]	row	The label row rect (non-NULL).
[in]	text	Label text, or NULL to skip.
[in]	fg	Text colour, 0xRRGGBB.
[in]	bg	Background colour, 0xRRGGBB.

Returns: Nothing.

Precondition: paint, row non-NULL; paint->draw_text non-NULL.; None.

Postcondition: At most one draw_text call is issued.; No draw call is issued when text is NULL.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 131 of file ra8_widget_book.c.

References k_ra8_widget_align_left, and priv_widget_text_pos().

Referenced by internal_bg_card().

◆ internal_bg_on_input()

bool internal_bg_on_input	(	ra8_widget_t *	w,
		const ra8_widget_event_t *	ev )

static

Book-grid vtable input: route a touch to the card it hit.

Recomputes the same grid tiling as render and finds the card whose cell contains the tap; on a hit it records selected, self-invalidates fast, fires the optional on_open, and consumes the event. A non-touch event, an empty grid, or a tap in no cell is declined.

Parameters

[in]	w	The book-grid widget (its ctx is a ra8_widget_book_grid_t).
[in]	ev	The event already routed to this grid.

Returns: true if a card touch was routed, false otherwise.

Return values

true	`ev` was a touch on a card and it was routed.
false	Non-touch, empty grid, a tap in no card, or ctx is NULL.

Precondition: w and ev are non-NULL.; w->ctx points at a valid grid descriptor or is NULL.

Postcondition: On a card touch selected holds the hit index and w is dirty/fast.; No state changes on a declined event.

Note: Not thread-safe; loop bounded by count (NASA Rule 2).

Since: 0.1.0

Definition at line 274 of file ra8_widget_book.c.

References internal_bg_cell(), internal_bg_content(), internal_bg_rows(), k_ra8_widget_book_min_cols, k_ra8_widget_book_none, k_ra8_widget_ev_touch, k_ra8_widget_refresh_fast, ra8_widget_event_t::kind, ra8_ui_rect_contains(), ra8_widget_invalidate(), ra8_widget_event_t::x, and ra8_widget_event_t::y.

◆ internal_bg_render()

void internal_bg_render ( ra8_widget_t * w )

static

Book-grid vtable render: fill the background, tile + paint the cards.

Reads the ra8_widget_book_grid_t from w->ctx, fills the grid with bg, then tiles the count cards into cols columns and paints each via internal_bg_card. An empty grid or a missing paint backend / book array is a no-op.

Parameters

[in] w The book-grid widget (its ctx is a ra8_widget_book_grid_t).

Returns: Nothing.

Precondition: w is non-NULL (guaranteed by ra8_widget_render_dirty).; w->ctx points at a valid grid descriptor or is NULL.

Postcondition: At most a background fill plus count card paints are issued.; No pixels are touched when the grid has no paint backend.

Note: Not thread-safe; loop bounded by count (NASA Rule 2).

Since: 0.1.0

Definition at line 231 of file ra8_widget_book.c.

References internal_bg_card(), internal_bg_cell(), internal_bg_content(), internal_bg_rows(), k_ra8_widget_book_min_cols, k_ra8_widget_book_none, and priv_widget_fill_box().

◆ internal_bg_rows()

uint16_t internal_bg_rows	(	uint16_t	count,
		uint16_t	cols )

static

Row count for count cards laid cols wide (ceil division).

Rounds count / cols up so a partial final row still gets a row of height, which internal_bg_cell needs to size cells on the cross axis. Both render and hit-testing call it with the clamped cols.

Parameters

[in]	count	Number of cards (>= 1).
[in]	cols	Columns (>= 1).

Returns: The number of grid rows (>= 1).

Return values

rows	ceil(count / cols).

Precondition: count >= 1; cols >= 1.; None.

Postcondition: The result is >= 1.; No state is modified.

Note: Pure.

Since: 0.1.0

Definition at line 210 of file ra8_widget_book.c.

Referenced by internal_bg_on_input(), and internal_bg_render().

◆ ra8_widget_book_grid_init()

ra8_err_t ra8_widget_book_grid_init	(	ra8_widget_t *	w,
		ra8_widget_book_grid_t *	grid )

nodiscard

Bind a widget instance to a book grid.

Wires w to render + route grid: sets its vtable to ra8_widget_book_grid_vtable, points its ctx at grid, and makes it visible. The caller still sets w's fixed / flex for its parent's layout.

Parameters

[in,out]	w	Widget to turn into a book grid (non-NULL).
[in]	grid	Book-grid descriptor (non-NULL; outlives `w's` use).

Returns: ra8_err_t

Return values

k_ra8_ok	Bound; `w` renders + routes `grid`.
k_ra8_err_null_ptr	`w` or `grid` is NULL.

Precondition: w and grid are non-NULL.; grid outlives every render / dispatch of w.

Postcondition: On success w->vt == ra8_widget_book_grid_vtable(), w->ctx == grid, w->visible == true.; On failure w is left unchanged.

Note: Not thread-safe.

See also: ra8_widget_book_grid_vtable

Since: 0.1.0

Definition at line 317 of file ra8_widget_book.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_widget_book_grid_vtable(), and s_tag.

◆ ra8_widget_book_grid_vtable()

const ra8_widget_vtable_t * ra8_widget_book_grid_vtable ( void )

Return the shared vtable backing every book-grid widget.

One immutable vtable serves all book grids: render fills the background and tiles + paints every card through the grid's ra8_widget_paint_t; on_input maps a touch to a card and fires on_open; measure is NULL. ra8_widget_book_grid_init binds it.

Returns: Non-NULL pointer to the static book-grid vtable.

Precondition: None.; None.

Postcondition: The returned pointer is non-NULL and references static storage.; No state is modified.

Note: Pure; thread-safe (returns a pointer to immutable static data).

See also: ra8_widget_book_grid_init

Since: 0.1.0

Definition at line 312 of file ra8_widget_book.c.

References s_bg_vt.

Referenced by ra8_widget_book_grid_init(), and wd_build_tree().

Variable Documentation

◆ s_bg_vt

const ra8_widget_vtable_t s_bg_vt

static

Initial value:

                                         = {
  .measure  = nullptr,
  .render   = internal_bg_render,
  .on_input = internal_bg_on_input,
}

The single immutable vtable shared by every book grid.

Definition at line 306 of file ra8_widget_book.c.

Referenced by ra8_widget_book_grid_vtable().

◆ s_tag

const char* s_tag = "ra8_widget_book_grid"

static

Logging / check tag.

Definition at line 32 of file ra8_widget_book.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_widget_book_geom_t

Function Documentation

◆ internal_bg_card()

◆ internal_bg_cell()

◆ internal_bg_content()

◆ internal_bg_label()

◆ internal_bg_on_input()

◆ internal_bg_render()

◆ internal_bg_rows()

◆ ra8_widget_book_grid_init()

◆ ra8_widget_book_grid_vtable()

Variable Documentation

◆ s_bg_vt

◆ s_tag