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

Text entry in initialize with textEntryInit(), where the font used, max string length, and string pointer are provided. By default, a blank, black background is used with white text and no emphasis color.

Once initalized, additional commands can be run to customize the text entry screen:

• textEntrySetFont(font_t* newFont): A new font to use for the keyboard
• textEntrySetBgWsg(wsg_t *wsg): Sets a provided image to the background and sets teh background mode to use the WSG.
• textEntrySetBGColor(uint8_t color): Sets the background to a solid color
• textEntrySetBGTransparent(): Sets the background to be transparent
• textEntrySetTextColor(uint8_t color, bool emphasis): Sets the text color, and optionally sets the emphasis color.
• textEntrySetEmphasisColor(uint8_t color): Sets the emphasis color.
• textEntrySetShadowboxColor(bool active, uint8_t color): Sets the color of the shadowboxes used to contrast the background
• textEntrySetNewEnterStyle(bool newStyle): Sets the style to old (false) or new (true)
• textEntrySetNewCapsStyle(bool newStyle): Sets the style to old (false) or new (true)
• textEntrySetPrompt(char *prompt): Sets a string to be displayed over the text box as a prompt to the user
• textEntrySetCapMode(): Set the starting mode to Capslock
• textEntrySetNoShiftMode(): Set the current mode to lowercase text
• textEntrySetShiftMode(): Set the current mode to shift
• textEntrySetNounMode(): Set current mode to porper noun, which capitalizes the first letter after a space.

The text entry is re-drawn from scratch every cycle. The above commands can be run between cycles if desired, though it is strongly discouraged to keep the text entry easy for the end user to navigate and utilize.

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.

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. textEntryInput() returns true until enter/okay is selected.

The controls are as follows: Directions: navigate the keyboard A button: Select currently highlighted symbol B button: Backspace Start button: Move cursor to the enter key

Example

// Variables required
font fnt;
font fnt2;
int strLen = 32;
char createdString[strlen];
wsg bg_test;
const char promptStr[] "Enter your name:";
 
// Text Entry initialization
textEntryInit(&fnt, strLen, kbTest->typedText);
 
// Examples: Each of the following would overwrite the others
// Blue background, gray text, red emphasis text, and dark gray shadowboxes
textEntrySetBGColor(c003);
textEntrySetTextColor(c444);
textEntrySetEmphasisColor(c500);
textEntrySetShadowboxColor(c111);
 
// WSG background, pink shadowboxes, a new font and a prompt string
textEntrySetBgWsg(&bg_test);
textEntrySetShadowboxColor(true, c433);
textEntrySetFont(&fnt2);
textEntrySetPrompt(promptStr);
 
// Transparent BG with caps lock and enter variations, and with the starting mode set to "Proper noun"
textEntrySetBGTransparent();
textEntrySetNewCapsStyle(true);
textEntrySetNewEnterStyle(true);
textEntrySetNounMode();
 
main loop(int64_t elapsedUs)
{
    buttonEvt_t evt = {0};
    while (checkButtonQueueWrapper(&evt))
    {
        done = !textEntryInput(evt.down, evt.button);
    }
    if (done)
    {
        // Text entry is done, createdString contains the text and can be used elsewhere
    }
    // Draw backgrounds for transparent mode here.
    textEntryDraw(elapsedUs);
}

Go to the source code of this file.

Macros
#define	KB_LINES   5
#define	ENTER_X   12
#define	ENTER_Y   2
#define	CORNER_MARGIN   20
#define	SHADOWBOX_MARGIN   4
#define	RETURN_WIDTH   16
#define	KEY_SPACING   5
#define	MAX_WIDTH_CHAR   32
#define	BLINK_RATE   500000

Enumerations
enum	keyModifier_t {   NO_SHIFT , SHIFT , CAPS_LOCK , PROPER_NOUN ,   SPECIAL_DONE }
enum	controlChar_t {   KEY_SHIFT = 0x01 , KEY_CAPS_LOCK = 0x02 , KEY_BACKSPACE = 0x03 , KEY_SPACE = 0x20 ,   KEY_EOL = 0x05 , KEY_TAB = 0x09 , KEY_ENTER = 0x0A }
enum	bgMode_t { WSG_BG , COLOR_BG , CLEAR_BG }

Functions
void	textEntryInit (font_t *useFont, int max_len, char *buffer)
	Initialize the text entry with prettier graphics.
bool	textEntryDraw (int64_t elapsedUs)
	Draw the text entry UI.
bool	textEntryInput (uint8_t down, uint8_t button)
	Handle button input for text entry.
void	textEntrySetFont (font_t *newFont)
	A new font to load into the text entry screen.
void	textEntrySetBgWsg (wsg_t *BG)
	Sets a background image and sets the BG Mode to use the WSG.
void	textEntrySetBGColor (uint8_t color)
	Sets the background to use a solid color.
void	textEntrySetBGTransparent (void)
	Sets the background to be transparent.
void	textEntrySetTextColor (uint8_t color, bool emphasis)
	Set the main text color for the keyboard and entry text.
void	textEntrySetEmphasisColor (uint8_t color)
	Set the emphasis color for the text.
void	textEntrySetShadowboxColor (bool active, uint8_t color)
	Sets the color of the shadowbox.
void	textEntrySetNewEnterStyle (bool newStyle)
	Sets the style of the Enter key.
