tcMenu
Classes | Typedefs | Enumerations | Functions
MenuItems.h File Reference

Go to the source code of this file.

Classes

struct  AnyMenuInfo
 
struct  AnalogMenuInfo
 
struct  EnumMenuInfo
 
struct  BooleanMenuInfo
 
struct  SubMenuInfo
 
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 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 }
 
enum  Flags : uint8_t {
  MENUITEM_ACTIVE = 0, MENUITEM_CHANGED = 1, MENUITEM_READONLY = 2, MENUITEM_LOCAL_ONLY = 3,
  MENUITEM_EDITING = 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_SET_VALUE, RENDERFN_GETRANGE, RENDERFN_GETPART
}
 

Functions

void copyMenuItemValue (const MenuItem *item, char *buffer, size_t bufferSize)
 
void copyMenuItemNameAndValue (const MenuItem *item, char *buffer, size_t bufferSize, char additionalSep=':')
 
bool isMenuBasedOnValueItem (const MenuItem *item)
 
bool isMenuRuntime (const MenuItem *t)
 
bool isMenuRuntimeMultiEdit (const MenuItem *t)
 
const RuntimeMenuItemasRuntimeItem (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.

Most of the editable menu items can stored to EEPROM, including AnalogMenuItem, EnumMenuItem, BooleanMenuItem and TextMenuItem


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[5]

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

◆ SubMenuInfo

struct 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.

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

Not used for submenus.

uint16_t maxValue

maximum value that this type can store - always 0

MenuCallbackFn callback

the callback function - not used for submenu's

◆ 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

◆ 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
itemthe menu item that is being drawn
rowthe row in the list of items that is being drawn
modeone of the RenderFnMode enumerations indicating what you need to do.
bufferthe buffer to copy into
bufferSizethe 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

◆ Flags

enum Flags : uint8_t

Each menu item can be in the following states.

Enumerator
MENUITEM_ACTIVE 

the menu is currently active but not editing

MENUITEM_CHANGED 

the menu has changed and needs drawing by the renderer

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_EDITING 

the menu is currently being edited

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_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

Function Documentation

◆ copyMenuItemValue()

void copyMenuItemValue ( const MenuItem item,
char *  buffer,
size_t  bufferSize 
)

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

Parameters
itemthe item who's value is to be copied
bufferthe buffer for the copy
bufferSizesize of the buffer

◆ copyMenuItemNameAndValue()

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

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

Parameters
itemthe item to be copied
bufferthe buffer to copy into
bufferSizethe size of the buffer
additionalSepoptional provide the separator character (use '\0' for no additional separator)

◆ 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