touchTextEntry.h File Reference

Detailed Description

Design Philosophy

The text entry utility provides a minimal interface for editing a single line of text of unlimited length. The entered text is kept in an internal buffer that automatically grows if needed. The string is returned via a callback, and should be copied to an external buffer with strncpy() or strdup() for later access.

Characters can be selected using either touchpad spins or up and down on the D-pad. Once selected, a character can be confirmed and entered with the A button. The B button erases the previous charater, and the left and right arrows move the cursor within the text. The right arrow will also create one space if used at the end of the text. The pause button confirms the text entry and calls the callback.

Usage

The text entry was made as generic as possible to enable using it in various modes. The only thing it draws to the screen is the text and, optionally, a box around the text area's bounds. When the text entry is being used, the mode should pass all button input to the text entry until the callback is called. The text entry provides support for allowing certain sets of characters individually, or for combined multiple classes by performing a logical OR of values in textEntryCharMask_t. The classes that can be used are:

• Uppercase Letters
• Lowercase Letters
• Numbers
• Whitespace
• Symbols, which includes everything not covered by the other categories

Example

typedef struct {
    textEntry_t* textEntry;
    font_t font;
    char* textData;
} modeData_t;
 
static modeData_t* modeData;
 
void textEntryCb(const char* text, void* data)
{
    ESP_LOGI("Text", "Text entered was %s!", text);
    modeData_t* mode = (modeData_t*) data;
 
    if (mode->textData != NULL)
    {
        free(mode->textData);
    }
    mode->textData = strdup(text);
}
 
void setup(void)
{
    modeData = calloc(1, sizeof(modeData_t));
    // Setup function
    uint16_t entryW = 160;
    uint16_t entryH = 16;
    uint16_t entryX = (TFT_WIDTH - entryW) / 2;
    uint16_t entryY = (TFT_HEIGHT - entryH) / 2;
 
    loadFont("ibm_vga8.font", &modeData->font);
 
    modeData->textEntry = initTextEntry(entryX, entryY, entryW, entryH, &font, ENTRY_ALPHANUM, textEntryCb);
 
    // If needed, a data pointer can be set that will be passed back to the callback
    textEntrySetData(textEntry, &modeData);
}
 
void cleanUp(void)
{
    freeTextEntry(textEntry);
    freeFont(&font);
 
    if (modeData->textData != NULL)
    {
        free(modeData->textData);
    }
}
 
// Main loop
void mainLoop(int64_t elapsedUs)
{
    // Handle buttons for text entry
    buttonEvt_t evt;
    while (checkButtonQueueWrapper(&evt))
    {
        textEntryButton(textEntry, &evt);
    }
 
    // Handle touchpad, button repeating, and other logic
    textEntryMainLoop(textEntry, elapsedUs);
 
    // Draw the text entry with a white background, black text, and a box around the text itself
    drawTextEntry(textEntry, c000, c555, true);
}

Go to the source code of this file.

Data Structures
struct	textEntry_t
	Struct to store all state for a text entry. More...

Macros
#define	ENTRY_ALPHA   (ENTRY_UPPERCASE | ENTRY_LOWERCASE)
	Mask for allowing uppercase and lowercase alphabet.
#define	ENTRY_ALPHANUM   (ENTRY_ALPHA | ENTRY_NUMBERS)
	Mask for allowing uppercase and lowercase alphabet, and numbers.
#define	ENTRY_WORD   (ENTRY_UPPERCASE | ENTRY_LOWERCASE | ENTRY_NUMBERS | ENTRY_SYMBOLS)
	Mask for allowing any characters except whitespace.
#define	ENTRY_ALL   (ENTRY_UPPERCASE | ENTRY_LOWERCASE | ENTRY_NUMBERS | ENTRY_SYMBOLS | ENTRY_WHITESPACE)
	Mask for allowing all printable characters.

Typedefs
typedef void(*	textEntryCb) (const char *text, void *data)
	A callback which is called once text entry is complete.

Enumerations
enum	textEntryCharMask_t {   ENTRY_UPPERCASE = 0x01 , ENTRY_LOWERCASE = 0x02 , ENTRY_NUMBERS = 0x04 , ENTRY_SYMBOLS = 0x08 ,   ENTRY_WHITESPACE = 0x10 }
	Bitmask enum for specifying which classes of characters may be entered. More...

Functions
textEntry_t *	initTextEntry (uint16_t x, uint16_t y, uint16_t w, uint16_t length, const font_t *font, textEntryCharMask_t mask, textEntryCb cbFn)
	Allocate and return a new text entry. The text entry must be freed with freeTextEntry()
void	freeTextEntry (textEntry_t *textEntry)
	Frees any memory associated with a text entry.
void	textEntrySetData (textEntry_t *textEntry, void *data)
	Sets the data pointer to be passed along to the callback function.
void	textEntrySetText (textEntry_t *textEntry, const char *text)
	Copy the given text into the text entry, replacing any text that was there and moving the cursor to the end of the new text.
void	textEntryMainLoop (textEntry_t *textEntry, int64_t elapsedUs)
	Update timer logic and handle touchpad for a text entry.
void	textEntryButton (textEntry_t *textEntry, const buttonEvt_t *evt)
	Handle a button event for a text entry to modify the text or confirm entry.
void	drawTextEntry (textEntry_t *textEntry, paletteColor_t fg, paletteColor_t bg, bool drawBox)
	Draw a text entry box.

---

Data Structure Documentation

textEntry_t

struct textEntry_t

