menu.c File Reference

Functions
menu_t *	initMenu (const char *title, menuCb cbFunc)
	Initialize and return an empty menu. A menu is a collection of vertically scrollable rows. The rows are separated into pages, and when a page boundary is crossed the whole page scrolls.
void	deinitMenu (menu_t *menu)
	Deinitialize a menu and all connected menus, including submenus and parent menus. This frees memory allocated for this menu, but not memory allocated elsewhere, like the font or item labels.
menu_t *	startSubMenu (menu_t *menu, const char *label)
	Add a submenu item to the menu. When this item is select, the submenu is rendered. The menuCb is not called.
menu_t *	endSubMenu (menu_t *menu)
	Finish adding items to a submenu and resume adding items to the parent menu. This will automatically add a "Back" item to the submenu, which returns to the parent menu. menuCb will not be called when "Back" is selected.
menuItem_t *	addSingleItemToMenu (menu_t *menu, const char *label)
	Add a single item entry to the menu. When this item is selected, the menuCb callback is called with the given label as the argument.
void	removeSingleItemFromMenu (menu_t *menu, const char *label)
	Remove a single item entry from the menu. This item is removed by pointer, not by doing a string comparison.
void	addMultiItemToMenu (menu_t *menu, const char *const *labels, uint8_t numLabels, uint8_t currentLabel)
	Add a multiple item entry to the menu. The multiple items exist in a single entry and are left-right scrollable. The menuCb callback will be called each time the multi-item scrolls with the newly selected label as the argument. The menuCb callback will also be called if the currently displayed label is selected with that label as the argument.
void	removeMultiItemFromMenu (menu_t *menu, const char *const *labels)
	Remove a multi item entry from the menu. This item is removed by pointer, not by doing any string comparisons.
void	addSettingsItemToMenu (menu_t *menu, const char *label, const settingParam_t *bounds, int32_t val)
	Add a settings entry to the menu. A settings entry is left-right scrollable where an integer setting is incremented or decremented. The menuCb callback will be called each time the settings change with the newly selected value as the argument. The menuCb callback will also be called if the currently displayed setting is selected with that value as the argument.
void	removeSettingsItemFromMenu (menu_t *menu, const char *label)
	Remove a settings item entry from the menu. This item is removed by pointer, not by doing any string comparisons.
void	addSettingsOptionsItemToMenu (menu_t *menu, const char *settingLabel, const char *const *optionLabels, const int32_t *optionValues, uint8_t numOptions, const settingParam_t *bounds, int32_t currentValue)
	Adds a settings item entry to the menu with a specific list of options. The entry will be left-right scrollable. The menuCb callback will be called each time the setting-options item scrolls or is selected with the newly selected label and setting value as the arguments.
void	removeSettingsOptionsItemFromMenu (menu_t *menu, const char *const *optionLabels)
	Remove a settings options item entry from the menu. This item is removed by pointer, not by doing any string comparisons.
menu_t *	menuNavigateToItem (menu_t *menu, const char *label)
	Changes the selected item to the one with the given label, just as though it were scrolled to.
menu_t *	menuNavigateToPrevItem (menu_t *menu)
	Navigate to the previous item in the menu. This is equivalent to pressing the UP button.
menu_t *	menuNavigateToNextItem (menu_t *menu)
	Navigate to the next item in the menu. This is equivalent to pressing the DOWN button.
menu_t *	menuNavigateToPrevOption (menu_t *menu)
	Navigate to the previous option in a menu item. This is equivalent to pressing the LEFT button.
menu_t *	menuNavigateToNextOption (menu_t *menu)
	Navigate to the next option in a menu item. This is equivalent to pressing the RIGHT button.
menu_t *	menuSelectCurrentItem (menu_t *menu)
	Select the current item in a menu item. This is equivalent to pressing the A button.
menu_t *	menuSetCurrentOption (menu_t *menu, int32_t value)
	Performs the equivalent of scrolling to the given setting value or option index for the currently selected menu item.
menu_t *	menuButton (menu_t *menu, buttonEvt_t evt)
	This must be called to pass button event from the Swadge mode to the menu. If a button is passed here, it should not be handled anywhere else.
void	setShowBattery (menu_t *menu, bool showBattery)
	Show or hide the battery on the menu. This should be called from the root menu after the menu is constructed.

Variables
const char *	mnuBackStr = "Back"
	A string used to return to super-menus that says "Back".

Function Documentation

initMenu()

menu_t * initMenu	(	const char *	title,
		menuCb	cbFunc )

Initialize and return an empty menu. A menu is a collection of vertically scrollable rows. The rows are separated into pages, and when a page boundary is crossed the whole page scrolls.

