On-screen keyboard widget – iOS-style layers + shift. More...

#include "ra8_keyboard.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_ui.h"

Include dependency graph for ra8_keyboard.c:

Enumerations
enum	kbd_geom_t : int32_t { k_kbd_hu_div = 20 , k_kbd_key_hu = 2 , k_kbd_wide_hu = 3 , k_kbd_inset_hu = 1 , k_kbd_act_hu = 4 , k_kbd_space_hu = 12 , k_kbd_top_keys = 10 , k_kbd_mid_keys = 9 , k_kbd_r2_lett = 7 , k_kbd_punct_n = 5 , k_kbd_punct_hu0 = 5 , k_kbd_sym1_n = 7 , k_kbd_sym1_hu0 = 3 , k_kbd_row1 = 1 , k_kbd_row2 = 2 , k_kbd_row3 = 3 }
	Row geometry in 20ths of the width ("half-units"), iOS proportions. More...

Functions
static void	internal_add (ra8_kbd_layout_t *kb, int32_t x, int32_t w, int32_t y, int32_t h, char lo, char hi, ra8_kbd_key_kind_t kind, uint8_t aux)
	Append one key descriptor to the layout, bounded by k_ra8_kbd_max_keys.
static int32_t	internal_hx (const ra8_ui_rect_t *f, int32_t hu)
	Compute the pixel X coordinate for a given half-unit offset within a frame.
static void	internal_place (ra8_kbd_layout_t kb, const char lo, const char hi, int32_t n, int32_t hu0, const ra8_ui_rect_t f, int32_t y, int32_t rh)
	Place `n` character keys, each k_kbd_key_hu (2) half-units wide, starting from half-unit offset `hu0`.
static void	internal_span (ra8_kbd_layout_t kb, int32_t a, int32_t b, const ra8_ui_rect_t f, int32_t y, int32_t rh, ra8_kbd_key_kind_t kind, uint8_t aux)
	Append one special key that spans half-units [`a`, `b`).
static void	internal_row_punct (ra8_kbd_layout_t kb, const ra8_ui_rect_t f, int32_t y, int32_t rh, uint8_t tog_aux)
	Build row 2 for the numbers or symbols layer: layer-toggle, punctuation, backspace.
static void	internal_row_bottom (ra8_kbd_layout_t kb, const ra8_ui_rect_t f, int32_t y, int32_t rh, uint8_t left_aux)
	Build the bottom row: a layer-toggle key, SPACE, and RETURN.
static void	internal_build_letters (ra8_kbd_layout_t kb, const ra8_ui_rect_t f, int32_t rh)
	Build the letters layer (QWERTY / SHIFT / 123 bottom-row toggle).