Data Fields
char *	value	The buffer holding the actual entered text value. Can be accessed as a string.
uint16_t	size	The total size of the dynamic text buffer.
uint16_t	cursor	The position of the cursor.
bool	overtype	Whether the cursor will operate in overtype mode instead of insert mode.
bool	pendingChar	Whether a to-be-entered character should be shown.
char	cur	The current character pending addition at the cursor, when pendingChar is true.
bool	blinkState	Boolean value to keep track of whether the blinking cursor is shown.
int64_t	blinkTimer	The number of nanoseconds remaining before the blink state changes.
uint16_t	minLength	The minimum length of text that will be accepted.
uint16_t	maxLength	The maximum length of text allowed, or 0 for no limit.
textEntryCharMask_t	mask	The mask of character types that are allowed.
touchSpinState_t	spinState	Struct to track the state of the touchpad for spins.
char	spinCharStart	The selected character at the start of the touchpad spin.
buttonBit_t	heldButton	The button that is currently being held, or 0 if none.
int64_t	repeatTimer	The number of nanoseconds remaining before the held button repeats.
uint16_t	offset	The first character to be drawn on-screen, if the whole value doesn't fit.
uint16_t	x	The X position of the text entry box.
uint16_t	y	The Y position of the text entry box.
uint16_t	w	The width of the text entry box.
const font_t *	font	The font to use for text entry.
void *	data	A pointer to be passed back into the callback.
textEntryCb	cbFn	The function to call when the text entry is completed.

Macro Definition Documentation

ENTRY_ALPHA

#define ENTRY_ALPHA   (ENTRY_UPPERCASE | ENTRY_LOWERCASE)

Mask for allowing uppercase and lowercase alphabet.

ENTRY_ALPHANUM

#define ENTRY_ALPHANUM   (ENTRY_ALPHA | ENTRY_NUMBERS)

Mask for allowing uppercase and lowercase alphabet, and numbers.

ENTRY_WORD

#define ENTRY_WORD   (ENTRY_UPPERCASE | ENTRY_LOWERCASE | ENTRY_NUMBERS | ENTRY_SYMBOLS)

Mask for allowing any characters except whitespace.

ENTRY_ALL

#define ENTRY_ALL   (ENTRY_UPPERCASE | ENTRY_LOWERCASE | ENTRY_NUMBERS | ENTRY_SYMBOLS | ENTRY_WHITESPACE)

Mask for allowing all printable characters.

Typedef Documentation

textEntryCb

typedef void(* textEntryCb) (const char *text, void *data)

A callback which is called once text entry is complete.

Parameters

text	The final text value. This value should be copied if it will be saved.
data	The void pointer passed to textEntrySetData(), or NULL if no data was set

Enumeration Type Documentation

textEntryCharMask_t

enum textEntryCharMask_t

Bitmask enum for specifying which classes of characters may be entered.

Any of these values may be combined with a bitwise OR to allow multiple classes.

Enumerator
ENTRY_UPPERCASE	Mask for allowing uppercase alphabet characters.
ENTRY_LOWERCASE	Mask for allowing lowercase alphabet characters.
ENTRY_NUMBERS	Mask for allowing numeric characters.
ENTRY_SYMBOLS	Mask for allowing symbol characters (printable, non-alphanumeric, and non-whitespace)
ENTRY_WHITESPACE	Mask for allowing whitespace characters (space)

Function Documentation

initTextEntry()

textEntry_t * initTextEntry	(	uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	length,
		const font_t *	font,
		textEntryCharMask_t	mask,
		textEntryCb	cbFn )

Allocate and return a new text entry. The text entry must be freed with freeTextEntry()

Parameters

x	The X coordinate of the left edge of the text box
y	The Y coordinate of the top of the text box
w	The width of the text box, in pixels
length	The maximum text length, or 0 for no limit
font	The font to use when drawing the text entry
mask	The mask of allowable character types, or 0 for all characters
cbFn	The function to call once text entry is complete

Returns

textEntry_t*

freeTextEntry()

void freeTextEntry

(

textEntry_t *

textEntry

)

Frees any memory associated with a text entry.

Parameters

textEntry

The text entry to be deallocated

textEntrySetData()

void textEntrySetData	(	textEntry_t *	textEntry,
		void *	data )

Sets the data pointer to be passed along to the callback function.

Parameters

textEntry	The text entry to update the data for
data	The void pointer to be passed when the callback is called

textEntrySetText()

void textEntrySetText	(	textEntry_t *	textEntry,
		const char *	text )

Copy the given text into the text entry, replacing any text that was there and moving the cursor to the end of the new text.

Parameters

textEntry	The text entry to update the text for
text	The text to set as the text entry's value

textEntryMainLoop()

void textEntryMainLoop	(	textEntry_t *	textEntry,
		int64_t	elapsedUs )

Update timer logic and handle touchpad for a text entry.

Parameters

textEntry	The text entry to update
elapsedUs	The number of nanoseconds elapsed since the last call

textEntryButton()

void textEntryButton	(	textEntry_t *	textEntry,
		const buttonEvt_t *	evt )

Handle a button event for a text entry to modify the text or confirm entry.

Parameters

textEntry	The text entry to handle the button event
evt	A pointer to the button event to be handled

drawTextEntry()

void drawTextEntry	(	textEntry_t *	textEntry,
		paletteColor_t	fg,
		paletteColor_t	bg,
		bool	drawBox )

Draw a text entry box.

Parameters

textEntry	The text entry to draw
fg	The color to use for drawing text and "more" dots
bg	The color to use for drawing inverted text and, if drawBox is enabled, the background
drawBox	Whether to fill the text entry box area's background