Base class for complex menus. More...

Detailed Description

Base class for complex menus.

Author: jelliesen

This is the base class for any form of UiPage that displays a menu with multiple items. It handles all the logic behind a menu (selecting items, editing items, etc.) but doesn't implement any form of drawing. Implement your own drawing routines by overriding UiPage::Draw() or use FullScreenItemMenu

Vaious types of items can be added to the menu, e.g.

Checkbox items to toggle something on/off,
Generic action items that call a function when activated,
Value editing items for editing int/float/enum values,
Close items that close the menu when activated (useful when no cancel button is available),
Custom items that do whatever you want them to do, by providing a CustomItem object that handles the item-specific functionality.

The Abstract Menu can work with a wide variety of physical controls, here are a couple of combinations that are possible:

3 buttons: Left/Right to select and edit items, Ok to activate or enter/leave editing mode
5 buttons: Up/Down to select, Ok to activate/enter/leave, Cancel to close menu, function button to use coarse step size when editing
6 buttons: Left/Right to select, Up/Down to quickly edit selected items, Ok/Cancel to enter/leave
1 encoder with pushbutton
1 encoder for selecting items, another one for editing their values
1 encoder for selecting items and a value slider potentiometer for editing
... any other combination of the above

These are the controls that the AbstractMenu will react to and their associated function:

Left/Right buttons: Select items when Orientation::leftRightSelectUpDownModify, directly edit value of the selected item when Orientation::upDownSelectLeftRightModify.
Up/Down buttons: Select items when Orientation::upDownSelectLeftRightModify, directly edit value of the selected item when Orientation::leftRightSelectUpDownModify.
Ok button: Activate the action of the selected item (if it has an action, e.g. ItemType::closeMenuItem) otherwise enter/leave editing mode where the arrow buttons used for selection will now edit the value instead (only possible if allowEntering is set to true).
Cancel button: Closes the menu page or leaves editing mode
Menu encoder: Selects items; edits item value when in editing mode
Value Encoder: Edits value of selected item
Value potentiometer/slider: Edits value of selected item
Function button: Uses an alternate step size when modifying the value with encoders or buttons while pressed

#include <AbstractMenu.h>

Inheritance diagram for daisy::AbstractMenu:

Classes
class	CustomItem

struct	ItemConfig

Public Types
enum class	Orientation { leftRightSelectUpDownModify , upDownSelectLeftRightModify }

enum class	ItemType { callbackFunctionItem , checkboxItem , valueItem , openUiPageItem , closeMenuItem , customItem }

Public Member Functions
	AbstractMenu ()=default

virtual	~AbstractMenu () override

uint16_t	GetNumItems () const

const ItemConfig &	GetItem (uint16_t itemIdx) const

void	SelectItem (uint16_t itemIdx)

int16_t	GetSelectedItemIdx () const

bool	OnOkayButton (uint8_t numberOfPresses, bool isRetriggering) override

bool	OnCancelButton (uint8_t numberOfPresses, bool isRetriggering) override

bool	OnArrowButton (ArrowButtonType arrowType, uint8_t numberOfPresses, bool isRetriggering) override

bool	OnFunctionButton (uint8_t numberOfPresses, bool isRetriggering) override

bool	OnMenuEncoderTurned (int16_t turns, uint16_t stepsPerRevolution) override

bool	OnValueEncoderTurned (int16_t turns, uint16_t stepsPerRevolution) override

bool	OnValuePotMoved (float newPosition) override

void	OnShow () override

Public Member Functions inherited from daisy::UiPage
	UiPage ()

virtual	~UiPage ()

virtual bool	IsOpaque (const UiCanvasDescriptor &display)

bool	IsActive ()

virtual void	OnUserInteraction ()

void	Close ()

virtual bool	OnButton (uint16_t buttonID, uint8_t numberOfPresses, bool isRetriggering)

virtual bool	OnEncoderTurned (uint16_t encoderID, int16_t turns, uint16_t stepsPerRevolution)

virtual bool	OnMenuEncoderActivityChanged (bool isCurrentlyActive)

virtual bool	OnValueEncoderActivityChanged (bool isCurrentlyActive)

virtual bool	OnEncoderActivityChanged (uint16_t encoderID, bool isCurrentlyActive)

virtual bool	OnPotMoved (uint16_t potID, float newPosition)

virtual bool	OnValuePotActivityChanged (bool isCurrentlyActive)

virtual bool	OnPotActivityChanged (uint16_t potID, bool isCurrentlyActive)

virtual void	OnHide ()

virtual void	OnFocusGained ()

