Navigation-strip leaf widget for the ra8_widget tree model (#145 Phase 2). More...

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

Include dependency graph for ra8_widget_nav_bar.c:

Enumerations
enum	ra8_widget_nav_geom_t : uint16_t { k_ra8_widget_nav_empty = 0U }
	Empty sentinel: an empty strip (no items) draws / routes nothing. More...

Functions
static ra8_ui_rect_t	internal_nav_cell (const ra8_ui_rect_t *strip, uint16_t idx, uint16_t count)
	Compute cell `idx` of a count-cell strip laid inside `strip`.
static void	internal_nav_item (const ra8_widget_paint_t paint, const ra8_ui_rect_t cell, const char *text, uint32_t fg, uint32_t bg)
	Draw one nav item's centred label in its cell.
static void	internal_nav_render (ra8_widget_t *w)
	Nav-strip vtable render: fill the strip, centre each cell's label.
static bool	internal_nav_hit (const ra8_ui_rect_t strip, uint16_t count, int32_t px, uint16_t out)
	Map a touch X to a cell index within a count-cell strip.
static bool	internal_nav_on_input (ra8_widget_t w, const ra8_widget_event_t ev)
	Nav-strip vtable input: route a touch to the cell it hit.
const ra8_widget_vtable_t *	ra8_widget_nav_bar_vtable (void)
	Return the shared vtable backing every navigation-strip widget.
ra8_err_t	ra8_widget_nav_bar_init (ra8_widget_t w, ra8_widget_nav_bar_t nav)
	Bind a widget instance to a navigation strip.

Variables
static const char *	s_tag = "ra8_widget_nav_bar"
	Logging / check tag.
static const ra8_widget_vtable_t	s_nav_vt
	The single immutable vtable shared by every nav strip.

Detailed Description

Navigation-strip leaf widget for the ra8_widget tree model (#145 Phase 2).

Extracts the e-reader bottom navigation strip into a reusable ra8_widget leaf: count equal-width cells, each a centred label (active vs muted colour), each a tap target. The cell geometry (internal_nav_cell) is shared between render (draw each label) and the hit maths (internal_nav_hit), so a tap lands in the cell it looks like it lands in. Painting goes through the injected ra8_widget_paint_t backend, so the file carries no ra8_gfx dependency.

[Ring 5 / UI] {World: NS}

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

Since: 0.1.0

Definition in file ra8_widget_nav_bar.c.

Enumeration Type Documentation

◆ ra8_widget_nav_geom_t

enum ra8_widget_nav_geom_t : uint16_t

Empty sentinel: an empty strip (no items) draws / routes nothing.

Enumerator
k_ra8_widget_nav_empty	A count of this many is a no-op.

Definition at line 35 of file ra8_widget_nav_bar.c.

Function Documentation

◆ internal_nav_cell()

ra8_ui_rect_t internal_nav_cell	(	const ra8_ui_rect_t *	strip,
		uint16_t	idx,
		uint16_t	count )

static

Compute cell idx of a count-cell strip laid inside strip.

Splits strip into count equal cells using rounded prefix widths (w*i/count), so cells tile the strip with no gap and absorb the remainder deterministically. Shared by render and hit-testing.

Parameters

[in]	strip	The nav-strip widget rect (non-NULL).
[in]	idx	Cell index (< count).
[in]	count	Number of cells (>= 1).

Returns: The cell rectangle.

Return values

rect	The `idx-th` cell within `strip`.

Precondition: strip is non-NULL; count >= 1; idx < count.; None.

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

Note: Pure.

Since: 0.1.0

Definition at line 57 of file ra8_widget_nav_bar.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_nav_render().

◆ internal_nav_hit()

bool internal_nav_hit	(	const ra8_ui_rect_t *	strip,
		uint16_t	count,
		int32_t	px,
		uint16_t *	out )

static

Map a touch X to a cell index within a count-cell strip.

Guards a degenerate strip (count == 0 or w <= 0) and a tap outside the strip, then returns the proportional cell index clamped to the last cell. Split out so internal_nav_on_input stays small.

Parameters

[in]	strip	The nav-strip rect (non-NULL).
[in]	count	Number of cells.
[in]	px	Touch X (pixels).
[out]	out	Receives the hit cell index (only on a true return).

Returns: true if px lands on a cell, false otherwise.

Return values

true	A cell was hit; *out holds its index.
false	Degenerate strip or a tap outside it.

Precondition: strip and out are non-NULL.; None.

Postcondition: On true *out < count (the in-range guard makes px - x < w, so the proportional index is strictly below count – no clamp needed).; No state is modified.

Note: Pure.

Since: 0.1.0

Definition at line 164 of file ra8_widget_nav_bar.c.

References k_ra8_widget_nav_empty, ra8_ui_rect_t::w, and ra8_ui_rect_t::x.

Referenced by internal_nav_on_input().

◆ internal_nav_item()

void internal_nav_item	(	const ra8_widget_paint_t *	paint,
		const ra8_ui_rect_t *	cell,
		const char *	text,
		uint32_t	fg,
		uint32_t	bg )

static

Draw one nav item's centred label in its cell.

Places text centred in cell via priv_widget_text_pos and draws it in fg over bg. A NULL text is a no-op.

Parameters

[in]	paint	Draw backend (non-NULL; draw_text already checked non-NULL).
[in]	cell	The item's cell rectangle (non-NULL).
[in]	text	Item label, or NULL to skip.
[in]	fg	Text colour, 0xRRGGBB.
[in]	bg	Background colour, 0xRRGGBB.

Returns: Nothing.

Precondition: paint, cell are non-NULL; paint->draw_text is 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 87 of file ra8_widget_nav_bar.c.

References k_ra8_widget_align_center, and priv_widget_text_pos().

Referenced by internal_nav_render().

◆ internal_nav_on_input()

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

static

Nav-strip vtable input: route a touch to the cell it hit.

A touch inside a cell records it in selected, self-invalidates fast, fires the optional on_select, and reports the event consumed. A non-touch event or a tap outside the strip is declined.

Parameters

[in]	w	The nav-strip widget (its ctx is a ra8_widget_nav_bar_t).
[in]	ev	The event already routed to this strip.

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

Return values

true	`ev` was a touch on a cell and it was routed.
false	Non-touch, a tap off the strip, or ctx is NULL.

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

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 198 of file ra8_widget_nav_bar.c.

References internal_nav_hit(), k_ra8_widget_ev_touch, k_ra8_widget_refresh_fast, ra8_widget_event_t::kind, ra8_widget_invalidate(), and ra8_widget_event_t::x.

◆ internal_nav_render()

void internal_nav_render ( ra8_widget_t * w )

static

Nav-strip vtable render: fill the strip, centre each cell's label.

Reads the ra8_widget_nav_bar_t from w->ctx, fills the strip with bg, then draws each of the count items centred in its cell with fg_active for the active index and fg_muted for the rest. An empty strip (count == 0) or a missing paint backend is a no-op.

Parameters

[in] w The nav-strip widget (its ctx is a ra8_widget_nav_bar_t).

Returns: Nothing.

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

Postcondition: At most a strip fill plus count label draws are issued.; No pixels are touched when the strip has no paint backend.

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

Since: 0.1.0

Definition at line 118 of file ra8_widget_nav_bar.c.

References internal_nav_cell(), internal_nav_item(), k_ra8_widget_nav_empty, and priv_widget_fill_box().

◆ ra8_widget_nav_bar_init()

ra8_err_t ra8_widget_nav_bar_init	(	ra8_widget_t *	w,
		ra8_widget_nav_bar_t *	nav )

nodiscard

Bind a widget instance to a navigation strip.

Wires w to render + route nav: sets its vtable to ra8_widget_nav_bar_vtable, points its ctx at nav, 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 nav strip (non-NULL).
[in]	nav	Nav-strip descriptor (non-NULL; outlives `w's` use).

Returns: ra8_err_t

Return values

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

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

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

Note: Not thread-safe.

See also: ra8_widget_nav_bar_vtable

Since: 0.1.0

Definition at line 231 of file ra8_widget_nav_bar.c.

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

◆ ra8_widget_nav_bar_vtable()

const ra8_widget_vtable_t * ra8_widget_nav_bar_vtable ( void )

Return the shared vtable backing every navigation-strip widget.

One immutable vtable serves all nav strips: render fills the strip and centres each label in its cell through the strip's ra8_widget_paint_t; on_input maps a touch to a cell and fires on_select; measure is NULL. ra8_widget_nav_bar_init binds it.

Returns: Non-NULL pointer to the static nav-strip 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_nav_bar_init

Since: 0.1.0

Definition at line 226 of file ra8_widget_nav_bar.c.

References s_nav_vt.

Referenced by ra8_widget_nav_bar_init(), and wd_build_tree().

Variable Documentation

◆ s_nav_vt

const ra8_widget_vtable_t s_nav_vt

static

Initial value:

                                          = {
  .measure  = nullptr,
  .render   = internal_nav_render,
  .on_input = internal_nav_on_input,
}

The single immutable vtable shared by every nav strip.

Definition at line 220 of file ra8_widget_nav_bar.c.

Referenced by ra8_widget_nav_bar_vtable().

◆ s_tag

const char* s_tag = "ra8_widget_nav_bar"

static

Logging / check tag.

Definition at line 30 of file ra8_widget_nav_bar.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_widget_nav_geom_t

Function Documentation

◆ internal_nav_cell()

◆ internal_nav_hit()

◆ internal_nav_item()

◆ internal_nav_on_input()

◆ internal_nav_render()

◆ ra8_widget_nav_bar_init()

◆ ra8_widget_nav_bar_vtable()

Variable Documentation

◆ s_nav_vt

◆ s_tag