textEntry.h File Reference

Detailed Description

Design Philosophy

TextEntry serves as a method to create strings for a multitude of cases. It should be easy to see, easy to customize and as intuitive to use as possible. Several customization options are available.

Usage

Initialize text entry with textEntryInit(), where the settings, string pointer and the desired font are provided. By default, a blank, black background is used with white text and red as the emphasis color. textEntryInit() can be called once during initialization or just before the text entry is required, but cannot be inside the loop or it will not function.

Settings:

• textEntrySettings_t.textPrompt: The text prompt at the top of the screen
• textEntrySettings_t.maxLen: The maximum length that the string may build to
• textEntrySettings_t.startKMod: There are several capitalization modes. This sets the initial mode. The options are TE_NO_SHIFT, TE_SHIFT, TE_CAPS_LOCK, and TE_PROPER_NOUN
• textEntrySettings_t.useMultiLine: Uses a larger text box for longer strings
• textEntrySettings_t.useNewCapsStyle: Use the second caps lock style
• textEntrySettings_t.useOKEnterStyle: Use 'OK' instead of the return symbol
• textEntrySettings_t.blink: If the cursor should blink
• textEntrySettings_t.textColor: Color of most of the text in the UI
• textEntrySettings_t.emphasisColor: Color of certain UI elements to help users
• textEntrySettings_t.bgColor: Color that the background is drawn, set to cTransparent to not draw anything
• textEntrySettings_t.shadowboxColor: Color of shadowboxes drawn to allow text to stand out. Set to cTransparent to not draw

After all of the initialization is done, use textEntryDraw() to draw the current text entry box and textEntryInput() to send inputs to the tent entry. The text entry is re-drawn from scratch every cycle. textEntryInput() returns false until enter/okay is selected.

The controls are as follows:

• Directions: navigate the keyboard
• A: Select currently highlighted symbol
• B: Backspace
• Start: Cycle through text entry modes.

Example

 // Settings
 static const textEntrySettings_t teSettings = {
    .textPrompt      = textSamplePrompt,
    .maxLen          = MAX_TEXT_LEN,
    .startKMod       = TE_PROPER_NOUN,
    .useMultiLine    = true,
    .useNewCapsStyle = true,
    .useOKEnterStyle = true,
    .blink           = true,
    .textColor       = c454,
    .emphasisColor   = c511,
    .bgColor         = c000,
    .shadowboxColor  = c222,
};
 
// Init
textEntryInit(&teSettings, promptText, font);
 
main loop(int64_t elapsedUs)
{
    buttonEvt_t evt = {0};
    while (checkButtonQueueWrapper(&evt))
    {
        done = textEntryInput(evt);
    }
    if (done)
    {
        // Text entry is done, createdString contains the text and can be used elsewhere
    }
    // Draw backgrounds if no solid color is picked
    textEntryDraw(elapsedUs);
}
 
// Deinit
textEntryDeinit();

Go to the source code of this file.

Data Structures
struct	textEntrySettings_t

Enumerations
enum	keyModifier_t {   TE_NO_SHIFT , TE_SHIFT , TE_CAPS_LOCK , TE_PROPER_NOUN ,   TE_SPECIAL_DONE }

Functions
void	textEntryInit (const textEntrySettings_t *settings, char *entryText, font_t *font)
void	textEntryDeinit (void)
	Deletes the memory used by the text entry system.
bool	textEntryInput (buttonEvt_t evt)
	Handle button input for text entry.
bool	textEntryDraw (int64_t elapsedUs)
	Draws the text entry screen.
void	textEntrySoftReset (void)
	Resets the textEntry object.

---

Data Structure Documentation

textEntrySettings_t

struct textEntrySettings_t

Data Fields
const char *	textPrompt	Prompt for the player. Set to NULL to not draw.
int	maxLen	The max length of the string.
keyModifier_t	startKMod	Sets default capitalization mode.
bool	useMultiLine	Use multiple lines.
bool	useOKEnterStyle	Use the "OK" instead of the arrow.
bool	useNewCapsStyle	Use new style instead of old style.
bool	blink	If the cursor should blink.
paletteColor_t	textColor	Color of the text to use.
paletteColor_t	emphasisColor	Color of the emphasis, used to highlight certain parts of the UI.
paletteColor_t	bgColor	Color of the background. Set to cTransparent to not draw a background.
paletteColor_t	shadowboxColor	Color of the shadowboxes. Set to cTransparent to not draw shadowboxes.

Enumeration Type Documentation

keyModifier_t

enum keyModifier_t

Enumerator
TE_NO_SHIFT	Start on lowercase, no auto-capitalization.
TE_SHIFT	Capitalize the first character only.
TE_CAPS_LOCK	Default to all caps.
TE_PROPER_NOUN	automatically the first letter after a space
TE_SPECIAL_DONE	DO NOT USE! Indicates to system that it is done.

Function Documentation

textEntryInit()

void textEntryInit	(	const textEntrySettings_t *	settings,
		char *	entryText,
		font_t *	font )

textEntryDeinit()

void textEntryDeinit

(

void

)

Deletes the memory used by the text entry system.

textEntryInput()

bool textEntryInput

(

buttonEvt_t

evt

)

Handle button input for text entry.

Parameters

evt	button event to run

Returns

false if text entry is still ongoing

true if the enter key was pressed and text entry is done

textEntryDraw()

bool textEntryDraw

(

int64_t

elapsedUs

)

Draws the text entry screen.

Parameters

elapsedUs

TIme for cursor blink

Returns

true If text entry is still being executed

false If text entry is done

textEntrySoftReset()

void textEntrySoftReset

(

void

)

Resets the textEntry object.