ra8_widget_panel.c File Reference

Container-panel compositor for the ra8_widget tree model (#145). More...

#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_widget.h"

Include dependency graph for ra8_widget_panel.c:

Go to the source code of this file.

Functions
static ra8_err_t	internal_panel_layout (const ra8_widget_panel_t *p, const ra8_ui_rect_t *rect)
	Lay a panel's children out inside a rectangle.
static ra8_err_t	internal_compose_check (ra8_widget_t *panel_w, const ra8_ui_rect_t *frame, const ra8_ui_rect_t *out_damage, const ra8_widget_refresh_t *out_hint, const uint16_t *out_dirty, ra8_widget_panel_t **out_panel)
	Validate ra8_widget_panel_compose arguments and extract the panel.
static void	internal_panel_render (ra8_widget_t *w)
	Panel vtable render: lay out + composite the whole subtree.
static bool	internal_panel_on_input (ra8_widget_t *w, const ra8_widget_event_t *ev)
	Panel vtable input: route the event down to the children.
const ra8_widget_vtable_t *	ra8_widget_panel_vtable (void)
	Return the shared vtable that every container panel uses.
ra8_err_t	ra8_widget_panel_init (ra8_widget_t *w, ra8_widget_panel_t *panel)
	Bind a widget instance to a container panel.
ra8_err_t	ra8_widget_panel_compose (ra8_widget_t *panel_w, const ra8_ui_rect_t *frame, ra8_ui_rect_t *out_damage, ra8_widget_refresh_t *out_hint, uint16_t *out_dirty)
	Run one top-level compose cycle over a panel and report the flush.

Variables
static const char *	s_tag = "ra8_widget_panel"
	Logging / check tag.
static const ra8_widget_vtable_t	s_panel_vt
	The single immutable vtable shared by every container panel.

Detailed Description

Container-panel compositor for the ra8_widget tree model (#145).

A panel is a ra8_widget_t whose ctx points at a ra8_widget_panel_t child array. Binding the shared panel vtable (ra8_widget_panel_vtable) turns a widget into a container, which is what lifts the flat widget array into a tree: because a panel is itself a widget, a panel can be a child of another panel. The compositor logic is delegated to the existing flat ops – ra8_widget_layout_stack (layout), ra8_widget_damage (minimal flush rect) and ra8_widget_render_dirty (composite) – so this file adds only the tree-recursion glue and stays free of any framebuffer 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_panel.c.

Function Documentation

internal_compose_check()

ra8_err_t internal_compose_check ( ra8_widget_t * panel_w, const ra8_ui_rect_t * frame, const ra8_ui_rect_t * out_damage, const ra8_widget_refresh_t * out_hint, const uint16_t * out_dirty, ra8_widget_panel_t ** out_panel )

static

Validate ra8_widget_panel_compose arguments and extract the panel.

Split out so the compose entry point stays under the NASA Rule 4 statement budget: it folds the five null guards plus the panel / child-array check into one place and hands back the panel pointer.

Parameters

[in]	panel_w	The root panel widget (its ctx is the panel).
[in]	frame	Outer rectangle pointer to null-check.
[in]	out_damage	Damage out-pointer to null-check.
[in]	out_hint	Refresh-hint out-pointer to null-check.
[in]	out_dirty	Dirty-count out-pointer to null-check.
[out]	out_panel	Receives the validated panel descriptor.

Returns

ra8_err_t

Return values

k_ra8_ok	Arguments valid; out_panel set.
k_ra8_err_null_ptr	Any of the checked pointers is NULL.
k_ra8_err_invalid_arg	panel_w is not a panel (NULL ctx/children).

Precondition

out_panel is non-NULL.

The other pointers are the caller's compose arguments.

Postcondition

On success *out_panel references the panel's descriptor.

On failure *out_panel is not relied upon by the caller.

Note

Not thread-safe.

Since

0.1.0

Definition at line 85 of file ra8_widget_panel.c.

References k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by ra8_widget_panel_compose().

internal_panel_layout()

ra8_err_t internal_panel_layout ( const ra8_widget_panel_t * p, const ra8_ui_rect_t * rect )

static

Lay a panel's children out inside a rectangle.

Thin forwarder to ra8_widget_layout_stack shared by the compose entry point and the nested-render callback, so each stays within the NASA Rule 4 size cap and the stack-layout call is written once.

Parameters

[in]	p	Panel descriptor (non-NULL; children covers count).
[in]	rect	Rectangle the children stack fills (non-NULL).

Returns

ra8_err_t Forwarded from ra8_widget_layout_stack.

Return values

k_ra8_ok	Children laid out; each visible rect set.
k_ra8_err_null_ptr	p->children or rect is NULL.
k_ra8_err_invalid_arg	Scratch too small for the visible child count.

Precondition

p and rect are non-NULL.

p->box_scratch holds at least count + 1 nodes.

Postcondition

On success every visible child has its rect assigned.

On failure no child rect is relied upon by the caller.

Note

Not thread-safe.

Since

0.1.0

Definition at line 50 of file ra8_widget_panel.c.

References ra8_widget_layout_stack().

Referenced by internal_panel_render(), and ra8_widget_panel_compose().

internal_panel_on_input()

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

static

Panel vtable input: route the event down to the children.

Offers the event to the panel's children via ra8_widget_dispatch (touch routed by hit-test, button offered first-consumer). A child that is itself a panel re-enters here; depth is bounded by the caller's static tree (NASA Rule 1).

Parameters

[in]	w	The panel widget (its ctx is a ra8_widget_panel_t).
[in]	ev	The event already routed to this panel.

Returns

true if some child consumed the event, false otherwise.

Return values

true	A child's on_input consumed ev.
false	No child consumed it (or the panel has no children).

Precondition

w and ev are non-NULL.

w->ctx points at a valid panel descriptor.

Postcondition

No widget state changes beyond what a child's on_input performs.

The return reflects whether a child consumed ev.

Note

Not thread-safe.

Since

0.1.0

Definition at line 162 of file ra8_widget_panel.c.

References ra8_widget_dispatch().

internal_panel_render()

void internal_panel_render ( ra8_widget_t * w )

static

Panel vtable render: lay out + composite the whole subtree.

Runs when a panel is a dirty child of another panel: it lays its children out inside the panel's rect, marks every visible child dirty with the panel's own refresh hint (a dirty panel repaints its whole subtree), then composites them via ra8_widget_render_dirty. A child that is itself a panel re-enters here, so the recursion is bounded by the caller's static tree depth (NASA Rule 1).

Parameters

[in]

w

The panel widget (its ctx is a ra8_widget_panel_t).

Returns

Nothing.

Precondition

w is non-NULL (guaranteed by ra8_widget_render_dirty).

w->ctx points at a valid panel descriptor.

Postcondition

Every visible child has been rendered for this subtree.

No child remains dirty after the render pass.

Note

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

Since

0.1.0

Definition at line 123 of file ra8_widget_panel.c.

References internal_panel_layout(), k_ra8_ok, k_ra8_widget_refresh_none, k_ra8_widget_refresh_quality, ra8_widget_invalidate(), and ra8_widget_render_dirty().

ra8_widget_panel_compose()

ra8_err_t ra8_widget_panel_compose ( ra8_widget_t * panel_w, const ra8_ui_rect_t * frame, ra8_ui_rect_t * out_damage, ra8_widget_refresh_t * out_hint, uint16_t * out_dirty )

nodiscard

Run one top-level compose cycle over a panel and report the flush.

The compositor pass the issue asks for, packaged as one call:

1. Pin the panel to frame (panel_w->rect = *frame).
2. Lay the panel's children out inside it (ra8_widget_layout_stack).
3. Compute the minimal damage rectangle + folded refresh hint over the dirty children (ra8_widget_damage) – what the caller hands to display_flush.
4. Composite by rendering only the dirty children (ra8_widget_render_dirty); a dirty child that is itself a panel repaints its whole subtree.

Marking the whole tree dirty before the call yields a full-frame quality flush; marking only one child (e.g. the status bar) yields just that child's rect with its hint – the damage-tracked partial update.

Parameters

[in,out]	panel_w	The root panel widget (bound via panel_init).
[in]	frame	Outer rectangle the panel fills (the framebuffer).
[out]	out_damage	Receives the union rect to flush (empty if clean).
[out]	out_hint	Receives the folded refresh hint (none if clean).
[out]	out_dirty	Receives the number of dirty children composited.

Returns

ra8_err_t

Return values

k_ra8_ok	Composed; see out_dirty / out_damage.
k_ra8_err_null_ptr	Any pointer argument is NULL.
k_ra8_err_invalid_arg	panel_w is not a panel, or its scratch is too small (forwarded from the layout step).

Precondition

All pointer arguments are non-NULL.

panel_w was bound by ra8_widget_panel_init.

Postcondition

On success every dirty child has been rendered and cleared.

*out_dirty == 0 iff nothing was dirty (then *out_damage is empty).

Note

Not thread-safe. Descends the tree; depth is statically bounded by the caller's widget tree (NASA Rule 1).

See also

ra8_widget_damage

ra8_widget_render_dirty

Since

0.1.0

Definition at line 203 of file ra8_widget_panel.c.

References internal_compose_check(), internal_panel_layout(), k_ra8_ok, k_ra8_widget_refresh_none, ra8_widget_damage(), and ra8_widget_render_dirty().

Referenced by wc_compose(), wd_compose(), and wk_compose().

ra8_widget_panel_init()

ra8_err_t ra8_widget_panel_init ( ra8_widget_t * w, ra8_widget_panel_t * panel )

nodiscard

Bind a widget instance to a container panel.

Wires w to act as a container: sets its vtable to ra8_widget_panel_vtable, points its ctx at panel, and makes it visible. The caller still sets w's fixed / flex for its parent's layout (a root panel is typically pinned by ra8_widget_panel_compose, which sets its rect directly).

Parameters

[in,out]	w	Widget to turn into a panel (non-NULL).
[in]	panel	Panel descriptor (non-NULL; children covers count).

Returns

ra8_err_t

Return values

k_ra8_ok	Bound; w renders/routes panel's children.
k_ra8_err_null_ptr	w or panel is NULL.
k_ra8_err_invalid_arg	panel has count > 0 but a NULL child array or box_cap < count + 1.

Precondition

w and panel are non-NULL.

panel->box_scratch holds at least count + 1 nodes.

Postcondition

On success w->vt == ra8_widget_panel_vtable(), w->ctx == panel, w->visible == true.

On failure w is left unchanged.

Note

Not thread-safe.

See also

ra8_widget_panel_compose

Since

0.1.0

Definition at line 185 of file ra8_widget_panel.c.

References k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_widget_panel_vtable(), and s_tag.

Referenced by wc_build_tree(), wd_build_tree(), and wk_build_tree().

ra8_widget_panel_vtable()

const ra8_widget_vtable_t * ra8_widget_panel_vtable

(

void

)

Return the shared vtable that every container panel uses.

One immutable vtable backs all panels: its render lays out the panel's children inside the panel widget's rect and composites them (a dirty panel repaints its whole subtree); its on_input routes the event to the children via ra8_widget_dispatch; measure is NULL (a panel sizes from its parent's fixed/flex like any widget). ra8_widget_panel_init binds this vtable, so callers rarely need it directly – it is exposed for tests and for building a widget by hand.

Returns

Non-NULL pointer to the static panel 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).

Render/route descend the tree, so nesting depth is bounded by the caller's static tree – there is no data-dependent self-call (NASA Rule 1).

See also

ra8_widget_panel_init

Since

0.1.0

Definition at line 180 of file ra8_widget_panel.c.

References s_panel_vt.

Referenced by ra8_widget_panel_init().

Variable Documentation

s_panel_vt

const ra8_widget_vtable_t s_panel_vt

static

Initial value:

                                            = {
  .measure  = nullptr,
  .render   = internal_panel_render,
  .on_input = internal_panel_on_input,
}

The single immutable vtable shared by every container panel.

Definition at line 174 of file ra8_widget_panel.c.

Referenced by ra8_widget_panel_vtable().

s_tag

const char* s_tag = "ra8_widget_panel"

static

Logging / check tag.

Definition at line 29 of file ra8_widget_panel.c.