ra8_widget_button.c File Reference

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

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

Include dependency graph for ra8_widget_button.c:

Go to the source code of this file.

Functions
static uint32_t	internal_button_face (const ra8_widget_button_t *b)
	Pick the face fill colour for the button's current state.
static void	internal_button_render (ra8_widget_t *w)
	Button vtable render: paint the bordered face, then the label.
static bool	internal_button_on_input (ra8_widget_t *w, const ra8_widget_event_t *ev)
	Button vtable input: latch a touch, decline everything else.
const ra8_widget_vtable_t *	ra8_widget_button_vtable (void)
	Return the shared vtable backing every push-button widget.
ra8_err_t	ra8_widget_button_init (ra8_widget_t *w, ra8_widget_button_t *button)
	Bind a widget instance to a push button.

Variables
static const char *	s_tag = "ra8_widget_button"
	Logging / check tag.
static const ra8_widget_vtable_t	s_button_vt
	The single immutable vtable shared by every push button.

Detailed Description

Push-button leaf widget for the ra8_widget tree model (#145 Phase 2).

The interactive counterpart to the text label: a bordered, filled face with an aligned label that latches on a tap. render paints the face (a different fill while pressed) and label through the injected ra8_widget_paint_t backend; on_input consumes a touch the dispatcher has already hit-tested onto it – flipping pressed, bumping the presses counter, self-invalidating with the fast hint (so only this button's rect re-flushes through the panel's damage cycle), then firing the optional on_press callback. Button-kind events are declined so they keep routing. Like the rest of ra8_widget, 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_button.c.

Function Documentation

internal_button_face()

uint32_t internal_button_face ( const ra8_widget_button_t * b )

static

Pick the face fill colour for the button's current state.

Folds the pressed/released face selection out of the render body so it stays a single, branch-coverable decision.

Parameters

[in]

b

The button descriptor (non-NULL).

Returns

face_pressed when latched, else face.

Return values

b->face_pressed	When b->pressed is true.
b->face	When b->pressed is false.

Precondition

b is non-NULL.

None.

Postcondition

No state is modified.

Return is one of the two configured face colours.

Note

Pure.

Since

0.1.0

Definition at line 48 of file ra8_widget_button.c.

Referenced by internal_button_render().

internal_button_on_input()

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

static

Button vtable input: latch a touch, decline everything else.

A touch routed onto this button flips pressed, increments presses, marks the button dirty with the fast hint (so the panel flushes only this rect next compose), fires on_press if set, and reports the event consumed. Non-touch events return false so the dispatcher keeps offering them to other widgets.

Parameters

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

Returns

true if a touch was latched, false otherwise.

Return values

true	ev was a touch and the button latched it.
false	ev was not a touch (or ctx is NULL).

Precondition

w and ev are non-NULL.

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

Postcondition

On a touch pressed toggled and presses grew by one.

On a non-touch event no button state changed.

Note

Not thread-safe.

Since

0.1.0

Definition at line 115 of file ra8_widget_button.c.

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

internal_button_render()

void internal_button_render ( ra8_widget_t * w )

static

Button vtable render: paint the bordered face, then the label.

Reads the ra8_widget_button_t from w->ctx, fills its (optionally bordered) face for the current pressed state via priv_widget_fill_box, then – when there is text and a draw_text backend – places and draws the label over the face.

Parameters

[in]

w

The button widget (its ctx is a ra8_widget_button_t).

Returns

Nothing.

Precondition

w is non-NULL (guaranteed by ra8_widget_render_dirty).

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

Postcondition

At most the face fill(s) plus one text draw are issued.

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

Note

Not thread-safe.

Since

0.1.0

Definition at line 72 of file ra8_widget_button.c.

References internal_button_face(), priv_widget_fill_box(), and priv_widget_text_pos().

ra8_widget_button_init()

ra8_err_t ra8_widget_button_init ( ra8_widget_t * w, ra8_widget_button_t * button )

nodiscard

Bind a widget instance to a push button.

Wires w to render + route button: sets its vtable to ra8_widget_button_vtable, points its ctx at button, and makes it visible. The caller still sets w's fixed / flex (and usually its action_id) for its parent's layout and hit routing.

Parameters

[in,out]	w	Widget to turn into a button (non-NULL).
[in]	button	Button descriptor (non-NULL; outlives w's use).

Returns

ra8_err_t

Return values

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

Precondition

w and button are non-NULL.

button outlives every render / dispatch of w.

Postcondition

On success w->vt == ra8_widget_button_vtable(), w->ctx == button, w->visible == true.

On failure w is left unchanged.

Note

Not thread-safe.

See also

ra8_widget_button_vtable

Since

0.1.0

Definition at line 145 of file ra8_widget_button.c.

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

Referenced by wk_build_tree().

ra8_widget_button_vtable()

const ra8_widget_vtable_t * ra8_widget_button_vtable

(

void

)

Return the shared vtable backing every push-button widget.

One immutable vtable serves all buttons: render paints the (optionally bordered) face and aligned label through the button's ra8_widget_paint_t; on_input latches a touch (flip pressed, bump presses, self-invalidate fast, call on_press) and consumes it, ignoring button events; measure is NULL. ra8_widget_button_init binds it.

Returns

Non-NULL pointer to the static button 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_button_init

Since

0.1.0

Definition at line 140 of file ra8_widget_button.c.

References s_button_vt.

Referenced by ra8_widget_button_init().

Variable Documentation

s_button_vt

const ra8_widget_vtable_t s_button_vt

static

Initial value:

                                             = {
  .measure  = nullptr,
  .render   = internal_button_render,
  .on_input = internal_button_on_input,
}

The single immutable vtable shared by every push button.

Definition at line 134 of file ra8_widget_button.c.

Referenced by ra8_widget_button_vtable().

s_tag

const char* s_tag = "ra8_widget_button"

static

Logging / check tag.

Definition at line 30 of file ra8_widget_button.c.