Stores the data that defines a menu and provides thread-safe access to that data. More...

#include <Menu.hpp>

Inheritance diagram for duds::ui::menu::Menu:

Collaboration diagram for duds::ui::menu::Menu:

Public Types
typedef std::vector< std::shared_ptr< MenuItem > >	ItemVec
	The type that holds the menu's items. More...

typedef std::map< MenuView *, std::weak_ptr< MenuView > >	ViewMap
	Container type used to track views of the menu. More...

Public Member Functions
	Menu (std::size_t reserve=0)
	Construct a new menu. More...

	Menu (const std::string &title, std::size_t reserve=0)
	Construct a new menu. More...

bool	empty () const
	True if the menu has no items. More...

bool	haveToggles () const
	True if the menu has at least one MenuItem that is a toggle. More...

std::size_t	invisible () const
	Returns the number of MenuItem objects flagged as invisible in the menu. More...

std::size_t	size () const
	Returns the number of MenuItem objects in the menu. More...

const std::string &	title () const
	Returns the title of the menu. More...

int	updateIndex () const
	Returns a number that is incremented every time the menu is changed. More...

std::size_t	visible () const
	Returns the number of visible MenuItem objects in the menu. More...

Static Public Member Functions
static std::shared_ptr< Menu >	make (std::size_t reserve=0)
	Makes a new menu that is managed by a std::shared_ptr. More...

static std::shared_ptr< Menu >	make (const std::string &title, std::size_t reserve=0)
	Makes a new menu that is managed by a std::shared_ptr. More...

Private Member Functions
void	addView (const std::shared_ptr< MenuView > &view)
	Stores a weak reference to the given view for the purpose of informing the view of any item insertions and deletions. More...

void	append (std::shared_ptr< MenuItem > &&mi)
	Appends a new item to the end of the menu. More...

void	append (const std::shared_ptr< MenuItem > &mi)
	Appends a new item to the end of the menu. More...

ItemVec::const_iterator	cbegin () const
	Returns the begin iterator for the contained MenuItem objects. More...

ItemVec::const_iterator	cend () const
	Returns the end iterator for the contained MenuItem objects. More...

void	clear () noexcept
	Removes all items from the menu. More...

void	exclusiveLock ()
	Performs a recursive exclusive lock on block. More...

void	exclusiveUnlock ()
	Performs a recursive exclusive unlock on block. More...

void	informViews (void(MenuView::*eventFunc)(std::size_t), std::size_t idx)
	Calls a function on each view using this menu, and provides the index of a menu item. More...

void	insert (std::size_t index, std::shared_ptr< MenuItem > &&mi)
	Inserts a new item into the menu. More...

void	insert (std::size_t index, const std::shared_ptr< MenuItem > &mi)
	Inserts a new item into the menu. More...

ItemVec::const_iterator	iterator (std::size_t index) const
	Returns an iterator to the MenuItem object at the given position. More...

void	remove (const std::shared_ptr< MenuItem > &mi)
	Removes an item from the menu. More...

void	remove (std::size_t index)
	Removes an item from the menu. More...

void	title (const std::string &newTitle) noexcept
	Change the title of the menu. More...

Private Attributes
std::shared_timed_mutex	block
	Used to enable thread-safe operations. More...

std::size_t	invis
	The number of items that are currently flagged as invisible. More...

ItemVec	items
	The store of menu items for the menu. More...

std::string	lbl
	The menu's name; optional. More...

int	lockCnt
	The number of exclusive locks held by the thread indicated by lockOwner. More...

std::thread::id	lockOwner
	Used with block to implement recursive locking. More...

friend	MenuAccess

friend	MenuItem

friend	MenuOutput

friend	MenuOutputAccess

friend	MenuView

std::size_t	toggles
	The number of items that are toggles. More...

int	updateIdx
	This value is incremented every time the menu is changed. More...

ViewMap	views
	The views; used to inform the views that menu items have been added or removed. More...

Detailed Description

Stores the data that defines a menu and provides thread-safe access to that data.

Modifying the menu is done through a MenuAccess object which obtains an exclusive and recursive lock on the menu's data.

See the Menu page for how this relates to the rest of the menu system.

Author: Jeff Jackowski

Definition at line 45 of file Menu.hpp.

Member Typedef Documentation

◆ ItemVec

typedef std::vector< std::shared_ptr<MenuItem> > duds::ui::menu::Menu::ItemVec

The type that holds the menu's items.

Definition at line 50 of file Menu.hpp.

◆ ViewMap

typedef std::map< MenuView*, std::weak_ptr<MenuView> > duds::ui::menu::Menu::ViewMap

Container type used to track views of the menu.

Definition at line 54 of file Menu.hpp.

