On-screen keyboard widget – iOS-style layers, shift, hit-test. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_ui.h"

Include dependency graph for ra8_keyboard.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ra8_kbd_key_t
	One key: a hit rectangle, its unshifted + shifted chars, a kind, and (for layer keys) the target layer in `aux`. More...
struct	ra8_kbd_layout_t
	The key grid for the active layer, plus SHIFT / layer / frame state. More...
struct	ra8_kbd_text_t
	The typed query buffer + commit state. More...

Enumerations
enum	ra8_kbd_limits_t : uint8_t { k_ra8_kbd_rows = 4U , k_ra8_kbd_max_keys = 40U , k_ra8_kbd_text_max = 64U , k_ra8_kbd_no_hit = 255U }
	Static capacities for the keyboard widget. More...
enum	ra8_kbd_layer_t : uint8_t { k_ra8_kbd_layer_letters = 0U , k_ra8_kbd_layer_numbers = 1U , k_ra8_kbd_layer_symbols = 2U }
	Which key set is shown. More...
enum	ra8_kbd_key_kind_t : uint8_t { k_ra8_kbd_key_char = 0U , k_ra8_kbd_key_space = 1U , k_ra8_kbd_key_backspace = 2U , k_ra8_kbd_key_enter = 3U , k_ra8_kbd_key_shift = 4U , k_ra8_kbd_key_layer = 5U }
	What a key does when tapped. More...

Functions
ra8_err_t	ra8_kbd_layout_init (ra8_kbd_layout_t kb, const ra8_ui_rect_t frame)
	Lay the letters layer into `frame`; clear SHIFT.
uint8_t	ra8_kbd_hit (const ra8_kbd_layout_t *kb, int32_t px, int32_t py)
	Map a tap to a key index.
char	ra8_kbd_key_glyph (const ra8_kbd_layout_t *kb, uint8_t key_idx)
	Effective character a char key emits given the live SHIFT state.
ra8_err_t	ra8_kbd_text_init (ra8_kbd_text_t *t)
	Reset a text buffer to empty / uncommitted.
ra8_err_t	ra8_kbd_apply (ra8_kbd_text_t t, ra8_kbd_layout_t kb, uint8_t key_idx)
	Apply key `key_idx` to the text buffer, SHIFT, and active layer.

Detailed Description

On-screen keyboard widget – iOS-style layers, shift, hit-test.

Tag: [Ring 4 / UI] {World: NS}

