ra8_widget_internal.h File Reference

Module-private paint helpers shared by the concrete leaf-widget TUs. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_widget.h"

Include dependency graph for ra8_widget_internal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

Module-private paint helpers shared by the concrete leaf-widget TUs.

Concrete widgets share aligned text placement, optionally bordered boxes, and proportional-fill width through the injected ra8_widget_paint_t backend. Rather than duplicate that geometry and its branch obligations, the three helpers live in ra8_widget_paint.c and are declared here as RA8_PRIV module-private seams. They remain pure compute plus callback dispatch, carry no ra8_gfx dependency, and are exercised through public render callbacks with a recording host paint.

Not part of the public surface: production callers use the widget vtables; the only out-of-TU consumers are the sibling widget TUs and the host tests.

[Ring 5 / UI] {World: NS}

Copyright

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

Since

0.1.0

Definition in file ra8_widget_internal.h.

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