Constructor & Destructor Documentation

◆ Menu() [1/2]

duds::ui::menu::Menu::Menu ( std::size_t reserve = 0 )

Construct a new menu.

Note: The menu object must be managed by a std::shared_ptr.

Parameters

reserve The size to reserve in the vector of menu items.

See also: make(std::size_t)

Definition at line 18 of file Menu.cpp.

◆ Menu() [2/2]

duds::ui::menu::Menu::Menu	(	const std::string &	title,
		std::size_t	reserve = `0`
	)

Construct a new menu.

Note: The menu object must be managed by a std::shared_ptr.

Parameters

title	The optional name of the menu.
reserve	The size to reserve in the vector of menu items.

See also: make(const std::string &title, std::size_t)

Definition at line 23 of file Menu.cpp.

Member Function Documentation

◆ addView()

void duds::ui::menu::Menu::addView ( const std::shared_ptr< MenuView > & view )

private

Stores a weak reference to the given view for the purpose of informing the view of any item insertions and deletions.

Parameters

view	The view to store.

Definition at line 87 of file Menu.cpp.

Referenced by haveToggles().

◆ append() [1/2]

void duds::ui::menu::Menu::append ( std::shared_ptr< MenuItem > && mi )

private

Appends a new item to the end of the menu.

Parameters

mi	The menu item to add. It will be moved into an internal vector.

Exceptions

MenuNoItemError An attempt was made to add nothing.

Definition at line 114 of file Menu.cpp.

Referenced by duds::ui::menu::MenuAccess::append(), append(), and cend().

◆ append() [2/2]

void duds::ui::menu::Menu::append ( const std::shared_ptr< MenuItem > & mi )

private

Appends a new item to the end of the menu.

Parameters

mi	The menu item to add.

Exceptions

MenuNoItemError An attempt was made to add nothing.

Definition at line 134 of file Menu.cpp.

◆ cbegin()

ItemVec::const_iterator duds::ui::menu::Menu::cbegin ( ) const

inlineprivate

Returns the begin iterator for the contained MenuItem objects.

Definition at line 220 of file Menu.hpp.

◆ cend()

ItemVec::const_iterator duds::ui::menu::Menu::cend ( ) const

inlineprivate

Returns the end iterator for the contained MenuItem objects.

Definition at line 226 of file Menu.hpp.

◆ clear()

void duds::ui::menu::Menu::clear ( )

privatenoexcept

Removes all items from the menu.

Definition at line 64 of file Menu.cpp.

Referenced by cend(), and duds::ui::menu::MenuAccess::clear().

◆ empty()

bool duds::ui::menu::Menu::empty ( ) const

inline

True if the menu has no items.

Definition at line 168 of file Menu.hpp.

◆ exclusiveLock()

void duds::ui::menu::Menu::exclusiveLock ( )

private

Performs a recursive exclusive lock on block.

Definition at line 28 of file Menu.cpp.

Referenced by addView(), duds::ui::menu::MenuItem::changeEnabledState(), duds::ui::menu::MenuItem::changeToggle(), duds::ui::menu::MenuItem::changeVisibility(), duds::ui::menu::MenuItem::description(), haveToggles(), duds::ui::menu::MenuItem::label(), duds::ui::menu::MenuAccess::MenuAccess(), duds::ui::menu::MenuItem::remove(), duds::ui::menu::MenuItem::toggle(), and duds::ui::menu::MenuItem::value().

◆ exclusiveUnlock()

void duds::ui::menu::Menu::exclusiveUnlock ( )

private

Performs a recursive exclusive unlock on block.

Definition at line 41 of file Menu.cpp.

Referenced by addView(), duds::ui::menu::MenuItem::changeEnabledState(), duds::ui::menu::MenuItem::changeToggle(), duds::ui::menu::MenuItem::changeVisibility(), duds::ui::menu::MenuItem::description(), haveToggles(), duds::ui::menu::MenuItem::label(), duds::ui::menu::MenuItem::remove(), duds::ui::menu::MenuAccess::retire(), duds::ui::menu::MenuItem::toggle(), and duds::ui::menu::MenuItem::value().

◆ haveToggles()

bool duds::ui::menu::Menu::haveToggles ( ) const

inline

True if the menu has at least one MenuItem that is a toggle.

Definition at line 180 of file Menu.hpp.

Referenced by duds::ui::menu::MenuAccess::haveToggles(), and duds::ui::menu::MenuOutputAccess::haveToggles().

◆ informViews()

void duds::ui::menu::Menu::informViews	(	void(MenuView::*)(std::size_t)	eventFunc,
		std::size_t	idx
	)

private

Calls a function on each view using this menu, and provides the index of a menu item.

