ra8_widget_keyboard.c File Reference

On-screen-keyboard leaf widget for the ra8_widget tree (#145 Phase 2). More...

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

Include dependency graph for ra8_widget_keyboard.c:

Go to the source code of this file.

Enumerations
enum	ra8_widget_kbd_geom_t : uint8_t {   k_ra8_widget_kbd_glyph_char = 0U ,   k_ra8_widget_kbd_glyph_nul = 1U ,   k_ra8_widget_kbd_glyph_len = 2U ,   k_ra8_widget_kbd_no_glyph = 0U }
	Glyph-buffer indices (no magic numbers). More...

Functions
static void	internal_kbd_key (const ra8_widget_keyboard_t *kbd, const ra8_widget_key_info_t *info)
	Draw one key: a bordered face plus its centred glyph or label.
static void	internal_kbd_render (ra8_widget_t *w)
	Keyboard vtable render: fill the background, draw every key.
static bool	internal_kbd_on_input (ra8_widget_t *w, const ra8_widget_event_t *ev)
	Keyboard vtable input: hit a key, apply it, fire the commit edge.
const ra8_widget_vtable_t *	ra8_widget_keyboard_vtable (void)
	Return the shared vtable backing every on-screen-keyboard widget.
ra8_err_t	ra8_widget_keyboard_init (ra8_widget_t *w, ra8_widget_keyboard_t *kbd)
	Bind a widget instance to an on-screen keyboard.

Variables
static const char *	s_tag = "ra8_widget_keyboard"
	Logging / check tag.
static const ra8_widget_vtable_t	s_kbd_vt
	The single immutable vtable shared by every on-screen keyboard.

Detailed Description

On-screen-keyboard leaf widget for the ra8_widget tree (#145 Phase 2).

Extracts the e-reader search keyboard into a reusable ra8_widget leaf. The widget owns the key drawing (a bordered face + centred glyph / label) and the tap routing (hit -> apply -> commit edge -> on_commit); the ra8_keyboard engine is reached through the injected ra8_widget_keyboard_ops_t seam, so the file (and the whole ra8_widget library) never links ra8_keyboard. Painting goes through the injected ra8_widget_paint_t backend, so the render + route logic is host-testable with a recording mock seam + paint.

[Ring 5 / UI] {World: NS}

Copyright

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

Since

0.1.0

Definition in file ra8_widget_keyboard.c.

Enumeration Type Documentation

ra8_widget_kbd_geom_t

enum ra8_widget_kbd_geom_t : uint8_t

Glyph-buffer indices (no magic numbers).

Enumerator
k_ra8_widget_kbd_glyph_char	Glyph char slot in the 2-byte buffer.
k_ra8_widget_kbd_glyph_nul	NUL terminator slot.
k_ra8_widget_kbd_glyph_len	Single-glyph string buffer length.
k_ra8_widget_kbd_no_glyph	glyph == 0: not a character key.

Definition at line 36 of file ra8_widget_keyboard.c.

Function Documentation

internal_kbd_key()

void internal_kbd_key ( const ra8_widget_keyboard_t * kbd, const ra8_widget_key_info_t * info )

static

Draw one key: a bordered face plus its centred glyph or label.

Fills the key's key_face face (framed by border_w), then centres its text – a single-character string for a character key, or the special-key label – through the paint backend. A key with neither a glyph nor a label draws just its face.

Parameters

[in]	kbd	The keyboard descriptor (non-NULL; paint non-NULL).
[in]	info	The key's geometry + glyph / label (non-NULL).

Returns

Nothing.

Precondition

kbd and info are non-NULL; kbd->paint is non-NULL.

None.

Postcondition

At most a framed face plus one text draw are issued for the key.

No text is drawn when the backend has no draw_text.

Note

Not thread-safe.

Since

0.1.0

Definition at line 60 of file ra8_widget_keyboard.c.

References k_ra8_widget_align_center, k_ra8_widget_kbd_glyph_char, k_ra8_widget_kbd_glyph_len, k_ra8_widget_kbd_glyph_nul, k_ra8_widget_kbd_no_glyph, priv_widget_fill_box(), and priv_widget_text_pos().

Referenced by internal_kbd_render().

internal_kbd_on_input()

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

static

Keyboard vtable input: hit a key, apply it, fire the commit edge.

A touch is mapped to a key via the seam's hit; a real key is applied via apply (which returns whether the query is now committed), the widget self-invalidates for a redraw, and on_commit fires when apply reports a commit. Any touch is consumed (the keyboard owns its band); a button event is declined.

Parameters

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

Returns

true if a touch was consumed, false otherwise.

Return values

true	ev was a touch (key applied or a gap tap).
false	ev was not a touch (or ctx is NULL).

Precondition

w and ev are non-NULL.

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

Postcondition

On a key hit the seam applied it and w is dirty.

on_commit fires exactly when apply reports a commit.

Note

Not thread-safe.

Since

0.1.0

Definition at line 140 of file ra8_widget_keyboard.c.

References k_ra8_widget_ev_touch, k_ra8_widget_key_no_hit, k_ra8_widget_refresh_quality, ra8_widget_event_t::kind, ra8_widget_invalidate(), ra8_widget_event_t::x, and ra8_widget_event_t::y.

internal_kbd_render()

void internal_kbd_render ( ra8_widget_t * w )

static

Keyboard vtable render: fill the background, draw every key.

Reads the ra8_widget_keyboard_t from w->ctx, fills the widget rect with bg, then – when the seam supplies count + key_info – asks it for each key and paints it via internal_kbd_key. An inert seam or a missing paint backend is a no-op beyond the background.

Parameters

[in]

w

The keyboard widget (its ctx is a ra8_widget_keyboard_t).

Returns

Nothing.

Precondition

w is non-NULL (guaranteed by ra8_widget_render_dirty).

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

Postcondition

At most a background fill plus count key paints are issued.

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

Note

Not thread-safe; loop bounded by the seam's count (NASA Rule 2).

Since

0.1.0

Definition at line 99 of file ra8_widget_keyboard.c.

References internal_kbd_key(), and priv_widget_fill_box().

ra8_widget_keyboard_init()

ra8_err_t ra8_widget_keyboard_init ( ra8_widget_t * w, ra8_widget_keyboard_t * kbd )

nodiscard

Bind a widget instance to an on-screen keyboard.

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

Returns

ra8_err_t

Return values

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

Precondition

w and kbd are non-NULL.

kbd outlives every render / dispatch of w.

Postcondition

On success w->vt == ra8_widget_keyboard_vtable(), w->ctx == kbd, w->visible == true.

On failure w is left unchanged.

Note

Not thread-safe.

See also

ra8_widget_keyboard_vtable

Since

0.1.0

Definition at line 176 of file ra8_widget_keyboard.c.

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

ra8_widget_keyboard_vtable()

const ra8_widget_vtable_t * ra8_widget_keyboard_vtable

(

void

)

Return the shared vtable backing every on-screen-keyboard widget.

One immutable vtable serves all keyboards: render fills the background and draws every key through the keyboard's ra8_widget_paint_t + seam; on_input maps a touch to a key, applies it, and fires on_commit on the commit edge; measure is NULL. ra8_widget_keyboard_init binds it.

Returns

Non-NULL pointer to the static keyboard 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_keyboard_init

Since

0.1.0

Definition at line 171 of file ra8_widget_keyboard.c.

References s_kbd_vt.

Referenced by ra8_widget_keyboard_init().

Variable Documentation

s_kbd_vt

const ra8_widget_vtable_t s_kbd_vt

static

Initial value:

                                          = {
  .measure  = nullptr,
  .render   = internal_kbd_render,
  .on_input = internal_kbd_on_input,
}

The single immutable vtable shared by every on-screen keyboard.

Definition at line 165 of file ra8_widget_keyboard.c.

Referenced by ra8_widget_keyboard_vtable().

s_tag

const char* s_tag = "ra8_widget_keyboard"

static

Logging / check tag.

Definition at line 30 of file ra8_widget_keyboard.c.