tcMenu
Public Member Functions | Protected Member Functions | List of all members
MenuManager Class Reference

#include <tcMenu.h>

Public Member Functions

void initForEncoder (MenuRenderer *renderer, MenuItem *root, pinid_t encoderPinA, pinid_t encoderPinB, pinid_t encoderButton, EncoderType type=FULL_CYCLE)
 
void initForUpDownOk (MenuRenderer *renderer, MenuItem *root, pinid_t downPin, pinid_t upPin, pinid_t okPin)
 
void initWithoutInput (MenuRenderer *renderer, MenuItem *root)
 
void setBackButton (pinid_t backButtonPin)
 
void setNextButton (pinid_t nextButtonPin)
 
void setRootMenu (MenuItem *menuItem)
 
void setAuthenticator (AuthenticationManager *manager)
 
AuthenticationManagergetAuthenticator ()
 
void setItemCommittedHook (MenuCallbackFn commitCallback)
 
void valueChanged (int value)
 
void onMenuSelect (bool held)
 
void performDirectionMove (bool dirIsBack)
 
void setItemsInCurrentMenu (int size, int offs=0)
 
EepromAbstraction * getEepromAbstraction ()
 
void setEepromRef (EepromAbstraction *globalRom)
 
void load (EepromAbstraction &eeprom, uint16_t magicKey=0xfade, TimerFn onEepromEmpty=nullptr)
 
void load (uint16_t magicKey=0xfade, TimerFn onEepromEmpty=nullptr)
 
void save (uint16_t magicKey=0xfade)
 
void save (EepromAbstraction &eeprom, uint16_t magicKey=0xfade)
 
MenuItemfindCurrentActive ()
 
bool activateMenuItem (MenuItem *item)
 
MenuItemgetRoot ()
 
MenuRenderergetRenderer ()
 
MenuItemgetCurrentEditor ()
 
void setCurrentEditor (MenuItem *editor)
 
void changeMenu (MenuItem *possibleActive=nullptr)
 
void navigateToMenu (MenuItem *theNewItem, MenuItem *possibleActive=nullptr, bool customMenu=false)
 
void resetMenu (bool completeReset)
 
MenuItemgetCurrentMenu ()
 
MenuItemgetCurrentSubMenu ()
 
MenuItemgetParentAndReset ()
 
int getCurrentRangeValue ()
 
SecuredMenuPopupsecureMenuInstance ()
 
void stopEditingCurrentItem (bool checkMultiPart)
 
void addMenuAfter (MenuItem *existing, MenuItem *toAdd, bool silent=false)
 
void notifyStructureChanged ()
 
void addChangeNotification (MenuManagerObserver *observer)
 

Protected Member Functions

void setupForEditing (MenuItem *item)
 
void actionOnCurrentItem (MenuItem *toEdit)
 
void actionOnSubMenu (MenuItem *nextSub)
 
void notifyEditEnd (MenuItem *pItem)
 
bool notifyEditStarting (MenuItem *pItem)
 

Detailed Description

MenuManager ties together all the parts of the menu app, it looks after the menu structure that's being presented, the renderer, security, and optionally an eeprom.

Member Function Documentation

◆ initForEncoder()

void MenuManager::initForEncoder ( MenuRenderer renderer,
MenuItem root,
pinid_t  encoderPinA,
pinid_t  encoderPinB,
pinid_t  encoderButton,
EncoderType  type = FULL_CYCLE 
)

Initialise the menu manager to use a hardware rotary encoder

Parameters
rendererthe renderer used for drawing
rootthe first menu item
encoderPinAencoder A pin
encorerPinBencoder B pin
encoderButtonthe OK button for the menu select / edit action
typeoptionally, you can provide the encoder type, only really needed for quarter cycle encoders.

◆ initForUpDownOk()

void MenuManager::initForUpDownOk ( MenuRenderer renderer,
MenuItem root,
pinid_t  downPin,
pinid_t  upPin,
pinid_t  okPin 
)

Initialise for up down and OK button, instead of using hardware changeEncoderPrecision