This is used to tell the views when an item is added or removed. Views that no longer exist will be removed from the internal data structure views while iterating over it.

Precondition: An exclusive lock on the menu.

Parameters

eventFunc	The function to call on each view object.
idx	The index of the menu item in question.

Definition at line 93 of file Menu.cpp.

Referenced by haveToggles(), insert(), and remove().

◆ insert() [1/2]

void duds::ui::menu::Menu::insert	(	std::size_t	index,
		std::shared_ptr< MenuItem > &&	mi
	)

private

Inserts a new item into the menu.

Parameters

index	The location where the item will go.
mi	The menu item to insert. It will be moved into an internal vector.

Exceptions

MenuNoItemError	An attempt was made to insert nothing.
MenuBoundsError	The insertion location is beyond the bounds of the menu.

Definition at line 141 of file Menu.cpp.

Referenced by cend(), duds::ui::menu::MenuAccess::insert(), and insert().

◆ insert() [2/2]

void duds::ui::menu::Menu::insert	(	std::size_t	index,
		const std::shared_ptr< MenuItem > &	mi
	)

private

Inserts a new item into the menu.

Parameters

index	The location where the item will go.
mi	The menu item to insert.

Exceptions

MenuNoItemError	An attempt was made to insert nothing.
MenuBoundsError	The insertion location is beyond the bounds of the menu.

Definition at line 172 of file Menu.cpp.

◆ invisible()

std::size_t duds::ui::menu::Menu::invisible ( ) const

inline

Returns the number of MenuItem objects flagged as invisible in the menu.

Definition at line 156 of file Menu.hpp.

◆ iterator()

Menu::ItemVec::const_iterator duds::ui::menu::Menu::iterator ( std::size_t index ) const

private

Returns an iterator to the MenuItem object at the given position.

This requires either an exclusive or a shared lock on the menu. The lock will ensure the return value is good while avoiding the need to create a new shared_ptr object.

Parameters

index The position of the menu item to return.

Exceptions

MenuBoundsError The index is beyond the bounds of this menu.

Definition at line 53 of file Menu.cpp.

Referenced by haveToggles(), duds::ui::menu::MenuAccess::item(), and duds::ui::menu::MenuOutputAccess::item().

◆ make() [1/2]

static std::shared_ptr<Menu> duds::ui::menu::Menu::make ( std::size_t reserve = 0 )

inlinestatic

Makes a new menu that is managed by a std::shared_ptr.

Parameters

reserve The size to reserve in the vector of menu items.

Returns: A shared pointer with the new menu.

Examples:: bppmenu.cpp.

Definition at line 124 of file Menu.hpp.

◆ make() [2/2]

static std::shared_ptr<Menu> duds::ui::menu::Menu::make	(	const std::string &	title,
		std::size_t	reserve = `0`
	)

inlinestatic

Makes a new menu that is managed by a std::shared_ptr.

Parameters

title	The optional name of the menu.
reserve	The size to reserve in the vector of menu items.

Returns: A shared pointer with the new menu.

Definition at line 133 of file Menu.hpp.

◆ remove() [1/2]

void duds::ui::menu::Menu::remove ( const std::shared_ptr< MenuItem > & mi )

private

Removes an item from the menu.

Parameters

mi	The menu item to remove.

Exceptions

MenuItemDoesNotExist The MenuItem is not in the menu.

Definition at line 179 of file Menu.cpp.

Referenced by duds::ui::menu::MenuAccess::remove(), and duds::ui::menu::MenuItem::remove().

◆ remove() [2/2]

void duds::ui::menu::Menu::remove ( std::size_t index )

private

Removes an item from the menu.

Parameters

index The position of the menu item to remove.

Exceptions

MenuBoundsError The index is beyond the bounds of this menu.

Definition at line 205 of file Menu.cpp.

◆ size()

std::size_t duds::ui::menu::Menu::size ( ) const

inline

Returns the number of MenuItem objects in the menu.

This includes items that are not visible or disabled.

Definition at line 150 of file Menu.hpp.

Referenced by duds::ui::menu::MenuAccess::size().

◆ title() [1/2]

const std::string& duds::ui::menu::Menu::title ( ) const

inline

Returns the title of the menu.

Since the title is optional, it may be an empty string.

Definition at line 143 of file Menu.hpp.

Referenced by cend(), make(), and duds::ui::menu::MenuAccess::title().

◆ title() [2/2]

void duds::ui::menu::Menu::title ( const std::string & newTitle )

privatenoexcept

Change the title of the menu.

Parameters

newTitle The new title for the menu.

Definition at line 78 of file Menu.cpp.

◆ updateIndex()

int duds::ui::menu::Menu::updateIndex ( ) const

inline

Returns a number that is incremented every time the menu is changed.