virtual void	OnFocusLost ()

virtual void	Draw (const UiCanvasDescriptor &canvas)=0

UI *	GetParentUI ()

const UI *	GetParentUI () const

Protected Member Functions
void	Init (const ItemConfig *items, uint16_t numItems, Orientation orientation, bool allowEntering)

bool	IsFunctionButtonDown () const

Protected Attributes
Orientation	orientation_ = Orientation::upDownSelectLeftRightModify

const ItemConfig *	items_ = nullptr

uint16_t	numItems_ = 0

int16_t	selectedItemIdx_ = -1

bool	allowEntering_ = true

bool	isEditing_ = false

Member Enumeration Documentation

◆ ItemType

enum class daisy::AbstractMenu::ItemType

strong

The types of entries that can be added to the menu.

Enumerator
callbackFunctionItem	Displays a text and calls a callback function when activated with the enter button
checkboxItem	Displays a name and a checkbox. When selected, the modify keys will allow to change the value directly. Pressing the enter button toggles the value.
valueItem	Displays a name and a value (with unit) from a MappedValue. When selected, the modify keys will allow to change the value directly. Pressing the enter button allows to change the value with the selection buttons as well.
openUiPageItem	Displays a name and opens another UiPage when selected.
closeMenuItem	Displays a text and closes the menu page when selected. This is useful when no cancel button is available to close a menu and return to the page below.
customItem	A custom item. See also CustomItem

◆ Orientation

enum class daisy::AbstractMenu::Orientation

strong

