ui_textkey.h File Reference

An on-screen keyboard for a short name: capitals, digits, space and the marks a name or a file needs, "-", "_" and ".". More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "gfx.h"
#include "touch_types.h"

Go to the source code of this file.

Data Structures
struct	ui_textkey_t
	A keyboard: what it was opened for, what is typed, and the press it holds. More...

Macros
#define	UI_TEXTKEY_MAX   23
	The longest name or search it takes, in characters.
#define	UI_TEXTKEY_PASS_MAX   63
	The longest Wi-Fi password, in characters.
#define	UI_TEXTKEY_PASS_MIN   8
	The shortest Wi-Fi password, in characters.
#define	UI_TEXTKEY_SSID_MAX   32
	The longest Wi-Fi network name, in bytes.
#define	UI_TEXTKEY_CHARS   40
	The keys: forty characters in four rows of ten, then SPACE, CLR, CANCEL and OK along the bottom.
#define	UI_TK_SHOW   UI_TK_KEYS
	SHOW, the password keyboard's sixth bottom key; zero size otherwise.
#define	UI_TK_SHIFT   30
	The Wi-Fi keyboard's capitals key, left of Z.
#define	UI_TK_LAYER   38
	The Wi-Fi keyboard's marks key, left of DEL.
#define	UI_TK_DEL   (UI_TEXTKEY_CHARS - 1)
	The DEL key, last of the character rows.
#define	UI_TK_MARK   (UI_TEXTKEY_CHARS - 3)
	The key that types "_", or "*" in a search.
#define	UI_TK_DOT   (UI_TEXTKEY_CHARS - 2)
	The key that types ".", or "/" for a folder.

Enumerations
enum	{   UI_TK_SPACE = UI_TEXTKEY_CHARS , UI_TK_CLR , UI_TK_CANCEL , UI_TK_OK ,   UI_TK_KEYS }
	The bottom row's keys, numbered after the characters. More...
enum	ui_textkey_result_t { UI_TEXTKEY_NONE = 0 , UI_TEXTKEY_OK , UI_TEXTKEY_CANCELLED }
	What an event on the keyboard came to. More...
enum	ui_textkey_layer_t { UI_TK_LOWER = 0 , UI_TK_UPPER , UI_TK_MARKS }
	The Wi-Fi keyboard's layers. More...

Functions
void	ui_textkey_open (ui_textkey_t *k, gfx_rect_t area, const char *title, const char *text, int max_len)
	Open over area on text.
void	ui_textkey_open_search (ui_textkey_t *k, gfx_rect_t area, const char *title, const char *text, int max_len)
	Open for a search pattern; see the top of this file.
void	ui_textkey_open_folder (ui_textkey_t *k, gfx_rect_t area, const char *title, const char *text)
	Open for a folder of the card; see the top of this file. Up to UI_TEXTKEY_MAX characters.
void	ui_textkey_open_wifi (ui_textkey_t *k, gfx_rect_t area, const char *title, const char *text, bool secret)
	Open for a Wi-Fi password or network name; see the top of this file. Lower case first.
void	ui_textkey_open_file (ui_textkey_t *k, gfx_rect_t area, const char *title, const char *text)
	Open for a file name; see the top of this file. Lower case first.
void	ui_textkey_close (ui_textkey_t *k)
	Close, dropping a press under way.
void	ui_textkey_cancel_press (ui_textkey_t *k)
	A press under way is dropped: the touch stream lost an event. What was typed stays typed.
ui_textkey_result_t	ui_textkey_event (ui_textkey_t *k, const touch_event_t *evt, char *out, size_t n)
	One touch event.
gfx_rect_t	ui_textkey_key_rect (const ui_textkey_t *k, int key)
	Where a key is drawn and hit: the grid ends 8px inside the area, or at UI_KEYS_FOOT (4px above the alert band, body coordinates) where the area reaches further.
const char *	ui_textkey_label (int key)
	A key's label as a name keyboard shows it.
const char *	ui_textkey_key_label (const ui_textkey_t *k, int key)
	A key's label as k shows it.
const gfx_font_t *	ui_textkey_char_font (const ui_textkey_t *k)
	The face of the character keys: the largest of 20 x 36, 16 x 28, 12 x 24 and 10 x 20 whose cell fits a character key with 4px on each side, else 8 x 16. Over the WI-FI screen's 1008 x 484px a key is 93 x 71px and takes 20 x 36.
