dialogBox.h File Reference

Detailed Description

Design Philosophy

Dialog boxes are a simple, generic way to show a message and/or prompt the user for a response.

Example

Const strings and declarations for the example dialog box:

// Declare the title and body text
static const char dialogTitle = "Confirmation";
static const char dialogDetail = "Something happened! Continue?";
 
// Declare the option labels
static const char optCancel[] = "Cancel";
static const char optOk[] = "OK";
 
// Declare the callback
static void dialogBoxCb(const char* label);

Initialize the dialog box:

bool dialogComplete = false;
bool confirmed = false;
font_t dialogFont;
wsg_t infoIcon;
loadFont("ibm_vga8.font", &dialogFont, false);
loadWsg("info.wsg", &infoIcon, false);
dialogBox_t* dialog = initDialogBox(dialogTitle, dialogDetail, &infoIcon, dialogBoxCb);

Inside the main loop:

clearPxTft();
if (!dialogComplete)
{
    buttonEvt_t evt = {0};
    while (checkButtonQueueWrapper(&evt))
    {
        dialogBoxButton(button, &evt);
    }
 
    // Draw the dialog, sized automatically, in the center of the screen
    drawDialogbox(dialog, &dialogFont, &dialogFont, DIALOG_CENTER, DIALOG_CENTER, DIALOG_AUTO, DIALOG_AUTO, 6);
}
else
{
    const char* message = confirmed ? "Confirmed" : "Cancelled";
    drawText(&dialogFont, c555, message, (TFT_WIDTH - textWidth(&dialogFont, message)) / 2, (TFT_HEIGHT -
dialogFont.height) / 2);
}

static void dialogBoxCb(const char* label)
{
    if (optCancel == label)
    {
        printf("Cancel\n");
        dialogComplete = true;
    }
    else if (optOk == label)
    {
        printf("OK!\n");
        dialogComplete = true;
        confirmed = true;
    }
}

Go to the source code of this file.

Data Structures
struct	dialogBoxOption_t
struct	dialogBox_t

Macros
#define	DIALOG_CENTER   (1 << 15)
	If passed for X or Y, will center the dialog box on that axis.
#define	DIALOG_AUTO   (1 << 15)
	If passed for W or H, will calculate the size of the dialog box based on its contents.

Typedefs
typedef void(*	dialogBoxCbFn_t) (const char *label)

Enumerations
enum	dialogOptionHint_t {   OPTHINT_NORMAL = 0 , OPTHINT_OK = 1 , OPTHINT_CANCEL = 2 , OPTHINT_DEFAULT = 4 ,   OPTHINT_DISABLED = 8 }
	Hints for the dialog box renderer. Multiple options can be combined with bitwise OR. More...

Functions
dialogBox_t *	initDialogBox (const char *title, const char *detail, const wsg_t *icon, dialogBoxCbFn_t cbFn)
	Allocate and return a new dialogBox_t with the given settings.
void	deinitDialogBox (dialogBox_t *dialogBox)
	Deallocate all memory associated with the given dialog box.
void	dialogBoxAddOption (dialogBox_t *dialogBox, const char *label, const wsg_t *icon, dialogOptionHint_t hints)
	Add an option button to a dialog box.
void	dialogBoxReset (dialogBox_t *dialogBox)
	Clear all options from the given dialog box.
void	drawDialogBox (const dialogBox_t *dialogBox, const font_t *titleFont, const font_t *detailFont, uint16_t x, uint16_t y, uint16_t w, uint16_t h, uint16_t r)
	Draw the dialog box.
void	dialogBoxButton (dialogBox_t *dialogBox, const buttonEvt_t *evt)
	Handle button presses for the dialog box.

---

Data Structure Documentation

dialogBoxOption_t

struct dialogBoxOption_t

Data Fields
const char *	label	The text to draw in the dialog.
const wsg_t *	icon	The icon, if any, to draw inside the option button.
dialogOptionHint_t	hints	The rendering hints for the option button.