Rows may be single items, or multi items, which are collections of horizontally scrollable items. The callback is called whenever a row is moved to or selected, and when a multi item is scrolled to or selected.

Rows may also be submenus. When a submenu is selected, the callback is not called, and instead a the submenu is rendered. Each submenu automatically has a "Back" item added to it, which returns to the parent menu

Parameters

title	The title to be displayed for this menu. The underlying memory isn't copied, so this string must persist for the lifetime of the menu.
cbFunc	The function to call when a menu option is selected. The argument to the callback will be the same pointer

Returns

A pointer to the newly allocated menu_t. This must be de-initialized when the menu is not used anymore.

deinitMenu()

void deinitMenu

(

menu_t *

menu

)

Deinitialize a menu and all connected menus, including submenus and parent menus. This frees memory allocated for this menu, but not memory allocated elsewhere, like the font or item labels.

Parameters

menu	The menu to deinitialize

startSubMenu()

menu_t * startSubMenu	(	menu_t *	menu,
		const char *	label )

Add a submenu item to the menu. When this item is select, the submenu is rendered. The menuCb is not called.

All items added to this menu_t after calling startSubMenu() will be added in this submenu until endSubMenu() is called. Submenus have no limitations on how many submenus may be nested.

Submenu items are rendered with an icon indicating that it is a submenu.

Parameters

menu	The menu to create a submenu in
label	The label for this submenu. The underlying memory isn't copied, so this string must persist for the lifetime of the menu

Returns

A pointer to the submenu

endSubMenu()

menu_t * endSubMenu

(

menu_t *

menu

)

Finish adding items to a submenu and resume adding items to the parent menu. This will automatically add a "Back" item to the submenu, which returns to the parent menu. menuCb will not be called when "Back" is selected.

During menu construction, each call to startSubMenu() must have a corresponding call to endSubMenu()

Parameters

menu	The menu to end a submenu in

Returns

A pointer to the parent menu to use for future function calls

addSingleItemToMenu()

menuItem_t * addSingleItemToMenu	(	menu_t *	menu,
		const char *	label )

Add a single item entry to the menu. When this item is selected, the menuCb callback is called with the given label as the argument.

Parameters

menu	The menu to add a single item to
label	The label for this item. The underlying memory isn't copied, so this string must persist for the lifetime of the menu

Returns

The new menuItem_t that was added to the menu

removeSingleItemFromMenu()

void removeSingleItemFromMenu	(	menu_t *	menu,
		const char *	label )

Remove a single item entry from the menu. This item is removed by pointer, not by doing a string comparison.

Parameters

menu	The menu to remove a single item from
label	The label for the item to remove

addMultiItemToMenu()

void addMultiItemToMenu	(	menu_t *	menu,
		const char *const *	labels,
		uint8_t	numLabels,
		uint8_t	currentLabel )

Add a multiple item entry to the menu. The multiple items exist in a single entry and are left-right scrollable. The menuCb callback will be called each time the multi-item scrolls with the newly selected label as the argument. The menuCb callback will also be called if the currently displayed label is selected with that label as the argument.

Multi items are rendered with an icon indicating that it is horizontally scrollable.

Parameters

menu	The menu to add a multi-item to
labels	All of the labels for this multi-item. The underlying memory isn't copied, so this string must persist for the lifetime of the menu
numLabels	The number of labels for this multi-item
currentLabel	The current label index to display

removeMultiItemFromMenu()

void removeMultiItemFromMenu	(	menu_t *	menu,
		const char *const *	labels )

Remove a multi item entry from the menu. This item is removed by pointer, not by doing any string comparisons.

Parameters

menu	The menu to remove a multi item from
labels	The labels to remove

addSettingsItemToMenu()

void addSettingsItemToMenu	(	menu_t *	menu,
		const char *	label,
		const settingParam_t *	bounds,
		int32_t	val )

Add a settings entry to the menu. A settings entry is left-right scrollable where an integer setting is incremented or decremented. The menuCb callback will be called each time the settings change with the newly selected value as the argument. The menuCb callback will also be called if the currently displayed setting is selected with that value as the argument.

Settings items are rendered with an icon indicating that it is horizontally scrollable.

Parameters

menu	The menu to add a settings item to
label	The label for this setting. The integer setting will be drawn after it
bounds	The bounds for this setting
val	The starting value for the setting

removeSettingsItemFromMenu()

void removeSettingsItemFromMenu	(	menu_t *	menu,
		const char *	label )

Remove a settings item entry from the menu. This item is removed by pointer, not by doing any string comparisons.

Parameters

