Implementation of the bounded UI interaction core. More...

#include "ra8_ui.h"
#include <stddef.h>
#include <stdint.h>
#include "ra8_check.h"
#include "ra8_err.h"

Include dependency graph for ra8_ui.c:

Functions
bool	ra8_ui_rect_contains (const ra8_ui_rect_t *r, int32_t px, int32_t py)
	Test whether a point lies inside a rectangle.
ra8_err_t	ra8_ui_hit_test (const ra8_ui_target_t targets, uint16_t count, int32_t px, int32_t py, uint16_t out_action, bool *out_hit)
	Find the first tap target containing a point.
ra8_err_t	ra8_ui_nav_init (ra8_ui_nav_t *nav, uint16_t root_screen)
	Initialise a navigation stack with a root screen.
ra8_err_t	ra8_ui_nav_push (ra8_ui_nav_t *nav, uint16_t screen)
	Push a new screen onto the stack.
ra8_err_t	ra8_ui_nav_pop (ra8_ui_nav_t nav, uint16_t out_screen)
	Pop the top screen, revealing the one beneath.
ra8_err_t	ra8_ui_nav_replace (ra8_ui_nav_t *nav, uint16_t screen)
	Replace the top screen in place (no depth change).
ra8_err_t	ra8_ui_nav_top (const ra8_ui_nav_t nav, uint16_t out_screen)
	Read the current (top) screen id.
ra8_err_t	ra8_ui_pager_init (ra8_ui_pager_t *p, uint16_t total)
	Initialise a pager over `total` pages at page 0.
ra8_err_t	ra8_ui_pager_next (ra8_ui_pager_t p, bool out_changed)
	Advance to the next page, clamping at the last page.
ra8_err_t	ra8_ui_pager_prev (ra8_ui_pager_t p, bool out_changed)
	Step to the previous page, clamping at page 0.
ra8_err_t	ra8_ui_pager_goto (ra8_ui_pager_t p, uint16_t page, bool out_changed)
	Jump to an absolute page, clamping into [0, total-1].

Variables
static const char *const	s_tag = "ra8_ui"
	Component tag for diagnostic logging.

Detailed Description

Implementation of the bounded UI interaction core.

Tag: [Ring 5 / UI] {World: NS}

Allocation-free hit-testing, screen-stack navigation, and page-cursor logic. See ra8_ui.h for the contract. Every entry point validates its pointer arguments and leaves caller state untouched on error.

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

Since: 0.1.0

Definition in file ra8_ui.c.

Function Documentation

◆ ra8_ui_hit_test()

ra8_err_t ra8_ui_hit_test	(	const ra8_ui_target_t *	targets,
		uint16_t	count,
		int32_t	px,
		int32_t	py,
		uint16_t *	out_action,
		bool *	out_hit )

nodiscard

Find the first tap target containing a point.

Walks targets in order and returns the action id of the first rectangle that contains (px, py). Earlier entries win on overlap, so callers should order more-specific targets first.

Parameters

[in]	targets	Target array (may be NULL only if count == 0).
[in]	count	Number of targets.
[in]	px	Point X (pixels).
[in]	py	Point Y (pixels).
[out]	out_action	Receives the hit target's action id.
[out]	out_hit	Receives true if a target was hit, else false.

Returns: ra8_err_t

Return values

k_ra8_ok	Search completed (see `out_hit`).
k_ra8_err_null_ptr	`out_action` / `out_hit` NULL, or `targets` NULL while `count` > 0.

Precondition: out_action and out_hit are non-NULL.; targets covers count entries.

Postcondition: On a hit, *out_hit == true and *out_action is the hit id.; On a miss, *out_hit == false and *out_action is unchanged.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 42 of file ra8_ui.c.

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

Referenced by er_handle_keyboard_tap(), er_handle_tap(), and iu_tap().

◆ ra8_ui_nav_init()

ra8_err_t ra8_ui_nav_init	(	ra8_ui_nav_t *	nav,
		uint16_t	root_screen )

nodiscard

Initialise a navigation stack with a root screen.

Parameters

[out]	nav	Stack to initialise.
[in]	root_screen	Screen id placed at the stack base.

Returns: ra8_err_t

Return values

k_ra8_ok	Initialised (depth == 1).
k_ra8_err_null_ptr	`nav` is NULL.

Precondition: nav is non-NULL.; None.

Postcondition: nav->depth == 1 and nav->stack[0] == root_screen.; No other slots are read.

Note: Not thread-safe (caller-owned mutable state).