const gfx_font_t *	ui_textkey_word_font (const ui_textkey_t *k)
	The face of the word keys (the bottom row, DEL, and the Wi-Fi layer keys) in the language shown: the largest of 20 x 36, 16 x 28, 12 x 24 and 10 x 20, never larger than ui_textkey_char_font(), in which every one of them fits its key with 4px each side, in every state it can show (SHOW and HIDE, ABC, abc and #+=), so the words of one keyboard share one face and a press does not change it; else 8 x 16.
void	ui_textkey_render (const ui_textkey_t *k, gfx_canvas_t *c)
	The whole keyboard over its area: the title and the count in 10 x 20 (8 x 16 where they do not fit side by side), the text in 20 x 36 (16 x 28 in a field narrower than UI_TEXTKEY_MAX characters and the caret), the character keys in ui_textkey_char_font() and the word keys in ui_textkey_word_font(). Nothing while it is closed.

Detailed Description

An on-screen keyboard for a short name: capitals, digits, space and the marks a name or a file needs, "-", "_" and ".".

Unlike the numeric keypad it edits the text it was opened with: DEL takes the last character, CLR the lot. OK on an empty name is refused, because a name is what a report is filed under. Spaces at either end are dropped on OK.

Opened for a search (ui_textkey_open_search()) it types a search pattern instead: the "_" key types "*", the wildcard; OK takes the text as typed, empty included, since an empty search is no search; and the bottom row gives SPACE and CANCEL three columns each, CLR and OK two, so CANCEL's longer translations fit an area narrower than the SERVO screen's. The caller reads the text as it is typed from text.

Opened for a folder of the card (ui_textkey_open_folder()) it types a path such as BENCH/LOGS: the "." key shows and types "/", and OK takes the path only when card_folder_check() (card_tree.h) does, in upper case. A refused OK keeps the keyboard open, and its line says why: an empty folder, over 8 characters, over 2 folders deep, a character outside A-Z, 0-9, "_" and "-", a reserved name, a folder of the bench's own files. The keys and the rest of the layout are the name's.

Opened for Wi-Fi (ui_textkey_open_wifi()) it types a network name of up to 32 bytes or a password of 8 to 63 characters: any printable ASCII (American Standard Code for Information Interchange) character, lower case included. Three layers share the grid: lower case, capitals, and the 32 marks. The key left of Z switches lower case and capitals ("ABC", "abc"); the key left of DEL switches to the marks and back ("#+=", "abc"). The digits stay on the top row of both letter layers. A password shows as "*" until SHOW, which a sixth bottom key carries (UI_TK_SHOW); SHOW again hides it. OK takes the text as typed, spaces included, and refuses a password under 8 characters or an empty name. A text longer than the field shows its end.

Opened for a file name (ui_textkey_open_file()) it is the Wi-Fi keyboard with its three layers, for a name of up to FM_NAME_MAX (59) bytes: OK takes the name only when fm_name_check() (fm_name.h) does, as typed. A refused OK keeps the keyboard open, and its line says why: an empty name, over 59 bytes, one of " * / : < > ? \ | , a space or a full stop at an end, a device name. DEL takes the last character, also one of two bytes.

The screen routes events to it while it is open and draws it last, as it does the keypad.

SPDX-License-Identifier: MIT

Enumeration Type Documentation

anonymous enum

anonymous enum

The bottom row's keys, numbered after the characters.

Enumerator
UI_TK_SPACE	SPACE
UI_TK_CLR	CLR: the whole text
UI_TK_CANCEL	CANCEL: closes, nothing taken
UI_TK_OK	OK: takes the text
UI_TK_KEYS	the count of the keys above

ui_textkey_layer_t

enum ui_textkey_layer_t

The Wi-Fi keyboard's layers.

Enumerator
UI_TK_LOWER	lower case and the digits
UI_TK_UPPER	capitals and the digits
UI_TK_MARKS	the 32 marks

ui_textkey_result_t

enum ui_textkey_result_t

What an event on the keyboard came to.

Enumerator
UI_TEXTKEY_NONE	still open, or the event was not its
UI_TEXTKEY_OK	closed with a name
UI_TEXTKEY_CANCELLED	closed, the name as it was

Function Documentation

ui_textkey_cancel_press()

void ui_textkey_cancel_press

(

ui_textkey_t *

k

)

A press under way is dropped: the touch stream lost an event. What was typed stays typed.

Parameters

k	The keyboard; NULL does nothing.

ui_textkey_char_font()

const gfx_font_t * ui_textkey_char_font

(

const ui_textkey_t *

k

)

The face of the character keys: the largest of 20 x 36, 16 x 28, 12 x 24 and 10 x 20 whose cell fits a character key with 4px on each side, else 8 x 16. Over the WI-FI screen's 1008 x 484px a key is 93 x 71px and takes 20 x 36.

Parameters

k	The keyboard, opened.

Returns

The face; 8 x 16 for NULL.

ui_textkey_close()

void ui_textkey_close

(

ui_textkey_t *

k

)

Close, dropping a press under way.

Parameters

k	The keyboard; NULL does nothing.

ui_textkey_event()

ui_textkey_result_t ui_textkey_event	(	ui_textkey_t *	k,
		const touch_event_t *	evt,
		char *	out,
		size_t	n )

One touch event.

A key acts on the release of the contact that pressed it, over the same key; a second contact is ignored while one is down.

Parameters

k	The keyboard.
evt	The event, in the keyboard's coordinates.
out	Where OK writes the name, ends trimmed; a search's text as typed; a folder in upper case, as card_folder_check() writes it.
n	The bytes at out: CARD_DIR_MAX or more for a folder.

Returns

UI_TEXTKEY_OK or UI_TEXTKEY_CANCELLED when it closed, UI_TEXTKEY_NONE otherwise and for a NULL or closed keyboard.

ui_textkey_key_label()

const char * ui_textkey_key_label	(	const ui_textkey_t *	k,
		int	key )

A key's label as k shows it.

Parameters

k	The keyboard.
key	The key.

Returns

"*" for UI_TK_MARK in a search, "/" for UI_TK_DOT for a folder, the layer's character on a Wi-Fi keyboard, "" for a blank key, else ui_textkey_label().

ui_textkey_key_rect()

gfx_rect_t ui_textkey_key_rect	(	const ui_textkey_t *	k,
		int	key )

Where a key is drawn and hit: the grid ends 8px inside the area, or at UI_KEYS_FOOT (4px above the alert band, body coordinates) where the area reaches further.

Parameters

k	The keyboard.
key	The key: 0 to UI_TK_OK, or UI_TK_SHOW on a password.

Returns

Its rectangle; zero size for one out of range.

ui_textkey_label()

const char * ui_textkey_label

(

int

key

)

A key's label as a name keyboard shows it.

Parameters

key

The key.

Returns

The label, or "" for one out of range.

ui_textkey_open()

void ui_textkey_open	(	ui_textkey_t *	k,
		gfx_rect_t	area,
		const char *	title,
		const char *	text,
		int	max_len )

Open over area on text.

Parameters

k	The keyboard; NULL does nothing.
area	Where it draws and takes presses.
title	What is typed, top left.
text	The text it starts with, cut to max_len.
max_len	The most characters it takes; 0, less, or more than UI_TEXTKEY_MAX is UI_TEXTKEY_MAX.

ui_textkey_open_file()

void ui_textkey_open_file	(	ui_textkey_t *	k,
		gfx_rect_t	area,
		const char *	title,
		const char *	text )

Open for a file name; see the top of this file. Lower case first.

Parameters

k	The keyboard; NULL does nothing.
area	Where it draws.
title	What is typed.
text	The name it starts with, cut to FM_NAME_MAX bytes between two characters.

ui_textkey_open_folder()

void ui_textkey_open_folder	(	ui_textkey_t *	k,
		gfx_rect_t	area,
		const char *	title,
		const char *	text )

Open for a folder of the card; see the top of this file. Up to UI_TEXTKEY_MAX characters.

Parameters

k	The keyboard; NULL does nothing.
area	Where it draws.
title	The setting's name.
text	The folder in force.

ui_textkey_open_search()

void ui_textkey_open_search	(	ui_textkey_t *	k,
		gfx_rect_t	area,
		const char *	title,
		const char *	text,
		int	max_len )

Open for a search pattern; see the top of this file.

Parameters

k	The keyboard; NULL does nothing.
area	Where it draws.
title	What is searched for.
text	The pattern it starts with.
max_len	The most characters, as ui_textkey_open() takes it.

ui_textkey_open_wifi()

void ui_textkey_open_wifi	(	ui_textkey_t *	k,
		gfx_rect_t	area,
		const char *	title,
		const char *	text,
		bool	secret )

Open for a Wi-Fi password or network name; see the top of this file. Lower case first.

Parameters

k	The keyboard; NULL does nothing.
area	Where it draws.
title	What is typed.
text	The text it starts with.
secret	A password: masked, 8 to 63 characters; else a name of 1 to 32 bytes.

ui_textkey_render()

void ui_textkey_render	(	const ui_textkey_t *	k,
		gfx_canvas_t *	c )

The whole keyboard over its area: the title and the count in 10 x 20 (8 x 16 where they do not fit side by side), the text in 20 x 36 (16 x 28 in a field narrower than UI_TEXTKEY_MAX characters and the caret), the character keys in ui_textkey_char_font() and the word keys in ui_textkey_word_font(). Nothing while it is closed.

Parameters

k	The keyboard.
c	Canvas.

ui_textkey_word_font()

const gfx_font_t * ui_textkey_word_font

(

const ui_textkey_t *

k

)

The face of the word keys (the bottom row, DEL, and the Wi-Fi layer keys) in the language shown: the largest of 20 x 36, 16 x 28, 12 x 24 and 10 x 20, never larger than ui_textkey_char_font(), in which every one of them fits its key with 4px each side, in every state it can show (SHOW and HIDE, ABC, abc and #+=), so the words of one keyboard share one face and a press does not change it; else 8 x 16.

Parameters

k	The keyboard, opened.

Returns

The face; 8 x 16 for NULL.