Reflowed-reading-body leaf widget for the ra8_widget tree (#145 Phase 2). More...

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

Include dependency graph for ra8_widget_reflow_view.c:

Enumerations
enum	ra8_widget_rv_geom_t : uint16_t { k_ra8_widget_rv_first = 0U , k_ra8_widget_rv_one = 1U }
	Paging constants (no magic numbers). More...

Functions
static ra8_ui_rect_t	internal_rv_body (const ra8_ui_rect_t *rect, int16_t mx, int16_t my)
	Body rectangle: the widget rect inset by the view margins.
static uint16_t	internal_rv_clamp (uint16_t page, uint16_t count)
	Clamp a page index into [0, count - 1].
static bool	internal_rv_turn (ra8_widget_reflow_view_t *v, int32_t px, int32_t mid)
	Turn the page by a tap side, clamped at both ends.
static void	internal_rv_render (ra8_widget_t *w)
	Reflow-view vtable render: clear the body, ask the seam to paint it.
static bool	internal_rv_link (ra8_widget_t w, ra8_widget_reflow_view_t v, const ra8_widget_event_t *ev)
	Try to follow a link at the tap through the seam.
static bool	internal_rv_on_input (ra8_widget_t w, const ra8_widget_event_t ev)
	Reflow-view vtable input: follow a link, else turn the page.
const ra8_widget_vtable_t *	ra8_widget_reflow_view_vtable (void)
	Return the shared vtable backing every reflow-view widget.
ra8_err_t	ra8_widget_reflow_view_init (ra8_widget_t w, ra8_widget_reflow_view_t view)
	Bind a widget instance to a reflow view.

Variables
static const char *	s_tag = "ra8_widget_reflow_view"
	Logging / check tag.
static const ra8_widget_vtable_t	s_rv_vt
	The single immutable vtable shared by every reflow view.

Detailed Description

Reflowed-reading-body leaf widget for the ra8_widget tree (#145 Phase 2).

Extracts the e-reader Reading body into a reusable ra8_widget leaf that owns the paging state + tap routing while reaching the ra8_reflow engine through the injected ra8_widget_reflow_ops_t seam. That seam is what keeps the file (and the whole ra8_widget library) free of ra8_reflow / ra8_gfx: the pure page-turn clamping (internal_rv_turn / internal_rv_clamp) and link routing are host-testable with a mock seam; the pixel work lives in the app-bound callbacks.

[Ring 5 / UI] {World: NS}

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

Since: 0.1.0

Definition in file ra8_widget_reflow_view.c.

Enumeration Type Documentation

◆ ra8_widget_rv_geom_t

enum ra8_widget_rv_geom_t : uint16_t

Paging constants (no magic numbers).

Enumerator
k_ra8_widget_rv_first	First page index / empty book.
k_ra8_widget_rv_one	One-page step / minimum count.

Definition at line 37 of file ra8_widget_reflow_view.c.

Function Documentation

◆ internal_rv_body()

ra8_ui_rect_t internal_rv_body	(	const ra8_ui_rect_t *	rect,
		int16_t	mx,
		int16_t	my )

static

Body rectangle: the widget rect inset by the view margins.

Shrinks rect by mx horizontally and my vertically so the reflowed page paints inside the margins rather than against the band edge. The seam's render_page receives this rect.

Parameters

[in]	rect	The widget rect (non-NULL).
[in]	mx	Horizontal inset, pixels.
[in]	my	Vertical inset, pixels.

Returns: The inset body rectangle.

Return values

body	The inset body 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 60 of file ra8_widget_reflow_view.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_rv_render().

◆ internal_rv_clamp()

uint16_t internal_rv_clamp	(	uint16_t	page,
		uint16_t	count )

static

Clamp a page index into [0, count - 1].

Guards a link destination the seam may return out of range: an empty book (count == 0) clamps to 0, a too-large page clamps to the last page, otherwise the page passes through unchanged.

Parameters

[in]	page	Candidate page.
[in]	count	Total pages.

Returns: page clamped into range (0 for an empty book).

Return values

page	The clamped page index.

Precondition: None.; None.

Postcondition: The result is < count when count > 0, else 0.; No state is modified.

Note: Pure.

Since: 0.1.0

Definition at line 89 of file ra8_widget_reflow_view.c.

References k_ra8_widget_rv_first, and k_ra8_widget_rv_one.

Referenced by internal_rv_link().

◆ internal_rv_link()

bool internal_rv_link	(	ra8_widget_t *	w,
		ra8_widget_reflow_view_t *	v,
		const ra8_widget_event_t *	ev )

static

Try to follow a link at the tap through the seam.

When the seam supplies a follow_link callback and it reports a link was followed, adopts the (clamped) destination page and marks the view dirty for a full redraw. Split out so internal_rv_on_input stays small.

Parameters

[in,out]	w	The reflow-view widget (non-NULL).
[in]	v	The view descriptor (non-NULL).
[in]	ev	The touch event (non-NULL).

Returns: true if a link was followed (page adopted), false otherwise.

Return values

true	A link jump changed the page.
false	No seam / no link at the tap.

Precondition: w, v, ev are non-NULL.; None.

Postcondition: On true v->page is the clamped link destination and w is dirty.; No state changes when no link is followed.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 189 of file ra8_widget_reflow_view.c.

References internal_rv_clamp(), k_ra8_widget_refresh_quality, ra8_widget_invalidate(), ra8_widget_event_t::x, and ra8_widget_event_t::y.

Referenced by internal_rv_on_input().

◆ internal_rv_on_input()

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

static

Reflow-view vtable input: follow a link, else turn the page.

A touch is offered to the link seam first; if no link is followed it turns the page by the tap side (internal_rv_turn), marking the view dirty for a quality redraw only when the page actually changed. Any body touch is consumed; a button event is declined.

Parameters

[in]	w	The reflow-view widget (its ctx is a ra8_widget_reflow_view_t).
[in]	ev	The event already routed to this view.

Returns: true if a body touch was consumed, false otherwise.

Return values

true	`ev` was a touch (link-followed or page-turned or a no-op tap).
false	`ev` was not a touch (or ctx is NULL).

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

Postcondition: On a page change w is dirty with the quality hint.; No state changes on a non-touch event.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 222 of file ra8_widget_reflow_view.c.

References internal_rv_link(), internal_rv_turn(), k_ra8_widget_ev_touch, k_ra8_widget_refresh_quality, ra8_widget_event_t::kind, ra8_widget_invalidate(), and ra8_widget_event_t::x.

◆ internal_rv_render()

void internal_rv_render ( ra8_widget_t * w )

static

Reflow-view vtable render: clear the body, ask the seam to paint it.

Reads the ra8_widget_reflow_view_t from w->ctx, clears the widget rect to bg through the paint backend, then – when the seam has a render_page callback – asks it to paint the current page inside the body rect (the widget rect inset by the margins).

Parameters

[in] w The reflow-view widget (its ctx is a ra8_widget_reflow_view_t).

Returns: Nothing.

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

Postcondition: At most a background clear plus one page paint are issued.; No page is painted when the seam is inert.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 152 of file ra8_widget_reflow_view.c.

References internal_rv_body(), and priv_widget_fill_box().

◆ internal_rv_turn()

bool internal_rv_turn	(	ra8_widget_reflow_view_t *	v,
		int32_t	px,
		int32_t	mid )

static

Turn the page by a tap side, clamped at both ends.

A tap left of mid steps back one page (a no-op on the first page); a tap at or right of mid steps forward one page (a no-op on the last page). Split out so internal_rv_on_input stays small and the boundary decisions are branch-coverable.

Parameters

[in,out]	v	Reflow-view descriptor (non-NULL).
[in]	px	Tap X (pixels).
[in]	mid	Body-rect horizontal midpoint (pixels).

Returns: true if v->page changed, false at a boundary.

Return values

true	The page stepped back or forward.
false	The tap was at a page boundary (no change).

Precondition: v is non-NULL.; None.

Postcondition: v->page stays within [0, page_count - 1].; Returns whether the page changed.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 120 of file ra8_widget_reflow_view.c.

References k_ra8_widget_rv_first, and k_ra8_widget_rv_one.

Referenced by internal_rv_on_input().

◆ ra8_widget_reflow_view_init()

ra8_err_t ra8_widget_reflow_view_init	(	ra8_widget_t *	w,
		ra8_widget_reflow_view_t *	view )

nodiscard

Bind a widget instance to a reflow view.

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

Returns: ra8_err_t

Return values

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

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

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

Note: Not thread-safe.

See also: ra8_widget_reflow_view_vtable

Since: 0.1.0

Definition at line 253 of file ra8_widget_reflow_view.c.

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

◆ ra8_widget_reflow_view_vtable()

const ra8_widget_vtable_t * ra8_widget_reflow_view_vtable ( void )

Return the shared vtable backing every reflow-view widget.

One immutable vtable serves all reflow views: render clears the body and asks the seam to paint the current page; on_input follows a link or turns the page; measure is NULL. ra8_widget_reflow_view_init binds it.

Returns: Non-NULL pointer to the static reflow-view 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_reflow_view_init

Since: 0.1.0

Definition at line 248 of file ra8_widget_reflow_view.c.

References s_rv_vt.

Referenced by ra8_widget_reflow_view_init().

Variable Documentation

◆ s_rv_vt

const ra8_widget_vtable_t s_rv_vt

static

Initial value:

                                         = {
  .measure  = nullptr,
  .render   = internal_rv_render,
  .on_input = internal_rv_on_input,
}

The single immutable vtable shared by every reflow view.

Definition at line 242 of file ra8_widget_reflow_view.c.

Referenced by ra8_widget_reflow_view_vtable().

◆ s_tag

const char* s_tag = "ra8_widget_reflow_view"

static

Logging / check tag.

Definition at line 31 of file ra8_widget_reflow_view.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_widget_rv_geom_t

Function Documentation

◆ internal_rv_body()

◆ internal_rv_clamp()

◆ internal_rv_link()

◆ internal_rv_on_input()

◆ internal_rv_render()

◆ internal_rv_turn()

◆ ra8_widget_reflow_view_init()

◆ ra8_widget_reflow_view_vtable()

Variable Documentation

◆ s_rv_vt

◆ s_tag