Since: 0.1.0

Definition at line 71 of file ra8_ui.c.

References ra8_ui_nav_t::depth, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_ui_nav_t::stack.

Referenced by iu_nav_check(), and main().

◆ ra8_ui_nav_pop()

ra8_err_t ra8_ui_nav_pop	(	ra8_ui_nav_t *	nav,
		uint16_t *	out_screen )

nodiscard

Pop the top screen, revealing the one beneath.

The root screen is never popped (a pop at depth == 1 fails).

Parameters

[in,out]	nav	Initialised stack.
[out]	out_screen	Receives the new top screen after the pop.

Returns: ra8_err_t

Return values

k_ra8_ok	Popped; *out_screen is the new top.
k_ra8_err_null_ptr	`nav` or `out_screen` is NULL.
k_ra8_err_invalid_state	Already at the root (depth <= 1).

Precondition: nav and out_screen are non-NULL.; nav->depth > 1 for success.

Postcondition: On success depth shrank by one and *out_screen is the top.; At the root the stack is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 93 of file ra8_ui.c.

References ra8_ui_nav_t::depth, k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_ui_nav_t::stack.

Referenced by er_handle_keyboard_tap(), er_handle_reading_tap(), er_handle_tap(), and iu_nav_check().

◆ ra8_ui_nav_push()

ra8_err_t ra8_ui_nav_push	(	ra8_ui_nav_t *	nav,
		uint16_t	screen )

nodiscard

Push a new screen onto the stack.

Parameters

[in,out]	nav	Initialised stack.
[in]	screen	Screen id to push.

Returns: ra8_err_t

Return values

k_ra8_ok	Pushed (depth incremented).
k_ra8_err_null_ptr	`nav` is NULL.
k_ra8_err_no_mem	Stack already at k_ra8_ui_nav_max_depth.
k_ra8_err_invalid_state	Stack not initialised (depth == 0).

Precondition: nav is non-NULL and initialised.; nav->depth < k_ra8_ui_nav_max_depth for success.

Postcondition: On success the new screen is on top and depth grew by one.; On overflow the stack is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 79 of file ra8_ui.c.

References ra8_ui_nav_t::depth, k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_ok, k_ra8_ui_nav_max_depth, RA8_CHECK_NULL_PTR, s_tag, and ra8_ui_nav_t::stack.

Referenced by er_handle_tap(), and iu_nav_check().

◆ ra8_ui_nav_replace()

ra8_err_t ra8_ui_nav_replace	(	ra8_ui_nav_t *	nav,
		uint16_t	screen )

nodiscard

Replace the top screen in place (no depth change).

Parameters

[in,out]	nav	Initialised stack.
[in]	screen	Screen id to install on top.

Returns: ra8_err_t

Return values

k_ra8_ok	Replaced.
k_ra8_err_null_ptr	`nav` is NULL.
k_ra8_err_invalid_state	Stack not initialised (depth == 0).

Precondition: nav is non-NULL and initialised.; None.

Postcondition: nav->stack[depth-1] == screen and depth is unchanged.; No other slots are touched.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 105 of file ra8_ui.c.

References ra8_ui_nav_t::depth, k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_ui_nav_t::stack.

◆ ra8_ui_nav_top()

ra8_err_t ra8_ui_nav_top	(	const ra8_ui_nav_t *	nav,
		uint16_t *	out_screen )

nodiscard

Read the current (top) screen id.

Parameters

[in]	nav	Initialised stack.
[out]	out_screen	Receives the top screen id.

Returns: ra8_err_t

Return values

k_ra8_ok	Reported.
k_ra8_err_null_ptr	`nav` or `out_screen` is NULL.
k_ra8_err_invalid_state	Stack not initialised (depth == 0).

Precondition: nav and out_screen are non-NULL.; nav->depth >= 1.

Postcondition: *out_screen is nav->stack[depth-1].; No state is modified.

Note: Pure read; not thread-safe vs concurrent mutation.

Since: 0.1.0

Definition at line 115 of file ra8_ui.c.

References ra8_ui_nav_t::depth, k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_ui_nav_t::stack.

Referenced by er_handle_tap(), er_poll_buttons(), er_render_current(), er_render_nag_region(), and iu_nav_check().

◆ ra8_ui_pager_goto()

ra8_err_t ra8_ui_pager_goto	(	ra8_ui_pager_t *	p,
		uint16_t	page,
		bool *	out_changed )

nodiscard

Jump to an absolute page, clamping into [0, total-1].