Parameters
rendererthe renderer used for drawing
rootthe first menu item
downPinthe button for down
upPinthe button on up
okPinthe OK button for the menu select / edit action

◆ initWithoutInput()

void MenuManager::initWithoutInput ( MenuRenderer renderer,
MenuItem root 
)

Initialise in situations where local input is not needed or where a custom type of input is needed that is not one of the common types.

In the case of custom input make sure that:

  1. something will call menuMgr.onMenuSelect(bool held) when the select button is pressed
  2. something will call menuMgr.valueChanged(int value) when the current value goes up / down.
Parameters
rendererthe renderer used for drawing
rootthe first menu item

◆ setBackButton()

void MenuManager::setBackButton ( pinid_t  backButtonPin)

You can add a back button that generally performs the back or left function

Parameters
backButtonPinthe pin on which the back button is assigned.

◆ setNextButton()

void MenuManager::setNextButton ( pinid_t  nextButtonPin)

YOu can add a next button that generally performs the next or right function

Parameters
nextButtonPinthe pin to which the next button is assigned

◆ setRootMenu()

void MenuManager::setRootMenu ( MenuItem menuItem)
inline

Sometimes you need to use the menu structure before everything is initialised, in this case you can call this function early on to set up the root menu item.

◆ setAuthenticator()

void MenuManager::setAuthenticator ( AuthenticationManager manager)
inline

If you want to be able to secure sub menus you have to provide an authentication manger. Normally create a global authentication manager and pass it into menuMgr and your remote server if you have one.

Parameters
managerthe authentication manager to use for the submenu pin lock.

◆ getAuthenticator()

AuthenticationManager* MenuManager::getAuthenticator ( )
inline
Returns
the global authentication manager that has been set for this menu application, or nullptr otherwise

◆ setItemCommittedHook()

void MenuManager::setItemCommittedHook ( MenuCallbackFn  commitCallback)
inline

This is a special callback, one per menu that indicates when a commit has taken place rather than when there has been a change. It uses the same callback signature as the standard change callback.

Parameters
commitCallbackthe callback to be notified when there is a commit event.

◆ valueChanged()

void MenuManager::valueChanged ( int  value)

called when the rotary encoder has moved to a new position to update the menu

Parameters
valuethe new changed value

Called when the rotary encoder value has changed, if we are editing this changes the value in the current editor, if we are showing menu items, it changes the index of the active item (renderer will move into display if needed).

◆ onMenuSelect()

void MenuManager::onMenuSelect ( bool  held)

Called when the OK button has been pressed

Parameters
heldif the button is held down

Called when the button on the encoder (OK button) is pressed. Most of this is left to the renderer to decide.

◆ performDirectionMove()

void MenuManager::performDirectionMove ( bool  dirIsBack)

This provides support for next and back (left, right) functionality by making the menu structure respond to such functions in a reasonable way.

Parameters
dirIsBacktrue for back (left), false for next (right)

◆ setItemsInCurrentMenu()

void MenuManager::setItemsInCurrentMenu ( int  size,
int  offs = 0 
)

Sets the number of items and offset of the items in the current menu

Parameters
sizethe number of items
offsthe offset within the items

◆ setEepromRef()

void MenuManager::setEepromRef ( EepromAbstraction *  globalRom)
inline

Sets the global eeprom reference that tcMenu and other apps can use throughout the program.

Parameters
globalRom

◆ load() [1/2]

void MenuManager::load ( EepromAbstraction &  eeprom,
uint16_t  magicKey = 0xfade,
TimerFn  onEepromEmpty = nullptr 
)

Used during initialisation to load the previously stored state. Only if the magic key matches at location 0. It will also set the global eeprom variable like calling setEepromRef().

◆ load() [2/2]

void MenuManager::load ( uint16_t  magicKey = 0xfade,
TimerFn  onEepromEmpty = nullptr 
)

Used during initialisation to load the previously stored state. Only if the magic key matches at location 0. This version requires that you have first set the eeprom abstraction using setEepromRef().

◆ save() [1/2]

void MenuManager::save ( uint16_t  magicKey = 0xfade)
inline