dialogBox_t

struct dialogBox_t

Data Fields
const wsg_t *	icon	The icon to draw in the left side of the dialog box, or NULL for no icon.
const char *	title	The title of the dialog box to draw at the top.
const char *	detail	The text in the body of the dialog box.
list_t	options	The linked list of dialog box options.
node_t *	selectedOption	The currently-selected option.
dialogBoxCbFn_t	cbFn	The callback function for when an item is selected.
bool	holdA	Whether A is being held.
bool	holdB	Whether B is being held.

Macro Definition Documentation

DIALOG_CENTER

#define DIALOG_CENTER   (1 << 15)

If passed for X or Y, will center the dialog box on that axis.

DIALOG_AUTO

#define DIALOG_AUTO   (1 << 15)

If passed for W or H, will calculate the size of the dialog box based on its contents.

Typedef Documentation

dialogBoxCbFn_t

typedef void(* dialogBoxCbFn_t) (const char *label)

Enumeration Type Documentation

dialogOptionHint_t

enum dialogOptionHint_t

Hints for the dialog box renderer. Multiple options can be combined with bitwise OR.

Enumerator
OPTHINT_NORMAL	No special options for this dialog option.
OPTHINT_OK	This option is the "OK" option.
OPTHINT_CANCEL	This option is the "Cancel" option, and will be selected if the user presses B.
OPTHINT_DEFAULT	This option should be selected by default when the dialog resets.
OPTHINT_DISABLED	This option should be shown, but should not be selectable.

Function Documentation

initDialogBox()

dialogBox_t * initDialogBox	(	const char *	title,
		const char *	detail,
		const wsg_t *	icon,
		dialogBoxCbFn_t	cbFn )

Allocate and return a new dialogBox_t with the given settings.

The result must be deallocated with deinitDialogBox().

Parameters

title	The title text of the dialog box
detail	The body text of the dialog box
icon	The icon to display in the dialog box, if not NULL
cbFn	The callback function to be called when an option is selected

Returns

dialogBox_t* The newly allocated dialog box

deinitDialogBox()

void deinitDialogBox

(

dialogBox_t *

dialogBox

)

Deallocate all memory associated with the given dialog box.

Parameters

dialogBox

The dialog box to deinitialize

dialogBoxAddOption()

void dialogBoxAddOption	(	dialogBox_t *	dialogBox,
		const char *	label,
		const wsg_t *	icon,
		dialogOptionHint_t	hints )

Add an option button to a dialog box.

Parameters

dialogBox	The dialog box to add the button to
label	The text of the option button
icon	The icon for this button, or NULL for no icon
hints	Any number of dialogOptionHint_t, combined with bitwise OR for multiple

dialogBoxReset()

void dialogBoxReset

(

dialogBox_t *

dialogBox

)

Clear all options from the given dialog box.

Parameters

dialogBox

The dialog box to reset

drawDialogBox()

void drawDialogBox	(	const dialogBox_t *	dialogBox,
		const font_t *	titleFont,
		const font_t *	detailFont,
		uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	h,
		uint16_t	r )

Draw the dialog box.

Parameters

dialogBox	The dialog box to draw
titleFont	The font to use for drawing the dialog box title text
detailFont	The font to use for drawing the dialog box detail text
x	The X coordinate of the left side of the dialog box, or DIALOG_CENTER to automatically center it
y	The Y coordinate of the top of the dialog box, or DIALOG_CENTER to automatically center it
w	The width of the dialog box, or if combined with DIALOG_AUTO, the maximum width of the dialog box
h	The height of the dialog box, or if combined with DIALOG_AUTO, the maximum height of the dialog box
r	The corner-radius of the dialog box

dialogBoxButton()

void dialogBoxButton	(	dialogBox_t *	dialogBox,
		const buttonEvt_t *	evt )

Handle button presses for the dialog box.

Parameters

dialogBox	The dialog box to update
evt	The button event to be handled by the dialog box