static void	internal_build_numbers (ra8_kbd_layout_t kb, const ra8_ui_rect_t f, int32_t rh)
	Build the numbers layer (digits, common symbols; #+= toggles to symbols).
static void	internal_build_symbols (ra8_kbd_layout_t kb, const ra8_ui_rect_t f, int32_t rh)
	Build the symbols layer (brackets, math operators; 123 toggles to numbers).
static void	internal_build_layer (ra8_kbd_layout_t *kb)
	Rebuild the key grid for the active layer stored in kb->layer.
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.
static void	internal_append (ra8_kbd_text_t *t, char ch)
	Append character `ch` to the text buffer if capacity allows.
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.

Variables
static const char *	s_tag = "KBD"
	Log tag for this module.
static const char	s_l_r0_lo [] = "qwertyuiop"
static const char	s_l_r0_hi [] = "QWERTYUIOP"
static const char	s_l_r1_lo [] = "asdfghjkl"
static const char	s_l_r1_hi [] = "ASDFGHJKL"
static const char	s_l_r2_lo [] = "zxcvbnm"
static const char	s_l_r2_hi [] = "ZXCVBNM"
static const char	s_n_r0 [] = "1234567890"
static const char	s_n_r1 [] = "-/:;()$&@\""
static const char	s_s_r0 [] = "[]{}#%^*+="
static const char	s_s_r1 [] = "<>\\_`\|~"
static const char	s_punct [] = ".,?!'"

Detailed Description

On-screen keyboard widget – iOS-style layers + shift.

Builds bounded letter, number, and symbol layouts, performs hit testing, and applies key actions to caller-owned text state without heap use.

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

Definition in file ra8_keyboard.c.

Enumeration Type Documentation

◆ kbd_geom_t

enum kbd_geom_t : int32_t

Row geometry in 20ths of the width ("half-units"), iOS proportions.

Enumerator
k_kbd_hu_div	Half-units per row (a normal key = 2 hu).
k_kbd_key_hu	Normal key width (half-units).
k_kbd_wide_hu	SHIFT / BACKSPACE width.
k_kbd_inset_hu	Home-row inset each side.
k_kbd_act_hu	123 / ABC / RETURN width.
k_kbd_space_hu	SPACE width.
k_kbd_top_keys	Keys in rows 0 and 1.
k_kbd_mid_keys	Keys in the inset home row.
k_kbd_r2_lett	Letters in letters row 2.
k_kbd_punct_n	Punctuation keys (. , ? ! ') in row 2.
k_kbd_punct_hu0	Centred start for the 5 punctuation keys.
k_kbd_sym1_n	Symbols row 1 keys (_ \ \| ~ < > `).
k_kbd_sym1_hu0	Centred start for symbols row 1.
k_kbd_row1	Row index 1.
k_kbd_row2	Row index 2.
k_kbd_row3	Row index 3.

Definition at line 30 of file ra8_keyboard.c.

Function Documentation

◆ internal_add()

void internal_add	(	ra8_kbd_layout_t *	kb,
		int32_t	x,
		int32_t	w,
		int32_t	y,
		int32_t	h,
		char	lo,
		char	hi,
		ra8_kbd_key_kind_t	kind,
		uint8_t	aux )

static

Append one key descriptor to the layout, bounded by k_ra8_kbd_max_keys.

Writes a single ra8_kbd_key_t entry into kb->keys[kb->count] and increments kb->count. If the layout is already at capacity (kb->count >= k_ra8_kbd_max_keys) the call is silently discarded so callers do not need to perform their own bounds check.

Parameters

[in,out]	kb	Layout being built; count is incremented on success.
[in]	x	Left edge of the key rectangle in screen pixels.
[in]	w	Width of the key rectangle in screen pixels.
[in]	y	Top edge of the key rectangle in screen pixels.
[in]	h	Height of the key rectangle in screen pixels.
[in]	lo	Character produced when shift is inactive (0 for special keys).
[in]	hi	Character produced when shift is active (0 for special keys).
[in]	kind	Key kind tag (char, space, backspace, shift, enter, layer).
[in]	aux	Auxiliary data; for k_ra8_kbd_key_layer this is the target layer index, otherwise 0.

Returns: Nothing.

Precondition: kb is not nullptr.; kb->count <= k_ra8_kbd_max_keys on entry.

Postcondition: If kb->count was less than k_ra8_kbd_max_keys, kb->count is incremented by exactly one and the new key slot is fully initialised.; If kb->count was already equal to k_ra8_kbd_max_keys, kb is unchanged.

Note: Not thread-safe; must be called from the same context as the owning ra8_kbd_layout_t initialisation.

Since: 0.1.0

Definition at line 100 of file ra8_keyboard.c.

References ra8_kbd_key_t::aux, ra8_kbd_key_t::ch_lower, ra8_kbd_key_t::ch_upper, ra8_kbd_layout_t::count, ra8_ui_rect_t::h, k_ra8_kbd_max_keys, ra8_kbd_layout_t::keys, ra8_kbd_key_t::kind, RA8_INTERNAL, ra8_kbd_key_t::rect, ra8_ui_rect_t::w, ra8_ui_rect_t::x, and ra8_ui_rect_t::y.

Referenced by internal_layout(), internal_place(), and internal_span().

◆ internal_append()

void internal_append	(	ra8_kbd_text_t *	t,
		char	ch )

static

Append character ch to the text buffer if capacity allows.

Checks whether t->len is strictly less than (k_ra8_kbd_text_max - 1) to preserve room for the NUL terminator. If there is space, writes ch at t->buf[t->len], increments t->len, and writes '\0' at the new t->len position. If the buffer is full the call is silently discarded so callers do not need to guard against overflow.

Parameters

[in,out]	t	Text buffer to append to; len and buf are modified on success.
[in]	ch	Character to append (must not be '\0').

Returns: Nothing.

Precondition: t is not nullptr.; t->len <= k_ra8_kbd_text_max - 1 on entry (invariant maintained by this function and ra8_kbd_apply()).

Postcondition: If t->len was less than (k_ra8_kbd_text_max - 1), t->len is incremented by one and t->buf[t->len] == '\0'.; t->buf is always NUL-terminated on exit.

Note: Not thread-safe; must be called from the same context as ra8_kbd_apply().

Since: 0.1.0

Definition at line 632 of file ra8_keyboard.c.

References ra8_kbd_text_t::buf, k_ra8_kbd_text_max, ra8_kbd_text_t::len, and RA8_INTERNAL.

Referenced by priv_fmt_host_spool_open(), ra8_fmt_jof_convert_stream(), and ra8_kbd_apply().

◆ internal_build_layer()

void internal_build_layer ( ra8_kbd_layout_t * kb )

static

Rebuild the key grid for the active layer stored in kb->layer.

Resets kb->count to zero, computes the uniform row height as kb->frame.h / k_ra8_kbd_rows, then dispatches to the appropriate layer builder:

k_ra8_kbd_layer_numbers -> internal_build_numbers()
k_ra8_kbd_layer_symbols -> internal_build_symbols()
any other value (including k_ra8_kbd_layer_letters) -> internal_build_letters() Called once at init and again every time the active layer changes (via ra8_kbd_apply() handling k_ra8_kbd_key_layer).

Parameters

[in,out] kb Layout to rebuild; kb->layer and kb->frame must be valid. kb->count is reset to 0 and then repopulated.

Returns: Nothing.

Precondition: kb is not nullptr.; kb->frame.h > 0 and kb->frame.w > 0 (ensured by ra8_kbd_layout_init).

Postcondition: kb->count == 0 before the layer builder runs, then reflects the number of keys placed by the selected builder.; Every key in kb->keys[0..kb->count-1] has a fully initialised rect, glyph pair, kind, and aux field.

Note: Not thread-safe; must be called from the same context that owns kb.

Since: 0.1.0

Definition at line 543 of file ra8_keyboard.c.

References ra8_kbd_layout_t::count, ra8_kbd_layout_t::frame, ra8_ui_rect_t::h, internal_build_letters(), internal_build_numbers(), internal_build_symbols(), k_ra8_kbd_layer_numbers, k_ra8_kbd_layer_symbols, k_ra8_kbd_rows, ra8_kbd_layout_t::layer, and RA8_INTERNAL.

Referenced by ra8_kbd_apply(), and ra8_kbd_layout_init().

◆ internal_build_letters()

void internal_build_letters	(	ra8_kbd_layout_t *	kb,
		const ra8_ui_rect_t *	f,
		int32_t	rh )

static

Build the letters layer (QWERTY / SHIFT / 123 bottom-row toggle).

Populates four rows into kb:

Row 0: 10-key QWERTY top row (s_l_r0_lo / s_l_r0_hi) at f->y.
Row 1: 9-key home row (s_l_r1_lo / s_l_r1_hi) inset by k_kbd_inset_hu.
Row 2: SHIFT (wide), 7 letter keys (s_l_r2_lo / s_l_r2_hi), BACKSPACE (wide).
Row 3: layer-toggle to numbers, SPACE, RETURN via internal_row_bottom(). The rh parameter is used as the uniform row height; f->y is the top of row 0 and subsequent rows are offset by multiples of rh.

Parameters

[in,out]	kb	Layout being built; all letter-layer keys are appended.
[in]	f	Bounding rectangle of the keyboard widget.
[in]	rh	Row height in pixels (f->h / k_ra8_kbd_rows).

Returns: Nothing.

Precondition: kb and f are not nullptr.; rh > 0 (non-zero row height, guaranteed by ra8_kbd_layout_init).

Postcondition: All letter-layer keys are appended to kb->keys, up to the k_ra8_kbd_max_keys capacity limit.; kb->count reflects the total number of keys placed for this layer.

Note: Not thread-safe; must be called from the layout-construction context.

Since: 0.1.0

Definition at line 397 of file ra8_keyboard.c.

References internal_place(), internal_row_bottom(), internal_span(), k_kbd_hu_div, k_kbd_inset_hu, k_kbd_mid_keys, k_kbd_r2_lett, k_kbd_row2, k_kbd_row3, k_kbd_top_keys, k_kbd_wide_hu, k_ra8_kbd_key_backspace, k_ra8_kbd_key_shift, k_ra8_kbd_layer_numbers, s_l_r0_hi, s_l_r0_lo, s_l_r1_hi, s_l_r1_lo, s_l_r2_hi, s_l_r2_lo, and ra8_ui_rect_t::y.

Referenced by internal_build_layer().

◆ internal_build_numbers()

void internal_build_numbers	(	ra8_kbd_layout_t *	kb,
		const ra8_ui_rect_t *	f,
		int32_t	rh )

static

Build the numbers layer (digits, common symbols; #+= toggles to symbols).

Populates four rows into kb:

Row 0: 10-key digit row (s_n_r0 "1234567890") at f->y.
Row 1: 10-key symbol row (s_n_r1 "-/:;()$&@\"") at f->y + rh; no shift effect (hi == nullptr so upper == lower for each key).
Row 2: layer-toggle to symbols, s_punct punctuation, BACKSPACE via internal_row_punct() with tog_aux = k_ra8_kbd_layer_symbols.
Row 3: layer-toggle to letters, SPACE, RETURN via internal_row_bottom().

Parameters

[in,out]	kb	Layout being built; all numbers-layer keys are appended.
[in]	f	Bounding rectangle of the keyboard widget.
[in]	rh	Row height in pixels (f->h / k_ra8_kbd_rows).

Returns: Nothing.

Precondition: kb and f are not nullptr.; rh > 0 (non-zero row height, guaranteed by ra8_kbd_layout_init).

Postcondition: All numbers-layer keys are appended to kb->keys, up to the k_ra8_kbd_max_keys capacity limit.; kb->count reflects the total number of keys placed for this layer.

Note: Not thread-safe; must be called from the layout-construction context.

Since: 0.1.0

Definition at line 459 of file ra8_keyboard.c.

References internal_place(), internal_row_bottom(), internal_row_punct(), k_kbd_row2, k_kbd_row3, k_kbd_top_keys, k_ra8_kbd_layer_letters, k_ra8_kbd_layer_symbols, s_n_r0, s_n_r1, and ra8_ui_rect_t::y.

Referenced by internal_build_layer().

◆ internal_build_symbols()

void internal_build_symbols	(	ra8_kbd_layout_t *	kb,
		const ra8_ui_rect_t *	f,
		int32_t	rh )

static

Build the symbols layer (brackets, math operators; 123 toggles to numbers).

Populates four rows into kb:

Row 0: 10-key brackets/math row (s_s_r0 "[]{}#%^*+=") at f->y; no shift effect (hi == nullptr).
Row 1: k_kbd_sym1_n (7) keys from s_s_r1 ("<>\\_ \`|~") centred at half-unit k_kbd_sym1_hu0 (3); no shift effect.
Row 2: layer-toggle to numbers, s_punct punctuation, BACKSPACE via internal_row_punct() with tog_aux = k_ra8_kbd_layer_numbers.
Row 3: layer-toggle to letters, SPACE, RETURN via internal_row_bottom().

Parameters

[in,out]	kb	Layout being built; all symbols-layer keys are appended.
[in]	f	Bounding rectangle of the keyboard widget.
[in]	rh	Row height in pixels (f->h / k_ra8_kbd_rows).

Returns: Nothing.

Precondition: kb and f are not nullptr.; rh > 0 (non-zero row height, guaranteed by ra8_kbd_layout_init).

Postcondition: All symbols-layer keys are appended to kb->keys, up to the k_ra8_kbd_max_keys capacity limit.; kb->count reflects the total number of keys placed for this layer.

Note: Not thread-safe; must be called from the layout-construction context.

Since: 0.1.0

Definition at line 498 of file ra8_keyboard.c.

References internal_place(), internal_row_bottom(), internal_row_punct(), k_kbd_row2, k_kbd_row3, k_kbd_sym1_hu0, k_kbd_sym1_n, k_kbd_top_keys, k_ra8_kbd_layer_letters, k_ra8_kbd_layer_numbers, s_s_r0, s_s_r1, and ra8_ui_rect_t::y.

Referenced by internal_build_layer().

◆ internal_hx()

int32_t internal_hx	(	const ra8_ui_rect_t *	f,
		int32_t	hu )

static

Compute the pixel X coordinate for a given half-unit offset within a frame.

Maps a half-unit index hu to an absolute horizontal pixel position using the formula: f->x + (f->w * hu) / k_kbd_hu_div. The division is integer (truncating), matching the iOS-style proportional key layout where the full frame width is divided into k_kbd_hu_div (20) equal slots.

Parameters

[in]	f	Bounding rectangle of the keyboard widget; x and w are used.
[in]	hu	Half-unit index in the range [0, k_kbd_hu_div].

Returns: int32_t Absolute pixel X coordinate of the half-unit boundary.

Return values

(f->x + (f->w * hu) / k_kbd_hu_div) Computed X coordinate.

Precondition: f is not nullptr.; hu is in [0, k_kbd_hu_div] (values outside this range yield out-of-frame coordinates but do not trap).

Postcondition: The returned value is >= f->x when hu >= 0.; The returned value equals f->x + f->w when hu == k_kbd_hu_div.

Note: Not thread-safe; intended only for use during layout construction.

Since: 0.1.0

Definition at line 150 of file ra8_keyboard.c.

References k_kbd_hu_div, RA8_INTERNAL, ra8_ui_rect_t::w, and ra8_ui_rect_t::x.

Referenced by internal_place(), and internal_span().

◆ internal_place()

void internal_place	(	ra8_kbd_layout_t *	kb,
		const char *	lo,
		const char *	hi,
		int32_t	n,
		int32_t	hu0,
		const ra8_ui_rect_t *	f,
		int32_t	y,
		int32_t	rh )

static

Place n character keys, each k_kbd_key_hu (2) half-units wide, starting from half-unit offset hu0.

Iterates over indices 0..n-1 and calls internal_add() for each character in the lo string. The left edge of key i is at half-unit (hu0 + i*2) and the right edge at half-unit (hu0 + (i+1)*2), with actual pixel positions resolved via internal_hx(). When hi is nullptr the upper-case glyph is set equal to the lower-case glyph (used for layers without a shift effect).

Parameters

[in,out]	kb	Layout being built; keys are appended via internal_add().
[in]	lo	Null-terminated string of lower-case glyphs; must have at least `n` characters.
[in]	hi	Null-terminated string of upper-case glyphs with at least `n` characters, or nullptr if shift has no effect.
[in]	n	Number of character keys to place.
[in]	hu0	Starting half-unit offset within `f`.
[in]	f	Bounding rectangle of the keyboard widget.
[in]	y	Top pixel coordinate of the key row.
[in]	rh	Row height in pixels.

Returns: Nothing.

Precondition: kb and f are not nullptr.; lo points to a character array with at least n elements.

Postcondition: Exactly min(n, k_ra8_kbd_max_keys - kb->count) new char keys have been appended to kb->keys.; kb->count has increased by the number of keys successfully appended.

Note: Not thread-safe; must be called from the layout-construction context.

Since: 0.1.0

Definition at line 189 of file ra8_keyboard.c.

References internal_add(), internal_hx(), k_kbd_key_hu, k_ra8_kbd_key_char, and RA8_INTERNAL.

Referenced by internal_build_letters(), internal_build_numbers(), internal_build_symbols(), and internal_row_punct().

◆ internal_row_bottom()

void internal_row_bottom	(	ra8_kbd_layout_t *	kb,
		const ra8_ui_rect_t *	f,
		int32_t	y,
		int32_t	rh,
		uint8_t	left_aux )

static

Build the bottom row: a layer-toggle key, SPACE, and RETURN.

Lays out three groups from left to right across the full frame width:

A k_ra8_kbd_key_layer special key spanning [0, k_kbd_act_hu) whose aux field is left_aux (the layer index to switch to).
A k_ra8_kbd_key_space key spanning [k_kbd_act_hu, k_kbd_act_hu + k_kbd_space_hu).
A k_ra8_kbd_key_enter key spanning [k_kbd_hu_div - k_kbd_act_hu, k_kbd_hu_div). This row is identical in structure for all three layers; only the target of the left toggle button differs, which is controlled by left_aux.

Parameters

[in,out]	kb	Layout being built; keys are appended via internal_span().
[in]	f	Bounding rectangle of the keyboard widget.
[in]	y	Top pixel coordinate of the row.
[in]	rh	Row height in pixels.
[in]	left_aux	Target layer index stored in the left layer-toggle key's aux field.

Returns: Nothing.

Precondition: kb and f are not nullptr.; left_aux is a valid ra8_kbd_layer_t cast to uint8_t.

Postcondition: Three keys (layer-toggle, space, enter) are appended to kb->keys, subject to the k_ra8_kbd_max_keys capacity guard.; kb->count increases by the number of keys successfully appended (up to 3).

Note: Not thread-safe; must be called from the layout-construction context.

Since: 0.1.0

Definition at line 343 of file ra8_keyboard.c.

References internal_span(), k_kbd_act_hu, k_kbd_hu_div, k_kbd_space_hu, k_ra8_kbd_key_enter, k_ra8_kbd_key_layer, k_ra8_kbd_key_space, and RA8_INTERNAL.

Referenced by internal_build_letters(), internal_build_numbers(), and internal_build_symbols().

◆ internal_row_punct()

void internal_row_punct	(	ra8_kbd_layout_t *	kb,
		const ra8_ui_rect_t *	f,
		int32_t	y,
		int32_t	rh,
		uint8_t	tog_aux )

static

Build row 2 for the numbers or symbols layer: layer-toggle, punctuation, backspace.

Lays out three groups from left to right across the full frame width:

A k_ra8_kbd_key_layer special key spanning [0, k_kbd_act_hu) whose aux field is set to tog_aux (the layer to switch to on press).
k_kbd_punct_n (5) character keys from s_punct starting at half-unit k_kbd_punct_hu0 (centred in the row).
A k_ra8_kbd_key_backspace special key spanning [k_kbd_hu_div - k_kbd_act_hu, k_kbd_hu_div). This row is shared between the numbers and symbols layers; the only difference is which layer the toggle button targets, expressed by tog_aux.

Parameters

[in,out]	kb	Layout being built; keys are appended via internal_span() and internal_place().
[in]	f	Bounding rectangle of the keyboard widget.
[in]	y	Top pixel coordinate of the row.
[in]	rh	Row height in pixels.
[in]	tog_aux	Target layer index stored in the layer-toggle key's aux field (k_ra8_kbd_layer_symbols or k_ra8_kbd_layer_numbers).

Returns: Nothing.

Precondition: kb and f are not nullptr.; tog_aux is a valid ra8_kbd_layer_t cast to uint8_t.

Postcondition: Seven keys (1 layer-toggle + 5 punctuation + 1 backspace) are appended to kb->keys, subject to the k_ra8_kbd_max_keys capacity guard.; kb->count increases by the number of keys successfully appended (up to 7).

Note: Not thread-safe; must be called from the layout-construction context.

Since: 0.1.0

Definition at line 292 of file ra8_keyboard.c.

References internal_place(), internal_span(), k_kbd_act_hu, k_kbd_hu_div, k_kbd_punct_hu0, k_kbd_punct_n, k_ra8_kbd_key_backspace, k_ra8_kbd_key_layer, RA8_INTERNAL, and s_punct.

Referenced by internal_build_numbers(), and internal_build_symbols().

◆ internal_span()

void internal_span	(	ra8_kbd_layout_t *	kb,
		int32_t	a,
		int32_t	b,
		const ra8_ui_rect_t *	f,
		int32_t	y,
		int32_t	rh,
		ra8_kbd_key_kind_t	kind,
		uint8_t	aux )

static

Append one special key that spans half-units [a, b).

Computes the pixel left edge from half-unit a and the pixel width as internal_hx(f, b) - internal_hx(f, a), then delegates to internal_add() with zero glyph characters. Used for shift, backspace, space, enter, and layer- toggle keys which span more than the standard 2-half-unit width.

Parameters

[in,out]	kb	Layout being built; one key is appended via internal_add().
[in]	a	First half-unit of the key span (inclusive).
[in]	b	Last half-unit of the key span (exclusive).
[in]	f	Bounding rectangle of the keyboard widget.
[in]	y	Top pixel coordinate of the key row.
[in]	rh	Row height in pixels.
[in]	kind	Key kind (shift, backspace, space, enter, or layer).
[in]	aux	Auxiliary data; for k_ra8_kbd_key_layer this is the target layer index, otherwise 0.

Returns: Nothing.

Precondition: kb and f are not nullptr.; a < b and both are in [0, k_kbd_hu_div].

Postcondition: kb->count is incremented by one if the layout was not already at k_ra8_kbd_max_keys capacity.; The appended key has ch_lower == 0 and ch_upper == 0.

Note: Not thread-safe; must be called from the layout-construction context.

Since: 0.1.0

Definition at line 244 of file ra8_keyboard.c.

References internal_add(), internal_hx(), and RA8_INTERNAL.

Referenced by internal_build_letters(), internal_row_bottom(), and internal_row_punct().

◆ 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().

Variable Documentation

◆ s_l_r0_hi

const char s_l_r0_hi[] = "QWERTYUIOP"

static

Definition at line 51 of file ra8_keyboard.c.

Referenced by internal_build_letters().

◆ s_l_r0_lo

const char s_l_r0_lo[] = "qwertyuiop"

static

Definition at line 50 of file ra8_keyboard.c.

Referenced by internal_build_letters().

◆ s_l_r1_hi

const char s_l_r1_hi[] = "ASDFGHJKL"

static

Definition at line 53 of file ra8_keyboard.c.

Referenced by internal_build_letters().

◆ s_l_r1_lo

const char s_l_r1_lo[] = "asdfghjkl"

static

Definition at line 52 of file ra8_keyboard.c.

Referenced by internal_build_letters().

◆ s_l_r2_hi

const char s_l_r2_hi[] = "ZXCVBNM"

static

Definition at line 55 of file ra8_keyboard.c.

Referenced by internal_build_letters().

◆ s_l_r2_lo

const char s_l_r2_lo[] = "zxcvbnm"

static

Definition at line 54 of file ra8_keyboard.c.

Referenced by internal_build_letters().

◆ s_n_r0

const char s_n_r0[] = "1234567890"

static

Definition at line 57 of file ra8_keyboard.c.

Referenced by internal_build_numbers().

◆ s_n_r1

const char s_n_r1[] = "-/:;()$&@\""

static

Definition at line 58 of file ra8_keyboard.c.

Referenced by internal_build_numbers().

◆ s_punct

const char s_punct[] = ".,?!'"

static

Definition at line 65 of file ra8_keyboard.c.

Referenced by internal_row_punct().

◆ s_s_r0

const char s_s_r0[] = "[]{}#%^*+="

static

Definition at line 62 of file ra8_keyboard.c.

Referenced by internal_build_symbols().

◆ s_s_r1

const char s_s_r1[] = "<>\\_`|~"

static

Definition at line 63 of file ra8_keyboard.c.

Referenced by internal_build_symbols().

◆ s_tag

const char* s_tag = "KBD"

static

Log tag for this module.

Definition at line 24 of file ra8_keyboard.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ kbd_geom_t

Function Documentation

◆ internal_add()

◆ internal_append()

◆ internal_build_layer()

◆ internal_build_letters()

◆ internal_build_numbers()

◆ internal_build_symbols()

◆ internal_hx()

◆ internal_place()

◆ internal_row_bottom()

◆ internal_row_punct()

◆ internal_span()

◆ ra8_kbd_apply()

◆ ra8_kbd_hit()

◆ ra8_kbd_key_glyph()

◆ ra8_kbd_layout_init()

◆ ra8_kbd_text_init()

Variable Documentation

◆ s_l_r0_hi

◆ s_l_r0_lo

◆ s_l_r1_hi

◆ s_l_r1_lo

◆ s_l_r2_hi

◆ s_l_r2_lo

◆ s_n_r0

◆ s_n_r1

◆ s_punct

◆ s_s_r0

◆ s_s_r1

◆ s_tag