ra8_widget_progress_bar.c File Reference

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

#include "ra8_widget_progress_bar.h"
#include "ra8_check.h"
#include "ra8_widget.h"
#include "ra8_widget_internal.h"

Include dependency graph for ra8_widget_progress_bar.c:

Go to the source code of this file.

Enumerations
enum	ra8_widget_pb_geom_t : int32_t { k_ra8_widget_pb_empty = 0 }
	Empty-bar sentinel: at or below this fill width, no fill is painted. More...

Functions
static void	internal_pb_render (ra8_widget_t *w)
	Progress-bar vtable render: fill the track, then the proportional fill.
const ra8_widget_vtable_t *	ra8_widget_progress_bar_vtable (void)
	Return the shared vtable backing every progress-bar widget.
ra8_err_t	ra8_widget_progress_bar_init (ra8_widget_t *w, ra8_widget_progress_bar_t *bar)
	Bind a widget instance to a progress bar.

Variables
static const char *	s_tag = "ra8_widget_progress_bar"
	Logging / check tag.
static const ra8_widget_vtable_t	s_pb_vt
	The single immutable vtable shared by every progress bar.

Detailed Description

Progress-bar leaf widget for the ra8_widget tree model (#145 Phase 2).

Extracts the e-reader footer / book-card progress indicator into a reusable ra8_widget leaf: a track fill plus a proportional value / total fill, painted through the injected ra8_widget_paint_t backend so the file carries no ra8_gfx dependency. The fill-fraction maths (::internal_pb_fill_w) clamps value into [0, total] and guards a zero total / zero-width rect, so a bar never divides by zero and never overflows its rect. Display-only: the vtable leaves on_input NULL.

[Ring 5 / UI] {World: NS}

Copyright

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

Since

0.1.0

Definition in file ra8_widget_progress_bar.c.

Enumeration Type Documentation

ra8_widget_pb_geom_t

enum ra8_widget_pb_geom_t : int32_t

Empty-bar sentinel: at or below this fill width, no fill is painted.

Enumerator
k_ra8_widget_pb_empty	No filled pixels (0% or degenerate rect).

Definition at line 35 of file ra8_widget_progress_bar.c.

Function Documentation

internal_pb_render()

void internal_pb_render ( ra8_widget_t * w )

static

Progress-bar vtable render: fill the track, then the proportional fill.

Reads the ra8_widget_progress_bar_t from w->ctx, fills the whole rect with track, then – when the fill fraction is non-zero – fills the leftmost ::internal_pb_fill_w pixels with fill. A missing paint backend / fill_rect callback is a safe no-op.

Parameters

[in]

w

The progress-bar widget (its ctx is a ra8_widget_progress_bar_t).

Returns

Nothing.

Precondition

w is non-NULL (guaranteed by ra8_widget_render_dirty).

w->ctx points at a valid bar descriptor or is NULL.

Postcondition

At most a track fill plus one proportional fill are issued.

No pixels are touched when the bar has no paint backend.

Note

Not thread-safe.

Since

0.1.0

Definition at line 55 of file ra8_widget_progress_bar.c.

References ra8_ui_rect_t::h, k_ra8_widget_pb_empty, priv_widget_fill_frac(), ra8_ui_rect_t::w, ra8_ui_rect_t::x, and ra8_ui_rect_t::y.

ra8_widget_progress_bar_init()

ra8_err_t ra8_widget_progress_bar_init ( ra8_widget_t * w, ra8_widget_progress_bar_t * bar )

nodiscard

Bind a widget instance to a progress bar.

Wires w to render bar: sets its vtable to ra8_widget_progress_bar_vtable, points its ctx at bar, 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 progress bar (non-NULL).
[in]	bar	Progress-bar descriptor (non-NULL; outlives w's use).

Returns

ra8_err_t

Return values

k_ra8_ok	Bound; w renders bar.
k_ra8_err_null_ptr	w or bar is NULL.

Precondition

w and bar are non-NULL.

bar outlives every render of w.

Postcondition

On success w->vt == ra8_widget_progress_bar_vtable(), w->ctx == bar, w->visible == true.

On failure w is left unchanged.

Note

Not thread-safe.

See also

ra8_widget_progress_bar_vtable

Since

0.1.0

Definition at line 87 of file ra8_widget_progress_bar.c.

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

ra8_widget_progress_bar_vtable()

const ra8_widget_vtable_t * ra8_widget_progress_bar_vtable

(

void

)

Return the shared vtable backing every progress-bar widget.

One immutable vtable serves all progress bars: render fills the track then the proportional fill through the bar's ra8_widget_paint_t; measure and on_input are NULL (a progress bar sizes from its parent's fixed/flex and never consumes input). ra8_widget_progress_bar_init binds it, so callers rarely need it directly – it is exposed for tests and hand-built widgets.

Returns

Non-NULL pointer to the static progress-bar 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_progress_bar_init

Since

0.1.0

Definition at line 82 of file ra8_widget_progress_bar.c.

References s_pb_vt.

Referenced by ra8_widget_progress_bar_init(), and wd_build_tree().

Variable Documentation

s_pb_vt

const ra8_widget_vtable_t s_pb_vt

static

Initial value:

                                         = {
  .measure  = nullptr,
  .render   = internal_pb_render,
  .on_input = nullptr,
}

The single immutable vtable shared by every progress bar.

Definition at line 76 of file ra8_widget_progress_bar.c.

Referenced by ra8_widget_progress_bar_vtable().

s_tag

const char* s_tag = "ra8_widget_progress_bar"

static

Logging / check tag.

Definition at line 30 of file ra8_widget_progress_bar.c.