ra8_widget_paint.c File Reference

Shared geometry helpers for the concrete leaf widgets (#145 Phase 2). More...

#include "ra8_widget_internal.h"

Include dependency graph for ra8_widget_paint.c:

Go to the source code of this file.

Enumerations
enum	ra8_widget_frac_geom_t : int32_t { k_ra8_widget_frac_empty = 0 }
	No filled pixels (0% or a degenerate rect). More...

Functions
void	priv_widget_text_pos (const ra8_widget_paint_t *paint, const ra8_ui_rect_t *rect, const char *text, int16_t pad, ra8_widget_align_t align, int32_t *out_x, int32_t *out_y)
	Compute where a leaf widget's text should start within its rect.
void	priv_widget_fill_box (const ra8_widget_paint_t *paint, const ra8_ui_rect_t *rect, uint32_t fill, uint32_t border, int16_t border_w)
	Fill a widget rect with an optional 1-or-more-pixel border.
int32_t	priv_widget_fill_frac (uint32_t value, uint32_t total, int32_t width)
	Filled width in pixels for a value / total bar spanning width.

Detailed Description

Shared geometry helpers for the concrete leaf widgets (#145 Phase 2).

Holds the three RA8_PRIV helpers shared by concrete widgets: aligned text placement, filled / bordered boxes, and bounded proportional-fill width. They compute pixel geometry and dispatch through the injected ra8_widget_paint_t backend, so – like the rest of ra8_widget – this file carries no ra8_gfx dependency. The full contracts live on the declarations in ra8_widget_internal.h; the definitions below are deliberately comment-free.

Both helpers take an already-validated, non-NULL paint (the widget render callbacks guard that before delegating here), so they keep only the guards a caller can still vary – the optional text_size / fill_rect callbacks and the geometry selectors – which keeps every branch reachable from the host tests through the public render path.

[Ring 5 / UI] {World: NS}

Copyright

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

Since

0.1.0

Definition in file ra8_widget_paint.c.

Enumeration Type Documentation

ra8_widget_frac_geom_t

enum ra8_widget_frac_geom_t : int32_t

No filled pixels (0% or a degenerate rect).

Enumerator
k_ra8_widget_frac_empty	RA8 widget frac empty.

Definition at line 81 of file ra8_widget_paint.c.

Function Documentation

priv_widget_fill_box()

void priv_widget_fill_box	(	const ra8_widget_paint_t *	paint,
		const ra8_ui_rect_t *	rect,
		uint32_t	fill,
		uint32_t	border,
		int16_t	border_w )

Fill a widget rect with an optional 1-or-more-pixel border.

With border_w <= 0 this is a single fill_rect of fill over rect. Otherwise it paints border over the whole rect then fill over the rect inset by border_w on every side, yielding a framed face in two fills. A NULL fill_rect callback is a no-op, so a widget with a non-drawing backend is safe. The widget render callbacks guard paint non-NULL before delegating here, so it is not re-checked.

Parameters

[in]	paint	Draw backend (non-NULL; NULL fill_rect -> no-op).
[in]	rect	Rectangle to fill (non-NULL).
[in]	fill	Interior fill colour, 0xRRGGBB.
[in]	border	Border colour, 0xRRGGBB (used only when border_w > 0).
[in]	border_w	Border thickness in pixels; <= 0 means no border.

Returns

Nothing.

Precondition

paint and rect are non-NULL.

border_w is the configured thickness (>= 0 by widget invariant).

Postcondition

At most two fill_rect calls are issued on paint.

No pixels are touched when paint->fill_rect is NULL.

Note

Not thread-safe vs concurrent backend mutation.

MC/DC:

Single-condition guards (fill_rect == NULL, border_w <= 0) – each exercised true and false via the label (border_w 0) and button (border_w > 0) renders plus a NULL-fill_rect backend vector.

Since

0.1.0

Definition at line 57 of file ra8_widget_paint.c.

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

Referenced by internal_bg_card(), internal_bg_render(), internal_button_render(), internal_kbd_key(), internal_kbd_render(), internal_label_render(), internal_nav_render(), internal_rv_render(), internal_sb_render(), and internal_tb_render().

priv_widget_fill_frac()

int32_t priv_widget_fill_frac	(	uint32_t	value,
		uint32_t	total,
		int32_t	width )

Filled width in pixels for a value / total bar spanning width.

The proportional-fill maths shared by the progress-bar leaf and the book-card progress indicator: clamp value into [0, total] and guard the degenerate inputs so no caller divides by zero or paints past the rect. A zero total or a non-positive width fills nothing; a value >= total fills the whole width; otherwise the fill is width * value / total. Pure integer compute, no backend call, so it is exercised on the host through both widgets' renders.

Parameters

[in]	value	Current progress value.
[in]	total	Full-scale value; 0 means empty (no fill).
[in]	width	Rect width in pixels the fill spans.

Returns

Filled width in pixels, in [0, width].

Return values

0	When total is 0, width is non-positive, or value is 0.
width	When value is at or above total (a full bar).

Precondition

None.

None.

Postcondition

The result is >= 0 and <= width.

No state is modified.

Note

Pure; thread-safe.

MC/DC:

Single-condition guards (total == 0, width <= 0, value > total) – each driven both true and false through the progress-bar render (empty / partial / full / zero-width vectors) and the book-card render.

Since

0.1.0

Definition at line 85 of file ra8_widget_paint.c.

References k_ra8_widget_frac_empty, and RA8_PRIV.

Referenced by internal_bg_card(), and internal_pb_render().

priv_widget_text_pos()

void priv_widget_text_pos	(	const ra8_widget_paint_t *	paint,
		const ra8_ui_rect_t *	rect,
		const char *	text,
		int16_t	pad,
		ra8_widget_align_t	align,
		int32_t *	out_x,
		int32_t *	out_y )

Compute where a leaf widget's text should start within its rect.

Resolves the top-left pen position for a string drawn inside rect. The horizontal coordinate follows align (left/centre/right); centre and right need the string's pixel width, so they require a text_size callback on paint and otherwise fall back to the left inset. When the width is measurable the vertical coordinate centres the glyph cell in the rect, else it uses the top inset. Each guard is a single condition (no compound decision), so MC/DC reduces to branch coverage of each early-out. The widget render callbacks guard paint and text non-NULL before delegating here, so neither is re-checked.

Parameters

[in]	paint	Draw backend (non-NULL); its text_size measures the text.
[in]	rect	The widget rectangle the text is placed inside (non-NULL).
[in]	text	NUL-terminated string (non-NULL; read only for centre/right).
[in]	pad	Inner inset from the rect edges, pixels.
[in]	align	Horizontal alignment selector.
[out]	out_x	Receives the pen X (left edge of the first glyph).
[out]	out_y	Receives the pen Y (top edge of the glyph row).

Returns

Nothing.

Precondition

paint, rect, text, out_x and out_y are non-NULL.

paint->text_size, if set, fills both out dimensions.

Postcondition

*out_x / *out_y hold a pen position inside or at the rect inset.

No backend draw call is issued (measurement only).

Note

Pure compute; not thread-safe vs concurrent backend mutation.

MC/DC:

Single-condition early-outs (align == left, text_size == NULL, align == right) – each driven both true and false through the label / button render with a mock paint that does / does not provide text_size.

Since

0.1.0

Definition at line 30 of file ra8_widget_paint.c.

References ra8_ui_rect_t::h, k_ra8_widget_align_left, k_ra8_widget_align_right, RA8_PRIV, ra8_ui_rect_t::w, ra8_ui_rect_t::x, and ra8_ui_rect_t::y.

Referenced by internal_bg_label(), internal_button_render(), internal_kbd_key(), internal_label_render(), internal_nav_item(), internal_sb_label(), and internal_tb_render().