Parameters

[in,out]	p	Initialised pager.
[in]	page	Requested 0-based page index.
[out]	out_changed	Receives true if the page actually moved.

Returns: ra8_err_t

Return values

k_ra8_ok	Done (see `out_changed`).
k_ra8_err_null_ptr	`p` or `out_changed` is NULL.

Precondition: p and out_changed are non-NULL; p->total >= 1.; None.

Postcondition: p->current is page clamped to [0, total-1].; *out_changed is true iff current moved.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 168 of file ra8_ui.c.

References ra8_ui_pager_t::current, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_ui_pager_t::total.

◆ ra8_ui_pager_init()

ra8_err_t ra8_ui_pager_init	(	ra8_ui_pager_t *	p,
		uint16_t	total )

nodiscard

Initialise a pager over total pages at page 0.

Parameters

[out]	p	Pager to initialise.
[in]	total	Total page count (must be >= 1).

Returns: ra8_err_t

Return values

k_ra8_ok	Initialised at page 0.
k_ra8_err_null_ptr	`p` is NULL.
k_ra8_err_invalid_arg	`total` is 0.

Precondition: p is non-NULL and total >= 1.; None.

Postcondition: p->current == 0 and p->total == total.; No other state exists.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 131 of file ra8_ui.c.

References ra8_ui_pager_t::current, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_ui_pager_t::total.

◆ ra8_ui_pager_next()

ra8_err_t ra8_ui_pager_next	(	ra8_ui_pager_t *	p,
		bool *	out_changed )

nodiscard

Advance to the next page, clamping at the last page.

Parameters

[in,out]	p	Initialised pager.
[out]	out_changed	Receives true if the page actually moved.

Returns: ra8_err_t

Return values

k_ra8_ok	Done (see `out_changed`).
k_ra8_err_null_ptr	`p` or `out_changed` is NULL.

Precondition: p and out_changed are non-NULL; p->total >= 1.; None.

Postcondition: p->current is min(current+1, total-1).; *out_changed is true iff current moved.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 142 of file ra8_ui.c.

References ra8_ui_pager_t::current, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_ui_pager_t::total.

◆ ra8_ui_pager_prev()

ra8_err_t ra8_ui_pager_prev	(	ra8_ui_pager_t *	p,
		bool *	out_changed )

nodiscard

Step to the previous page, clamping at page 0.

Parameters

[in,out]	p	Initialised pager.
[out]	out_changed	Receives true if the page actually moved.

Returns: ra8_err_t

Return values

k_ra8_ok	Done (see `out_changed`).
k_ra8_err_null_ptr	`p` or `out_changed` is NULL.

Precondition: p and out_changed are non-NULL.; None.

Postcondition: p->current is max(current-1, 0).; *out_changed is true iff current moved.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 155 of file ra8_ui.c.

References ra8_ui_pager_t::current, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_ui_rect_contains()

bool ra8_ui_rect_contains	(	const ra8_ui_rect_t *	r,
		int32_t	px,
		int32_t	py )

Test whether a point lies inside a rectangle.

Top-left inclusive, bottom-right exclusive: (px >= x) && (px < x + w) && (py >= y) && (py < y + h).

Parameters

[in]	r	Rectangle to test (NULL yields false).
[in]	px	Point X (pixels).
[in]	py	Point Y (pixels).

Returns: true if the point is inside r, false otherwise.

Return values

true	The point lies within `r`.
false	The point is outside `r`, or `r` is NULL.

Precondition: None (NULL r is handled).; None.

Postcondition: No state is modified.; Return value reflects containment only.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 34 of file ra8_ui.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 er_handle_reading_tap(), ez_zone_hit(), internal_bg_on_input(), internal_tb_on_input(), ra8_kbd_hit(), ra8_ui_hit_test(), and ra8_widget_dispatch().

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_ui"

static

Component tag for diagnostic logging.

Definition at line 27 of file ra8_ui.c.

Functions

Variables

Detailed Description

Function Documentation

◆ ra8_ui_hit_test()

◆ ra8_ui_nav_init()

◆ ra8_ui_nav_pop()

◆ ra8_ui_nav_push()

◆ ra8_ui_nav_replace()

◆ ra8_ui_nav_top()

◆ ra8_ui_pager_goto()

◆ ra8_ui_pager_init()

◆ ra8_ui_pager_next()

◆ ra8_ui_pager_prev()

◆ ra8_ui_rect_contains()

Variable Documentation

◆ s_tag