Controls which buttons are used to navigate back and forth between the menu items (selection buttons) and which buttons can be used to modify their value directly without pressing the enter button first (modify buttons; these don't have to be available).

See also: AbstractMenuPage

Enumerator
leftRightSelectUpDownModify	left/right buttons => selection buttons, up/down => value buttons
upDownSelectLeftRightModify	up/down buttons => selection buttons, left/right => value buttons

Constructor & Destructor Documentation

◆ AbstractMenu()

daisy::AbstractMenu::AbstractMenu ( )

default

◆ ~AbstractMenu()

virtual daisy::AbstractMenu::~AbstractMenu ( )

inlineoverridevirtual

Member Function Documentation

◆ GetItem()

const ItemConfig & daisy::AbstractMenu::GetItem ( uint16_t itemIdx ) const

inline

◆ GetNumItems()

uint16_t daisy::AbstractMenu::GetNumItems ( ) const

inline

◆ GetSelectedItemIdx()

int16_t daisy::AbstractMenu::GetSelectedItemIdx ( ) const

inline

◆ Init()

void daisy::AbstractMenu::Init	(	const ItemConfig *	items,
		uint16_t	numItems,
		Orientation	orientation,
		bool	allowEntering
	)

protected

Call this from your child class to initialize the menu. It's okay to re-initialize an AbstractMene multiple times, even while it's displayed on the UI.

Parameters

items	An array of ItemConfig that determine which items are available in the menu.
numItems	The number of items in the `items` array.
orientation	Controls which pair of arrow buttons are used for selection / editing
allowEntering	Globally controls if the Ok button can enter items for editing. If you have a physical controls that can edit selected items directly (value slider, a second arrow button pair, value encoder) you can set this to false, otherwise you set it to true so that the controls used for selecting items can now also be used to edit the values.

◆ IsFunctionButtonDown()

bool daisy::AbstractMenu::IsFunctionButtonDown ( ) const

inlineprotected

Returns the state of the function button.

◆ OnArrowButton()

bool daisy::AbstractMenu::OnArrowButton	(	ArrowButtonType	arrowType,
		uint8_t	numberOfPresses,
		bool	isRetriggering
	)

overridevirtual

Called when an arrow button is pressed or released.

Parameters

arrowType	The arrow button affected.
numberOfPresses	Holds the number of successive button presses. It will be 1 on the first call and increasing by 1 with each successive call. A button down event is signaled by numberOfButtonPresses == 0.
isRetriggering	True if the button is auto-retriggering (due to being held down)

Returns: false, if you want the event to be passed on to the page below.

Reimplemented from daisy::UiPage.

◆ OnCancelButton()

bool daisy::AbstractMenu::OnCancelButton	(	uint8_t	numberOfPresses,
		bool	isRetriggering
	)

overridevirtual

Called when the cancel button is pressed or released.

Parameters

numberOfPresses	Holds the number of successive button presses. It will be 1 on the first call and increasing by 1 with each successive call. A button down event is signaled by numberOfButtonPresses == 0.
isRetriggering	True if the button is auto-retriggering (due to being held down)

Returns: false, if you want the event to be passed on to the page below.

Reimplemented from daisy::UiPage.

◆ OnFunctionButton()

bool daisy::AbstractMenu::OnFunctionButton	(	uint8_t	numberOfPresses,
		bool	isRetriggering
	)

overridevirtual

Called when the function button is pressed or released.

Parameters

numberOfPresses	Holds the number of successive button presses. It will be 1 on the first call and increasing by 1 with each successive call. A button down event is signaled by numberOfButtonPresses == 0.
isRetriggering	True if the button is auto-retriggering (due to being held down)

Returns: false, if you want the event to be passed on to the page below.

Reimplemented from daisy::UiPage.

◆ OnMenuEncoderTurned()

bool daisy::AbstractMenu::OnMenuEncoderTurned	(	int16_t	turns,
		uint16_t	stepsPerRevolution
	)

overridevirtual

Called when the menu encoder is turned.

Parameters

turns	The number of increments, positive is clockwise.
stepsPerRevolution	The total number of increments per revolution on this encoder.

Returns: false, if you want the event to be passed on to the page below.

Reimplemented from daisy::UiPage.

◆ OnOkayButton()

bool daisy::AbstractMenu::OnOkayButton	(	uint8_t	numberOfPresses,
		bool	isRetriggering
	)

overridevirtual

Called when the okay button is pressed or released.

Parameters

numberOfPresses	Holds the number of successive button presses. It will be 1 on the first call and increasing by 1 with each successive call. A button down event is signaled by numberOfButtonPresses == 0.
isRetriggering	True if the button is auto-retriggering (due to being held down)

Returns: false, if you want the event to be passed on to the page below.

Reimplemented from daisy::UiPage.

◆ OnShow()

void daisy::AbstractMenu::OnShow ( )

overridevirtual

Called when the page is added to the UI.

Reimplemented from daisy::UiPage.

◆ OnValueEncoderTurned()

bool daisy::AbstractMenu::OnValueEncoderTurned	(	int16_t	turns,
		uint16_t	stepsPerRevolution
	)

overridevirtual

Called when the menu encoder is turned.

Parameters

turns	The number of increments, positive is clockwise.
stepsPerRevolution	The total number of increments per revolution on this encoder.

Returns: false, if you want the event to be passed on to the page below.

Reimplemented from daisy::UiPage.

◆ OnValuePotMoved()

bool daisy::AbstractMenu::OnValuePotMoved ( float newPosition )

overridevirtual

Called when the value potentiometer is turned.

Parameters

newPosition The new position in the range 0 .. 1

Returns: false, if you want the event to be passed on to the page below.

Reimplemented from daisy::UiPage.

◆ SelectItem()

void daisy::AbstractMenu::SelectItem ( uint16_t itemIdx )

Member Data Documentation

◆ allowEntering_

bool daisy::AbstractMenu::allowEntering_ = true

protected

If true, the menu allows "entering" an item to modify its value with the encoder / selection buttons.

◆ isEditing_

bool daisy::AbstractMenu::isEditing_ = false

protected

If true, the currently selected item index is "entered" so that it can be edited with the encoder/ selection buttons.

◆ items_

const ItemConfig* daisy::AbstractMenu::items_ = nullptr

protected

A list of items to include in the menu.

◆ numItems_

uint16_t daisy::AbstractMenu::numItems_ = 0

protected

The number of items in items_

◆ orientation_

Orientation daisy::AbstractMenu::orientation_ = Orientation::upDownSelectLeftRightModify

protected

The orientation of the menu. This is used to determine which function the arrow keys will be assigned to.

◆ selectedItemIdx_

int16_t daisy::AbstractMenu::selectedItemIdx_ = -1

protected

The currently selected item index

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

src/ui/AbstractMenu.h

Detailed Description

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Member Enumeration Documentation

◆ ItemType

◆ Orientation

Constructor & Destructor Documentation

◆ AbstractMenu()

◆ ~AbstractMenu()

Member Function Documentation

◆ GetItem()

◆ GetNumItems()

◆ GetSelectedItemIdx()

◆ Init()

◆ IsFunctionButtonDown()

◆ OnArrowButton()

◆ OnCancelButton()

◆ OnFunctionButton()

◆ OnMenuEncoderTurned()

◆ OnOkayButton()

◆ OnShow()

◆ OnValueEncoderTurned()

◆ OnValuePotMoved()

◆ SelectItem()

Member Data Documentation

◆ allowEntering_

◆ isEditing_

◆ items_

◆ numItems_

◆ orientation_

◆ selectedItemIdx_