menu	The menu to remove a multi item from
label	The label to remove

addSettingsOptionsItemToMenu()

void addSettingsOptionsItemToMenu	(	menu_t *	menu,
		const char *	settingLabel,
		const char *const *	optionLabels,
		const int32_t *	optionValues,
		uint8_t	numOptions,
		const settingParam_t *	bounds,
		int32_t	currentValue )

Adds a settings item entry to the menu with a specific list of options. The entry will be left-right scrollable. The menuCb callback will be called each time the setting-options item scrolls or is selected with the newly selected label and setting value as the arguments.

Parameters

menu	The menu to add a settings options item to
settingLabel	The overall label for this setting. This is what will be passed to the callback when the selected option changes, and this value will be rendered preceding the selected option's label.
optionLabels	All of the labels for each option. The underlying memory isn't copied, so these strings must persist for the lifetime of the menu. The label value for the selected option will be rendered following the settingLabel.
optionValues	The corresponding settings values for each option. The underlying memory isn't copied, so this array must persist for the lifetime of the menu. These values will not be rendered, but will be passed to the callback as the value when the selected option is changed.
numOptions	The number of options and labels for this settings item.
bounds	The bounds for this setting
currentValue	The current value of the setting. Must be one of the values in optionValues.

removeSettingsOptionsItemFromMenu()

void removeSettingsOptionsItemFromMenu	(	menu_t *	menu,
		const char *const *	optionLabels )

Remove a settings options item entry from the menu. This item is removed by pointer, not by doing any string comparisons.

Parameters

menu	The menu to remove a multi item from
optionLabels	The list of option labels to remove

menuNavigateToItem()

menu_t * menuNavigateToItem	(	menu_t *	menu,
		const char *	label )

Changes the selected item to the one with the given label, just as though it were scrolled to.

Parameters

menu	The menu to change the selected item of
label	The label of the menu item or an option to select

Returns

A pointer to the menu to use for future function calls. It may be a sub or parent menu.

menuNavigateToPrevItem()

menu_t * menuNavigateToPrevItem

(

menu_t *

menu

)

Navigate to the previous item in the menu. This is equivalent to pressing the UP button.

Parameters

menu	The menu to navigate in

Returns

A pointer to the menu to use for future function calls. It may be a sub or parent menu.

menuNavigateToNextItem()

menu_t * menuNavigateToNextItem

(

menu_t *

menu

)

Navigate to the next item in the menu. This is equivalent to pressing the DOWN button.

Parameters

menu	The menu to navigate in

Returns

A pointer to the menu to use for future function calls. It may be a sub or parent menu.

menuNavigateToPrevOption()

menu_t * menuNavigateToPrevOption

(

menu_t *

menu

)

Navigate to the previous option in a menu item. This is equivalent to pressing the LEFT button.

Parameters

menu	The menu to navigate in

Returns

A pointer to the menu to use for future function calls. It may be a sub or parent menu.

menuNavigateToNextOption()

menu_t * menuNavigateToNextOption

(

menu_t *

menu

)

Navigate to the next option in a menu item. This is equivalent to pressing the RIGHT button.

Parameters

menu	The menu to navigate in

Returns

A pointer to the menu to use for future function calls. It may be a sub or parent menu.

menuSelectCurrentItem()

menu_t * menuSelectCurrentItem

(

menu_t *

menu

)

Select the current item in a menu item. This is equivalent to pressing the A button.

Parameters

menu	The menu to select an item in

Returns

A pointer to the menu to use for future function calls. It may be a sub or parent menu.

menuSetCurrentOption()

menu_t * menuSetCurrentOption	(	menu_t *	menu,
		int32_t	value )

Performs the equivalent of scrolling to the given setting value or option index for the currently selected menu item.

Parameters

menu	The menu to scroll the selected item of
value	The setting value or option index to scroll to

Returns

menu_t* The menu

menuButton()

menu_t * menuButton	(	menu_t *	menu,
		buttonEvt_t	evt )

This must be called to pass button event from the Swadge mode to the menu. If a button is passed here, it should not be handled anywhere else.

Parameters

menu	The menu to process button events for
evt	The button event that occurred

Returns

A pointer to the menu to use for future function calls. It may be a sub or parent menu.

setShowBattery()

void setShowBattery	(	menu_t *	menu,
		bool	showBattery )

Show or hide the battery on the menu. This should be called from the root menu after the menu is constructed.

Parameters

menu	The menu to show a battery indicator on
showBattery	true to show the battery, false to hide it

Variable Documentation

mnuBackStr

const char* mnuBackStr = "Back"

A string used to return to super-menus that says "Back".