Saves the menu using the EEPROM ref that was set up either during load, or by calling setEepromRef(). To use this version you must ensure the eeprom was previously set. The magic key is saved first, followed by each item that has an eeprom location set. Only changes are saved because before each write we check if the value has actually changed.

Parameters
magicKeythe key that indicates the values are valid.

◆ save() [2/2]

void MenuManager::save ( EepromAbstraction &  eeprom,
uint16_t  magicKey = 0xfade 
)
inline

Call to save all item values into eeprom. The magic key is saved at location 0 if not already set. This is a lazy save that reads the eeprom values first, and only saves to eeprom when there are changes. Use this version when you want to override the eeprom used

◆ findCurrentActive()

MenuItem * MenuManager::findCurrentActive ( )

Find the menu item that is currently active.

Finds teh currently active menu item with the selected SubMenuItem

◆ activateMenuItem()

bool MenuManager::activateMenuItem ( MenuItem item)

Activates the menu item provided if it is within the current menu, this actually does more than set active, it does the equivalent of an encoder button press.

Parameters
itemthe item to activate
Returns
if the item was activated

◆ getRoot()

MenuItem* MenuManager::getRoot ( )
inline

Get the root of all menus, the first menu item basically

◆ getRenderer()

MenuRenderer* MenuManager::getRenderer ( )
inline

Get the renderer that this menu is using

◆ getCurrentEditor()

MenuItem* MenuManager::getCurrentEditor ( )
inline

Get the current MenuItem that is being edited (or null)

◆ setCurrentEditor()

void MenuManager::setCurrentEditor ( MenuItem editor)

Change the editor control that is receiving changes to apply to the menu item.

Parameters
editorthe new editor or NULL

◆ changeMenu()

void MenuManager::changeMenu ( MenuItem possibleActive = nullptr)

Set the root item of either the first menu or any sub menu

Parameters
theItemthe item to become the current root of the menu.

◆ navigateToMenu()

void MenuManager::navigateToMenu ( MenuItem theNewItem,
MenuItem possibleActive = nullptr,
bool  customMenu = false 
)

Navigate to the menu and ensure it is display, further, you can optionally provide an item in the menu to activate, not doing so selects the first possible item.

Parameters
theNewItemthe root menu item to display
possibleActivethe item to activate or null for default
customMenuset to true if this menu is custom and should not be stored in the history

◆ resetMenu()

void MenuManager::resetMenu ( bool  completeReset)

Force a complete reset of the menu

◆ getCurrentMenu()

MenuItem* MenuManager::getCurrentMenu ( )
inline

Get the first menu item in the linked list that is being rendered

◆ getParentAndReset()

MenuItem * MenuManager::getParentAndReset ( )

Get the parent of the current menu clearing all active flags too

◆ getCurrentRangeValue()

int MenuManager::getCurrentRangeValue ( )
inline

returns the range of the encoder or other device that is providing the equivalent function as the encoder.

◆ secureMenuInstance()

SecuredMenuPopup * MenuManager::secureMenuInstance ( )

gets the secure menu popup instance that can be used to ask for a password on the device.

Returns
the single instance of this popup.

◆ addMenuAfter()

void MenuManager::addMenuAfter ( MenuItem existing,
MenuItem toAdd,
bool  silent = false 
)

Adds a menu item into the tree directly after the existing item provided. Never add an item that's already in the tree. Don't forget that if you use silent, to call menuStructureChanged() after you're done adding items.

Parameters
existingwhere in the tree the new item is to be added.
toAddthe item that should be added, must not be in the tree already.
silentdo not run the structure changed callback.

◆ notifyStructureChanged()

void MenuManager::notifyStructureChanged ( )

Call this method after making any structural change to the menu tree. For example adding a new menu item, changing the item name or static data such as size parameters. For example: modifying an items name, etc.

◆ addChangeNotification()

void MenuManager::addChangeNotification ( MenuManagerObserver observer)

Adds an observer that will be notified of structure changes in the menu

Parameters
observerto be notified of structure changes.

The documentation for this class was generated from the following files: