MenuItems.h File Reference

In TcMenu, MenuItem storage is shared between program memory and RAM. Usually each MenuItem has associated Info block and within the InfoBlock, the first fields must be in the same order as AnyMenuInfo. The most commonly used menu items are defined within this file. Each menu item also has a menu item type that is used during rendering and remote communication to determine what it actually is. More...

Go to the source code of this file.

Classes
struct	AnyMenuInfo
struct	AnalogMenuInfo
struct	EnumMenuInfo
struct	BooleanMenuInfo
struct	FloatMenuInfo
class	MenuItem
class	ValueMenuItem
struct	WholeAndFraction
class	AnalogMenuItem
class	EnumMenuItem
class	BooleanMenuItem
class	FloatMenuItem
class	ActionMenuItem

Typedefs
typedef uint16_t	menuid_t
typedef void(*	MenuCallbackFn) (int id)
typedef AnyMenuInfo	SubMenuInfo
typedef int(*	RuntimeRenderingFn) (RuntimeMenuItem *item, uint8_t row, RenderFnMode mode, char *buffer, int bufferSize)

Enumerations
enum	BooleanNaming : uint8_t { NAMING_TRUE_FALSE = 0 , NAMING_ON_OFF , NAMING_YES_NO , NAMING_CHECKBOX }
enum	Flags : uint8_t {   MENUITEM_CHANGED = 0 , MENUITEM_CHANGED_1 = 1 , MENUITEM_READONLY = 3 , MENUITEM_LOCAL_ONLY = 4 ,   MENUITEM_PIN_SECURED = 5 , MENUITEM_PIN_VISIBLE = 6 , MENUITEM_INFO_STRUCT_PGM = 7 , MENUITEM_REMOTE_SEND0 = 10 ,   MENUITEM_REMOTE_SEND1 = 11 , MENUITEM_REMOTE_SEND2 = 12 , MENUITEM_REMOTE_SEND3 = 13 , MENUITEM_REMOTE_SEND4 = 14 ,   MENUITEM_REMOTE_SEND5 = 15 }
enum	MenuType : uint8_t {   MENUTYPE_INT_VALUE = 1 , MENUTYPE_ENUM_VALUE = 2 , MENUTYPE_BOOLEAN_VALUE = 3 , MENUTYPE_FLOAT_VALUE = 101 ,   MENUTYPE_ACTION_VALUE = 102 , MENUTYPE_RUNTIME_VALUE = 150 , MENUTYPE_RUNTIME_LIST = 151 , MENUTYPE_BACK_VALUE = 152 ,   MENUTYPE_ACTIVATE_SUBMENU = 153 , MENUTYPE_SCROLLER_VALUE = 154 , MENUTYPE_SUB_VALUE = 155 , MENUTYPE_TITLE_ITEM = 156 ,   MENUTYPE_DIALOG_BUTTON = 157 , MENUTYPE_TEXT_VALUE = 200 , MENUTYPE_IPADDRESS = 201 , MENUTYPE_TIME = 202 ,   MENUTYPE_DATE = 203 , MENUTYPE_LARGENUM_VALUE = 210 , MENUTYPE_COLOR_VALUE = 211 }
enum	RenderFnMode : uint8_t {   RENDERFN_VALUE , RENDERFN_NAME , RENDERFN_EEPROM_POS , RENDERFN_INVOKE ,   RENDERFN_ACTIVATE , RENDERFN_SET_VALUE , RENDERFN_GETRANGE , RENDERFN_GETPART ,   RENDERFN_SET_TEXT_VALUE }

Functions
void	copyMenuItemValue (const MenuItem *item, char *buffer, size_t bufferSize, bool active=false)
void	copyMenuItemNameAndValue (const MenuItem *item, char *buffer, size_t bufferSize, char additionalSep=':', bool active=false)
void	copyMenuItemValueDefault (const MenuItem *item, char *buffer, size_t bufferSize, const char *defValue, bool active=false)
bool	isMenuBasedOnValueItem (const MenuItem *item)
bool	isMenuRuntime (const MenuItem *t)
bool	isMenuRuntimeMultiEdit (const MenuItem *t)
const RuntimeMenuItem *	asRuntimeItem (const MenuItem *i)

Detailed Description

In TcMenu, MenuItem storage is shared between program memory and RAM. Usually each MenuItem has associated Info block and within the InfoBlock, the first fields must be in the same order as AnyMenuInfo. The most commonly used menu items are defined within this file. Each menu item also has a menu item type that is used during rendering and remote communication to determine what it actually is.

---

Class Documentation

AnyMenuInfo

struct AnyMenuInfo

Every single info structure must have these fields in this order. They are always stored in program memory. It is always safe to use this structure in place of a specific one. This is indeed how the core MenuItem class works.

Class Members
char	name[NAME_SIZE_T]	the name given to this menu item
menuid_t	id	the identifier for this menu
uint16_t	eepromAddr	eeprom address for this item or -1 if not stored
uint16_t	maxValue	maximum value that this type can store
MenuCallbackFn	callback	the callback function

AnalogMenuInfo

struct AnalogMenuInfo