void	textEntrySetNewCapsStyle (bool newStyle)
	Sets the style of the caps lock key.
void	textEntrySetMultiline (bool multiline)
	Sets the text entry mode from single line to multi-line.
void	textEntrySoftReset (void)
	Allow the text box to continue without a full reset.
void	textEntrySetPrompt (char *prompt)
	Sets the prompt text to be displayed. Use an empty string ("") to disable.
void	textEntrySetCapMode (void)
	Sets the starting mode to capslock.
void	textEntrySetNoShiftMode (void)
	Sets the starting mode to lowercase text.
void	textEntrySetShiftMode (void)
	Sets the starting mode to Shift, does one capital letter.
void	textEntrySetNounMode (void)
	Sets the starting mode to Porper Nouns (Auto capitalizes first letter after a space)

Macro Definition Documentation

KB_LINES

#define KB_LINES   5

ENTER_X

#define ENTER_X   12

ENTER_Y

#define ENTER_Y   2

CORNER_MARGIN

#define CORNER_MARGIN   20

SHADOWBOX_MARGIN

#define SHADOWBOX_MARGIN   4

RETURN_WIDTH

#define RETURN_WIDTH   16

KEY_SPACING

#define KEY_SPACING   5

MAX_WIDTH_CHAR

#define MAX_WIDTH_CHAR   32

BLINK_RATE

#define BLINK_RATE   500000

Enumeration Type Documentation

keyModifier_t

enum keyModifier_t

Enumerator
NO_SHIFT
SHIFT
CAPS_LOCK
PROPER_NOUN
SPECIAL_DONE

controlChar_t

enum controlChar_t

Enumerator
KEY_SHIFT
KEY_CAPS_LOCK
KEY_BACKSPACE
KEY_SPACE
KEY_EOL
KEY_TAB
KEY_ENTER

bgMode_t

enum bgMode_t

Enumerator
WSG_BG
COLOR_BG
CLEAR_BG

Function Documentation

textEntryInit()

void textEntryInit	(	font_t *	useFont,
		int	max_len,
		char *	buffer )

Initialize the text entry with prettier graphics.

Parameters

useFont	The font to use
max_len	The length of buffer
buffer	A char* to store the entered text in

textEntryDraw()

bool textEntryDraw

(

int64_t

elapsedUs

)

Draw the text entry UI.

Returns

true if text entry is still being used false if text entry is finished

textEntryInput()

bool textEntryInput	(	uint8_t	down,
		uint8_t	button )

Handle button input for text entry.

Parameters

down	true if the button was pressed, false if it was released
button	The button that was pressed

Returns

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

textEntrySetFont()

void textEntrySetFont

(

font_t *

newFont

)

A new font to load into the text entry screen.

Parameters

newFont

pointer to a font file

textEntrySetBgWsg()

void textEntrySetBgWsg

(

wsg_t *

BG

)

Sets a background image and sets the BG Mode to use the WSG.

Parameters

BG	Pointer to Background image to set

textEntrySetBGColor()

void textEntrySetBGColor

(

uint8_t

color

)

Sets the background to use a solid color.

Parameters

color

Color to set the background

textEntrySetBGTransparent()

void textEntrySetBGTransparent

(

void

)

Sets the background to be transparent.

textEntrySetTextColor()

void textEntrySetTextColor	(	uint8_t	color,
		bool	emphasis )

Set the main text color for the keyboard and entry text.

Parameters

color	Color to set the text to.
emphasis	Whether emphasis color should also be set to the same color

textEntrySetEmphasisColor()

void textEntrySetEmphasisColor

(

uint8_t

color

)

Set the emphasis color for the text.

Parameters

color

Color for the emphasis text

textEntrySetShadowboxColor()

void textEntrySetShadowboxColor	(	bool	active,
		uint8_t	color )

Sets the color of the shadowbox.

Parameters

active	Whether these boxes should be drawn
color	Color for the shadowboxes

textEntrySetNewEnterStyle()

void textEntrySetNewEnterStyle

(

bool

newStyle

)

Sets the style of the Enter key.

Parameters

newStyle

if true, use the new style

textEntrySetNewCapsStyle()

void textEntrySetNewCapsStyle

(

bool

newStyle

)

Sets the style of the caps lock key.

Parameters

newStyle

if true, use the new style

textEntrySetMultiline()

void textEntrySetMultiline

(

bool

multiline

)

Sets the text entry mode from single line to multi-line.

Parameters

multiline

True if using multi-line, false if not

Note

cursor does not draw in multiline due to drawTextWordWrap not exposing the end position of the text.

textEntrySoftReset()

void textEntrySoftReset

(

void

)

Allow the text box to continue without a full reset.

textEntrySetPrompt()

void textEntrySetPrompt

(

char *

prompt

)

Sets the prompt text to be displayed. Use an empty string ("") to disable.

Parameters

prompt

Text string to use

textEntrySetCapMode()

void textEntrySetCapMode

(

void

)

Sets the starting mode to capslock.

textEntrySetNoShiftMode()

void textEntrySetNoShiftMode

(

void

)

Sets the starting mode to lowercase text.

textEntrySetShiftMode()

void textEntrySetShiftMode

(

void

)

Sets the starting mode to Shift, does one capital letter.

textEntrySetNounMode()

void textEntrySetNounMode

(

void

)

Sets the starting mode to Porper Nouns (Auto capitalizes first letter after a space)