daisy::AbstractMenu¶

Module: LIBDAISY / UI

Base class for complex menus. More...

#include <AbstractMenu.h>

Public Classes¶

	Name
class	CustomItem
struct	ItemConfig

Public Types¶

	Name
enum class	Orientation
enum class	ItemType

Public Functions¶

	Name
	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
virtual bool	OnOkayButton(uint8_t numberOfPresses, bool isRetriggering) override
virtual bool	OnCancelButton(uint8_t numberOfPresses, bool isRetriggering) override
virtual bool	OnArrowButton(ArrowButtonType arrowType, uint8_t numberOfPresses, bool isRetriggering) override
virtual bool	OnFunctionButton(uint8_t numberOfPresses, bool isRetriggering) override
virtual bool	OnMenuEncoderTurned(int16_t turns, uint16_t stepsPerRevolution) override
virtual bool	OnValueEncoderTurned(int16_t turns, uint16_t stepsPerRevolution) override
virtual bool	OnValuePotMoved(float newPosition) override
virtual void	OnShow() override

Protected Functions¶

	Name
void	Init(const ItemConfig * items, uint16_t numItems, Orientation orientation, bool allowEntering)
bool	IsFunctionButtonDown() const

Protected Attributes¶

	Name
Orientation	orientation_
const ItemConfig *	items_
uint16_t	numItems_
int16_t	selectedItemIdx_
bool	allowEntering_
bool	isEditing_

Additional inherited members¶

Public Functions inherited from daisy::UiPage

	Name
	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

Friends inherited from daisy::UiPage

	Name
class	UI

Detailed Description¶

class daisy::AbstractMenu;

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](/libDaisy/Classes/classdaisy_1_1_full_screen_item_menu/)

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](/libDaisy/Classes/classdaisy_1_1_abstract_menu/#enumvalue-leftrightselectupdownmodify), directly edit value of the selected item when [Orientation::upDownSelectLeftRightModify](/libDaisy/Classes/classdaisy_1_1_abstract_menu/#enumvalue-updownselectleftrightmodify).
Up/Down buttons: Select items when [Orientation::upDownSelectLeftRightModify](/libDaisy/Classes/classdaisy_1_1_abstract_menu/#enumvalue-updownselectleftrightmodify), directly edit value of the selected item when [Orientation::leftRightSelectUpDownModify](/libDaisy/Classes/classdaisy_1_1_abstract_menu/#enumvalue-leftrightselectupdownmodify).
Ok button: Activate the action of the selected item (if it has an action, e.g. [ItemType::closeMenuItem](/libDaisy/Classes/classdaisy_1_1_abstract_menu/#enumvalue-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

Public Types Documentation¶

enum Orientation¶

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

See: AbstractMenuPage

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

enum ItemType¶

Enumerator	Value	Description
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.

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

Public Functions Documentation¶

function AbstractMenu¶

AbstractMenu() =default

function ~AbstractMenu¶

inline virtual ~AbstractMenu() override

function GetNumItems¶

inline uint16_t GetNumItems() const

function GetItem¶

inline const ItemConfig & GetItem(
    uint16_t itemIdx
) const

function SelectItem¶

void SelectItem(
    uint16_t itemIdx
)

function GetSelectedItemIdx¶

inline int16_t GetSelectedItemIdx() const

function OnOkayButton¶

virtual bool OnOkayButton(
    uint8_t numberOfPresses,
    bool isRetriggering
) override

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)

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

Reimplements: daisy::UiPage::OnOkayButton

Called when the okay button is pressed or released.

function OnCancelButton¶

virtual bool OnCancelButton(
    uint8_t numberOfPresses,
    bool isRetriggering
) override

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)

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

Reimplements: daisy::UiPage::OnCancelButton

Called when the cancel button is pressed or released.

function OnArrowButton¶

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

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)

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

Reimplements: daisy::UiPage::OnArrowButton

Called when an arrow button is pressed or released.

function OnFunctionButton¶

virtual bool OnFunctionButton(
    uint8_t numberOfPresses,
    bool isRetriggering
) override

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)

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

Reimplements: daisy::UiPage::OnFunctionButton

Called when the function button is pressed or released.

function OnMenuEncoderTurned¶

virtual bool OnMenuEncoderTurned(
    int16_t turns,
    uint16_t stepsPerRevolution
) override

Parameters:

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

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

Reimplements: daisy::UiPage::OnMenuEncoderTurned

Called when the menu encoder is turned.

function OnValueEncoderTurned¶

virtual bool OnValueEncoderTurned(
    int16_t turns,
    uint16_t stepsPerRevolution
) override

Parameters:

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

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

Reimplements: daisy::UiPage::OnValueEncoderTurned

Called when the menu encoder is turned.

function OnValuePotMoved¶

virtual bool OnValuePotMoved(
    float newPosition
) override

Parameters:

newPosition The new position in the range 0 .. 1

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

Reimplements: daisy::UiPage::OnValuePotMoved

Called when the value potentiometer is turned.

function OnShow¶

virtual void OnShow() override

Reimplements: daisy::UiPage::OnShow

Called when the page is added to the UI.

Protected Functions Documentation¶

function Init¶

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

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.

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.

function IsFunctionButtonDown¶

inline bool IsFunctionButtonDown() const

Returns the state of the function button.

Protected Attributes Documentation¶

variable orientation_¶

Orientation orientation_ = Orientation::upDownSelectLeftRightModify;

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

variable items_¶

const ItemConfig * items_ = nullptr;

A list of items to include in the menu.

variable numItems_¶

uint16_t numItems_ = 0;

The number of items in items_

variable selectedItemIdx_¶

int16_t selectedItemIdx_ = -1;

The currently selected item index

variable allowEntering_¶

bool allowEntering_ = true;

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

variable isEditing_¶

bool isEditing_ = false;

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

Updated on 2024-01-03 at 19:41:01 +0000