The information block stored in program memory for analog items. Analog items represent a 16 bit unsigned editable value. It can be made negative by applying an offset, and accuracy in decimal places set by the divisor.

Note: These items must remain in this order, as MenuItem relies upon it.

Class Members
char	name[NAME_SIZE_T]	the name given to this menu item
menuid_t	id	the identifier for this menu
uint16_t	eepromAddr	eeprom address for this item or -1 if not stored
uint16_t	maxValue	maximum value that this type can store
MenuCallbackFn	callback	the callback function
int16_t	offset	A 16 bit offset that can be either positive or negative, this will be added to the current value before display
uint16_t	divisor	A divisor that is used to reduce the currentValue by means of division: 0 or 1 : no division 2 thru 10 : single decimal place using optimised rendering above 10 : turned to decimal and displayed to correct number of DP.
char	unitName[UNIT_SIZE_T]	An optional unit name to be presented after the the value. For example V for volts, dB for decibel.

EnumMenuInfo

struct EnumMenuInfo

The information block stored in program memory for enumeration items. Enumeration items are somewhat like a comboBox or choice, they have a predetermined set of options, the current value represents the index of the chosen one.

Note: These items must remain in this order, as MenuItem relies upon it.

Class Members
char	name[NAME_SIZE_T]	the name given to this menu item
menuid_t	id	the identifier for this menu
uint16_t	eepromAddr	eeprom address for this item or -1 if not stored
uint16_t	maxValue	the number of items in the below array.
MenuCallbackFn	callback	the callback function
const char *const *	menuItems	An array of pointers to char arrys. Each one represents a possible choice, for example: const char enumText1[] = "Option 1"; const char* const minfoTextStrs[] = { enumText1 }; Note that on AVR arch. they must be in progam memory

BooleanMenuInfo

struct BooleanMenuInfo

The information block stored in program memory for boolean items. Boolean items hold either true or false only. The text used to represent those value can be changed by chaning the BooleanNaming parameter.

Note: These items must remain in this order, as MenuItem relies upon it.

Class Members
char	name[NAME_SIZE_T]	the name given to this menu item
menuid_t	id	the identifier for this menu
uint16_t	eepromAddr	eeprom address for this item or -1 if not stored
uint16_t	maxValue	maximum value that this type can store - always 1
MenuCallbackFn	callback	the callback function
BooleanNaming	naming	Defines the text that will be used to represent the boolean in this item See also BooleanNaming

FloatMenuInfo

struct FloatMenuInfo

The information block for a floating point menu component. Floating point items are not editable, they are generally to relay status information.

Class Members
char	name[NAME_SIZE_T]	the name given to this menu item
menuid_t	id	the identifier for this menu
uint16_t	eepromAddr	eeprom address for this item or -1 if not stored
uint16_t	numDecimalPlaces	The number of decimal places to render to
MenuCallbackFn	callback	The callback function

Typedef Documentation

MenuCallbackFn

typedef void(* MenuCallbackFn) (int id)

The definition of a callback from a menu item

SubMenuInfo

typedef AnyMenuInfo SubMenuInfo

The information block for a submenu stored in program memory. Sub menus can contain other menu items as children and render as another menu below this menu.

Note: These items must remain in this order, as MenuItem relies upon it.

RuntimeRenderingFn

typedef int(* RuntimeRenderingFn) (RuntimeMenuItem *item, uint8_t row, RenderFnMode mode, char *buffer, int bufferSize)

When implementing runtime menu items, they need to have a render function that is called for to obtain the name and value for each row, and should populate the buffer with appropriate text.

Parameters

item	the menu item that is being drawn
row	the row in the list of items that is being drawn
mode	one of the RenderFnMode enumerations indicating what you need to do.
buffer	the buffer to copy into
bufferSize	the size of the buffer available.

Enumeration Type Documentation

BooleanNaming

enum BooleanNaming : uint8_t

This indicates the preferred terminology to use to describe a boolean value. Such as On/Yes/True etc.

Enumerator
NAMING_TRUE_FALSE	prefer the use of true / false
NAMING_ON_OFF	prefer the use of On / Off
NAMING_YES_NO	prefer the user of Yes and No
NAMING_CHECKBOX	prefer that the user see a checkbox

Flags

enum Flags : uint8_t

Each menu item can be in the following states.

Enumerator
MENUITEM_CHANGED	the menu has changed and needs drawing by the renderer 0
MENUITEM_CHANGED_1	the menu has changed and needs drawing by the renderer 1
MENUITEM_READONLY	the menu cannot be changed by the renderer or remote, it can be changed by calling the setter.
MENUITEM_LOCAL_ONLY	the menu must not be sent remotely, and is only available via the local renderer
MENUITEM_PIN_SECURED	the menu item is secured, and must be accessed with a pin
MENUITEM_PIN_VISIBLE	the menu item is visible on the display and remote
MENUITEM_INFO_STRUCT_PGM	the info structure is in PROGMEM
MENUITEM_REMOTE_SEND0	indicates that remote 0 needs to resend this item
MENUITEM_REMOTE_SEND1	indicates that remote 1 needs to resend this item
MENUITEM_REMOTE_SEND2	indicates that remote 2 needs to resend this item
MENUITEM_REMOTE_SEND3	indicates that remote 3 needs to resend this item
MENUITEM_REMOTE_SEND4	indicates that remote 4 needs to resend this item
MENUITEM_REMOTE_SEND5	indicates that remote 5 needs to resend this item