An immediate-mode on-screen keyboard for text entry (e-reader search / filter, #105), modelled on the iOS keyboard. Pure, rendering-free logic:

ra8_kbd_layout_init lays the letters layer into a caller frame: qwertyuiop / asdfghjkl (inset) / SHIFT + zxcvbnm + BACKSPACE / 123 + SPACE + RETURN, with the home row inset and SHIFT/BACKSPACE/123/ RETURN widened, like iOS.
The 123 key switches to the numbers/symbols layer (1234567890 / -/:;()$&@" / symbols + BACKSPACE / ABC + SPACE + RETURN); ABC switches back. Tapping a layer key re-lays the grid in place.
SHIFT is one-shot: it capitalises the next letter only (so Hello), then clears.
ra8_kbd_hit maps a tap to a key index; ra8_kbd_apply mutates the text buffer, the SHIFT state, and the active layer; ra8_kbd_key_glyph gives a renderer the current-case character for a key.

The caller owns rendering (draw each key + its glyph) and tap routing; this is the deterministic model underneath, unit-testable and HIL-gateable with synthetic taps.

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

Definition in file ra8_keyboard.h.

Enumeration Type Documentation

◆ ra8_kbd_key_kind_t

enum ra8_kbd_key_kind_t : uint8_t

What a key does when tapped.

Enumerator
k_ra8_kbd_key_char	Append the shift-correct char.
k_ra8_kbd_key_space	Append a space.
k_ra8_kbd_key_backspace	Delete the last char.
k_ra8_kbd_key_enter	Commit the query (RETURN).
k_ra8_kbd_key_shift	Toggle the one-shot SHIFT.
k_ra8_kbd_key_layer	Switch to the layer in aux.

Definition at line 70 of file ra8_keyboard.h.

◆ ra8_kbd_layer_t

enum ra8_kbd_layer_t : uint8_t

Which key set is shown.

Enumerator
k_ra8_kbd_layer_letters	QWERTY letters (with one-shot SHIFT).
k_ra8_kbd_layer_numbers	Digits + common symbols (123).
k_ra8_kbd_layer_symbols	Brackets / math symbols (#+=).

Definition at line 60 of file ra8_keyboard.h.

◆ ra8_kbd_limits_t

enum ra8_kbd_limits_t : uint8_t

Static capacities for the keyboard widget.

Enumerator
k_ra8_kbd_rows	Key rows per layer.
k_ra8_kbd_max_keys	Key-rect slots (<= 31 used per layer).
k_ra8_kbd_text_max	Text buffer capacity incl. NUL.
k_ra8_kbd_no_hit	ra8_kbd_hit "no key" sentinel.

Definition at line 49 of file ra8_keyboard.h.

Function Documentation

◆ ra8_kbd_apply()

ra8_err_t ra8_kbd_apply	(	ra8_kbd_text_t *	t,
		ra8_kbd_layout_t *	kb,
		uint8_t	key_idx )

nodiscard

Apply key key_idx to the text buffer, SHIFT, and active layer.

A char/space appends (shift-correct) and clears one-shot SHIFT; SHIFT toggles kb->shift; a layer key swaps the layer (re-laying the grid in place); backspace deletes; RETURN sets committed. Out-of-range / capacity edges are no-ops (still k_ra8_ok).

Parameters

[in,out]	t	Text buffer.
[in,out]	kb	Laid-out grid (SHIFT / layer / keys may change).
[in]	key_idx	Key index from ra8_kbd_hit.

Returns: ra8_err_t

Return values

k_ra8_ok	Applied (possibly a no-op at a capacity edge).
k_ra8_err_null_ptr	`t` or `kb` is NULL.

Precondition: t, kb non-NULL.; key_idx is a hit index or k_ra8_kbd_no_hit (no-op).

Postcondition: t->buf stays NUL-terminated and t->len < k_ra8_kbd_text_max.; committed is true iff a RETURN key was applied.

Note: Not thread-safe relative to t / kb.

Since: 0.1.0

Definition at line 641 of file ra8_keyboard.c.

References ra8_kbd_key_t::aux, ra8_kbd_text_t::buf, ra8_kbd_key_t::ch_lower, ra8_kbd_key_t::ch_upper, ra8_kbd_text_t::committed, ra8_kbd_layout_t::count, internal_append(), internal_build_layer(), k_ra8_kbd_key_backspace, k_ra8_kbd_key_char, k_ra8_kbd_key_enter, k_ra8_kbd_key_layer, k_ra8_kbd_key_shift, k_ra8_kbd_key_space, k_ra8_ok, ra8_kbd_layout_t::keys, ra8_kbd_key_t::kind, ra8_kbd_layout_t::layer, ra8_kbd_text_t::len, RA8_CHECK_NULL_PTR, s_tag, and ra8_kbd_layout_t::shift.

Referenced by er_handle_keyboard_tap(), and kb_tap().

◆ ra8_kbd_hit()

uint8_t ra8_kbd_hit	(	const ra8_kbd_layout_t *	kb,
		int32_t	px,
		int32_t	py )

nodiscard

Map a tap to a key index.

Parameters

[in]	kb	Laid-out grid.
[in]	px	Tap X (pixels).
[in]	py	Tap Y (pixels).

Returns: Key index 0..kb->count-1, or k_ra8_kbd_no_hit if the tap hit no key (or kb is NULL).

Precondition: kb is laid out (or NULL, handled).; None.

Postcondition: No state modified.; Return is a valid index or k_ra8_kbd_no_hit.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 571 of file ra8_keyboard.c.

References ra8_kbd_layout_t::count, k_ra8_kbd_no_hit, ra8_kbd_layout_t::keys, ra8_ui_rect_contains(), and ra8_kbd_key_t::rect.

Referenced by kb_tap().

◆ ra8_kbd_key_glyph()

char ra8_kbd_key_glyph	(	const ra8_kbd_layout_t *	kb,
		uint8_t	key_idx )

nodiscard

Effective character a char key emits given the live SHIFT state.

Parameters

[in]	kb	Laid-out grid (for SHIFT).
[in]	key_idx	Key index.

Returns: The shift-correct char for a char key, or 0 for a non-char / invalid key (or NULL kb).

Precondition: kb is laid out (or NULL, handled).; None.

Postcondition: No state modified.

Note: Pure; lets a renderer label keys in the current case.

Since: 0.1.0

Definition at line 584 of file ra8_keyboard.c.

References ra8_kbd_key_t::ch_lower, ra8_kbd_key_t::ch_upper, ra8_kbd_layout_t::count, k_ra8_kbd_key_char, ra8_kbd_layout_t::keys, ra8_kbd_key_t::kind, and ra8_kbd_layout_t::shift.

Referenced by er_kbd_label().

◆ ra8_kbd_layout_init()

ra8_err_t ra8_kbd_layout_init	(	ra8_kbd_layout_t *	kb,
		const ra8_ui_rect_t *	frame )

nodiscard

Lay the letters layer into frame; clear SHIFT.

Parameters

[out]	kb	Receives the laid-out grid (letters layer, SHIFT cleared).
[in]	frame	Pixel rectangle to fill (w,h > 0); saved for layer swaps.

Returns: ra8_err_t

Return values

k_ra8_ok	Grid laid out.
k_ra8_err_null_ptr	`kb` or `frame` is NULL.
k_ra8_err_invalid_arg	`frame` has non-positive w or h.

Precondition: kb, frame non-NULL.; frame->w > 0 && frame->h > 0.

Postcondition: On success kb->layer == k_ra8_kbd_layer_letters and !kb->shift.; Every key rect lies within frame.

Note: Pure; not thread-safe relative to kb.

Since: 0.1.0

Definition at line 556 of file ra8_keyboard.c.

References ra8_kbd_layout_t::frame, ra8_ui_rect_t::h, internal_build_layer(), k_ra8_err_invalid_arg, k_ra8_kbd_layer_letters, k_ra8_ok, ra8_kbd_layout_t::layer, RA8_CHECK_NULL_PTR, s_tag, ra8_kbd_layout_t::shift, and ra8_ui_rect_t::w.

Referenced by er_kbd_keys_render(), and main().

◆ ra8_kbd_text_init()

ra8_err_t ra8_kbd_text_init ( ra8_kbd_text_t * t )

nodiscard

Reset a text buffer to empty / uncommitted.

Parameters

[out] t Buffer to clear.

Returns: ra8_err_t

Return values

k_ra8_ok	Cleared.
k_ra8_err_null_ptr	`t` is NULL.

Precondition: t non-NULL.; None.

Postcondition: t->len == 0 && t->buf[0] == '\0' && !t->committed.; Buffer ready for ra8_kbd_apply.

Note: Not thread-safe relative to t.

Since: 0.1.0

Definition at line 596 of file ra8_keyboard.c.

References ra8_kbd_text_t::buf, ra8_kbd_text_t::committed, k_ra8_ok, ra8_kbd_text_t::len, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by er_handle_tap(), and main().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_kbd_key_kind_t

◆ ra8_kbd_layer_t

◆ ra8_kbd_limits_t

Function Documentation

◆ ra8_kbd_apply()

◆ ra8_kbd_hit()

◆ ra8_kbd_key_glyph()

◆ ra8_kbd_layout_init()

◆ ra8_kbd_text_init()