Definition at line 174 of file Menu.hpp.

◆ visible()

std::size_t duds::ui::menu::Menu::visible ( ) const

inline

Returns the number of visible MenuItem objects in the menu.

Definition at line 162 of file Menu.hpp.

Member Data Documentation

◆ block

std::shared_timed_mutex duds::ui::menu::Menu::block

private

Used to enable thread-safe operations.

Definition at line 68 of file Menu.hpp.

Referenced by exclusiveLock(), and exclusiveUnlock().

◆ invis

std::size_t duds::ui::menu::Menu::invis

private

The number of items that are currently flagged as invisible.

Used to assist working out the number of items to show in a menu view.

Definition at line 81 of file Menu.hpp.

Referenced by append(), duds::ui::menu::MenuItem::changeVisibility(), clear(), insert(), invisible(), and visible().

◆ items

ItemVec duds::ui::menu::Menu::items

private

The store of menu items for the menu.

Definition at line 59 of file Menu.hpp.

Referenced by append(), clear(), insert(), iterator(), Menu(), and remove().

◆ lbl

std::string duds::ui::menu::Menu::lbl

private

The menu's name; optional.

Definition at line 76 of file Menu.hpp.

Referenced by title().

◆ lockCnt

int duds::ui::menu::Menu::lockCnt

private

The number of exclusive locks held by the thread indicated by lockOwner.

Used to implement recusrive locking.

Definition at line 90 of file Menu.hpp.

Referenced by append(), clear(), exclusiveLock(), exclusiveUnlock(), insert(), remove(), and title().

◆ lockOwner

std::thread::id duds::ui::menu::Menu::lockOwner

private

Used with block to implement recursive locking.

Definition at line 72 of file Menu.hpp.

Referenced by append(), clear(), exclusiveLock(), exclusiveUnlock(), insert(), remove(), and title().

◆ MenuAccess

friend duds::ui::menu::Menu::MenuAccess

private

Definition at line 98 of file Menu.hpp.

◆ MenuItem

friend duds::ui::menu::Menu::MenuItem

private

Definition at line 99 of file Menu.hpp.

◆ MenuOutput

friend duds::ui::menu::Menu::MenuOutput

private

Definition at line 100 of file Menu.hpp.

◆ MenuOutputAccess

friend duds::ui::menu::Menu::MenuOutputAccess

private

Definition at line 101 of file Menu.hpp.

◆ MenuView

friend duds::ui::menu::Menu::MenuView

private

Definition at line 102 of file Menu.hpp.

◆ toggles

std::size_t duds::ui::menu::Menu::toggles

private

The number of items that are toggles.

Definition at line 85 of file Menu.hpp.

Referenced by append(), clear(), and insert().

◆ updateIdx

int duds::ui::menu::Menu::updateIdx

private

This value is incremented every time the menu is changed.

It is used to tell when a MenuOutput needs to be re-rendered to show an up-to-date menu. This value should only be changed by a thread with an exclusive lock on block.

Definition at line 97 of file Menu.hpp.

Referenced by append(), duds::ui::menu::MenuItem::changeEnabledState(), duds::ui::menu::MenuItem::changeToggle(), duds::ui::menu::MenuItem::changeVisibility(), clear(), duds::ui::menu::MenuItem::description(), insert(), duds::ui::menu::MenuItem::label(), remove(), title(), duds::ui::menu::MenuItem::toggle(), updateIndex(), and duds::ui::menu::MenuItem::value().

◆ views

ViewMap duds::ui::menu::Menu::views

private

The views; used to inform the views that menu items have been added or removed.

Definition at line 64 of file Menu.hpp.

Referenced by addView(), and informViews().

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

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ ItemVec

◆ ViewMap

Constructor & Destructor Documentation

◆ Menu() [1/2]

◆ Menu() [2/2]

Member Function Documentation

◆ addView()

◆ append() [1/2]

◆ append() [2/2]

◆ cbegin()

◆ cend()

◆ clear()

◆ empty()

◆ exclusiveLock()

◆ exclusiveUnlock()

◆ haveToggles()

◆ informViews()

◆ insert() [1/2]

◆ insert() [2/2]

◆ invisible()

◆ iterator()

◆ make() [1/2]

◆ make() [2/2]

◆ remove() [1/2]

◆ remove() [2/2]

◆ size()

◆ title() [1/2]

◆ title() [2/2]

◆ updateIndex()

◆ visible()

Member Data Documentation

◆ block

◆ invis

◆ items

◆ lbl

◆ lockCnt

◆ lockOwner

◆ MenuAccess

◆ MenuItem

◆ MenuOutput

◆ MenuOutputAccess

◆ MenuView

◆ toggles

◆ updateIdx

◆ views