MenuType

enum MenuType : uint8_t

As we don't have RTTI we need a way of identifying each menu item. Any value below 100 is based on ValueMenuItem and can therefore be edited, otherwise it cannot be edited on the device. MenuItems less than 100 are based on ValueMenuItem and can be edited as an integer. MenuItems greater than 200 are runtime menu items. Items between 100 and 200 are non editable regular menu items.

Enumerator
MENUTYPE_INT_VALUE	item is of type AnalogMenuItem
MENUTYPE_ENUM_VALUE	item is of type EnumMenuItem
MENUTYPE_BOOLEAN_VALUE	item is of type BooleanMenuItem
MENUTYPE_FLOAT_VALUE	item is of type FloatMenuItem
MENUTYPE_ACTION_VALUE	item is of type ActionMenuItem
MENUTYPE_RUNTIME_VALUE	item is a single item of type RuntimeMenuItem
MENUTYPE_RUNTIME_LIST	item is a list, of type MultiRuntimeMenuItem
MENUTYPE_BACK_VALUE	item is of type BackMenuItem
MENUTYPE_ACTIVATE_SUBMENU	item is of type ActivateSubMenuItem
MENUTYPE_SCROLLER_VALUE	item is of type ScrollChoiceMenuItem
MENUTYPE_SUB_VALUE	item is of type SubMenuItem
MENUTYPE_TITLE_ITEM	represents the title item, never sent remotely, only for display
MENUTYPE_DIALOG_BUTTON	A button that can only be part of a dialog
MENUTYPE_TEXT_VALUE	item is of type TextMenuItem
MENUTYPE_IPADDRESS	item is an IP address and is editable per segment
MENUTYPE_TIME	An item that represents a time
MENUTYPE_DATE	An item that represents a date
MENUTYPE_LARGENUM_VALUE	An item that represent a large editable number
MENUTYPE_COLOR_VALUE	Represents an RGBA color picker, where alpha is optional

RenderFnMode

enum RenderFnMode : uint8_t

this is used in the redering function to indicate what needs to be done in this call.

Enumerator
RENDERFN_VALUE	render the current value for the item provided
RENDERFN_NAME	render the name part into the buffer
RENDERFN_EEPROM_POS	Get the eeprom position in the returned int, buffer not needed
RENDERFN_INVOKE	the callback has been triggered, buffer not needed
RENDERFN_ACTIVATE	list only - an item in a list has been activated, IE the index has changed)
RENDERFN_SET_VALUE	A new value for a position in the list, provided in buffer, it's length is in size. - used only in editable mode
RENDERFN_GETRANGE	Gets the range zero based, for this part - used only in editable mode, buffer not needed
RENDERFN_GETPART	Gets the integer value of the current part that is being edited, buffer not needed
RENDERFN_SET_TEXT_VALUE	Sets the value at a given position based on a keyboard press, only currently used by text controls

Function Documentation

copyMenuItemValue()

void copyMenuItemValue	(	const MenuItem *	item,
		char *	buffer,
		size_t	bufferSize,
		bool	active = false
	)

Copies the textual representation suitable for display on a device into the provided buffer safely.

Parameters

item	the item who's value is to be copied
buffer	the buffer for the copy
bufferSize	size of the buffer

copyMenuItemNameAndValue()

void copyMenuItemNameAndValue	(	const MenuItem *	item,
		char *	buffer,
		size_t	bufferSize,
		char	additionalSep = ':',
		bool	active = false
	)

Copies both the name and textual value representation suitable for display on a device into the buffer safely.

Parameters

item	the item to be copied
buffer	the buffer to copy into
bufferSize	the size of the buffer
additionalSep	optional provide the separator character (use '\0' for no additional separator)

copyMenuItemValueDefault()

void copyMenuItemValueDefault	(	const MenuItem *	item,
		char *	buffer,
		size_t	bufferSize,
		const char *	defValue,
		bool	active = false
	)

Copies the item value into the buffer provided using the above copyMenuItemValue method, if the resulting string is empty, then the default is provided instead.

isMenuBasedOnValueItem()

bool isMenuBasedOnValueItem ( const MenuItem *  item )

inline

Any MenuType with an ID less than 100 is editable as an integer

isMenuRuntime()

bool isMenuRuntime ( const MenuItem *  t )

inline

returns true if the menu item is an editable runtime item

isMenuRuntimeMultiEdit()

bool isMenuRuntimeMultiEdit ( const MenuItem *  t )

inline

Returns true if the menu item is a runtime item type. Otherwise returns false.

asRuntimeItem()

const RuntimeMenuItem* asRuntimeItem ( const MenuItem *  i )

inline

gets the menu item as a real time item, only call after determining the menu item is realtime using the above isMenuRuntime() method.

See also

isMenuRuntime