Compiles a list of visible menu items based on the selected item of a MenuView. More...

#include <MenuOutput.hpp>

Collaboration diagram for duds::ui::menu::MenuOutput:

Public Member Functions
	MenuOutput ()=default
	Constructs a menu output without a view. More...

	MenuOutput (const std::shared_ptr< MenuView > &view, int vis)
	Constructs a new output for a given menu view that will start with a specified maximum number of visible items. More...

void	attach (const std::shared_ptr< MenuView > &view, int vis=0)
	Attaches this object to the given MenuView. More...

const std::shared_ptr< Menu > &	menu () const
	Returns the Menu used by this output view. More...

const std::shared_ptr< MenuView > &	view () const
	Returns the MenuView used by this output view. More...

Static Public Member Functions
static std::shared_ptr< MenuOutput >	make (const std::shared_ptr< MenuView > &view, int vis)
	Makes a new output view for a given menu that will start with a specified maximum number of visible items, and returns a std::shared_ptr that will manage its memory. More...

Private Member Functions
bool	changed () const
	True if the view has changed. More...

bool	fore (Menu::ItemVec::const_iterator &iter)
	A helper function for update() that moves iter towards the front of the menu until it finds a visible menu item or the start of the menu. More...

void	lock (std::size_t newRange)
	Handles several tasks to lock and prepare menu data. More...

void	maxVisible (std::size_t newRange)
	Changes the maximum number of visible menu items and causes the visible list to be regenerated. More...

bool	revr (Menu::ItemVec::const_iterator &iter)
	A helper function for update() that moves iter towards the back of the menu until it finds a visible menu item or the end of the menu. More...

void	unlock ()
	Informs the MenuView that it has one fewer MenuOutput objects acting upon it, and releases the shared lock on the menu data. More...

void	updateVisible ()
	Updates which items should be visible. More...

Private Attributes
std::size_t	firstIdx
	Index of the first menu item that is visible. More...

MenuVisibleList	items
	The currently visible menu items. More...

std::size_t	lastIdx
	Index of the last menu item that is visible. More...

friend	MenuOutputAccess

std::shared_ptr< MenuView >	mview
	The menu view handling the selected menu item. More...

std::size_t	range = 1
	The maximum number of visible items. More...

std::size_t	selected = 0
	Index of the selected item from the container of all menu items. More...

std::size_t	selectedVis
	Index of the selected item within the list of currently visible menu items. More...

MenuVisibleList::const_iterator	seliter
	Iterator to the currently selected item. More...

bool	showFirst
	True if the visible list includes the first visible item on the menu. More...

bool	showLast
	True if the visible list includes the last visible item on the menu. More...

int	updateIdx = -1
	The menu's update index value when this subview was last rendered. More...

bool	vchg
	True when the view has changed since the last access, and false otherwise. More...

Detailed Description

Compiles a list of visible menu items based on the selected item of a MenuView.

The visible items are queried from a MenuOutputAccess object. MenuOutputAccess handles locking and unlocking the required data. This class holds more persistent data, and allows reuse of the visible list when no changes have occurred.

Updating a MenuView and output views requires the MenuView to have a brief exclusive lock on the menu data. After the update, a shared lock on the menu data is maintained by the output view while it is in use. This prevents a MenuView object from being used at the same time by multiple MenuOutput objects on the same thread. The deadlock can be avoided by having only one MenuOutputAccess object on the stack at the same time. Technically, two on the satck will work if they use different MenuView objects even if they use the same menu, but this shouldn't be required to make anything work.

Author: Jeff Jackowski

Definition at line 45 of file MenuOutput.hpp.

Constructor & Destructor Documentation

◆ MenuOutput() [1/2]

duds::ui::menu::MenuOutput::MenuOutput ( )

default

Constructs a menu output without a view.

Before this object can be used, attach() must be called.

◆ MenuOutput() [2/2]

duds::ui::menu::MenuOutput::MenuOutput	(	const std::shared_ptr< MenuView > &	view,
		int	vis
	)

Constructs a new output for a given menu view that will start with a specified maximum number of visible items.

Note: MenuOutput objects must be managed by std::shared_ptr.

Parameters

view	The MenuView that will feed this output.
vis	The initial maximum number of visible menu items.

See also: make()

Definition at line 17 of file MenuOutput.cpp.

Member Function Documentation

◆ attach()

void duds::ui::menu::MenuOutput::attach	(	const std::shared_ptr< MenuView > &	view,
		int	vis = `0`
	)

Attaches this object to the given MenuView.

The object may be re-attached to different MenuView objects during its lifetime.

Precondition: A MenuOutputAccess object is not currently acting upon this object.

Parameters

view	The MenuView that will feed this output.
vis	The maximum number of visible menu items, or 0 for no change. If this object has not yet been attached to a view and 0 is specified, a value of 1 will be used.

Definition at line 20 of file MenuOutput.cpp.

Referenced by make().

◆ changed()

bool duds::ui::menu::MenuOutput::changed ( ) const

inlineprivate

True if the view has changed.

Precondition: A MenuOutputAccess object is acting upon this object. This will cause the selected item to be updated, and updateVisible() will record if a change occurred.

Definition at line 170 of file MenuOutput.hpp.

Referenced by duds::ui::menu::MenuOutputAccess::changed().

◆ fore()

bool duds::ui::menu::MenuOutput::fore ( Menu::ItemVec::const_iterator & iter )

private

A helper function for update() that moves iter towards the front of the menu until it finds a visible menu item or the start of the menu.

Parameters

iter	The location to start the search.

Returns: True if a visible item was found, or false if there isn't an item in the forward direction that is visble.

Definition at line 72 of file MenuOutput.cpp.

Referenced by updateVisible().

◆ lock()

void duds::ui::menu::MenuOutput::lock ( std::size_t newRange )

private

Handles several tasks to lock and prepare menu data.

Calls MenuView::update() to conditionally update the view with any changes to the menu. If the view does update with new data, it requires an exclusive lock from the Menu. The lock is released by the end of the function.
Gets a shared lock on the menu data.
If a different range is requested, store the new range and force an update of the list of visible items.
Produce a list of the MenuItem objects that are visible.

Parameters

newRange The number of menu items that can be displayed, or -1 to not change the range.

Definition at line 39 of file MenuOutput.cpp.

Referenced by duds::ui::menu::MenuOutputAccess::MenuOutputAccess().

◆ make()

static std::shared_ptr<MenuOutput> duds::ui::menu::MenuOutput::make	(	const std::shared_ptr< MenuView > &	view,
		int	vis
	)

inlinestatic

Makes a new output view for a given menu that will start with a specified maximum number of visible items, and returns a std::shared_ptr that will manage its memory.

Parameters

view	The MenuView that will feed this output.
vis	The initial maximum number of visible menu items.

Definition at line 196 of file MenuOutput.hpp.

◆ maxVisible()

void duds::ui::menu::MenuOutput::maxVisible ( std::size_t newRange )

private

Changes the maximum number of visible menu items and causes the visible list to be regenerated.

Warning: Any visible list iterators obtained from other member functions must be considered invalid immediately following a call to this function.

Parameters

newRange The number of menu items that can be displayed.

Definition at line 61 of file MenuOutput.cpp.

Referenced by duds::ui::menu::MenuOutputAccess::maxVisible().

◆ menu()

const std::shared_ptr< Menu > & duds::ui::menu::MenuOutput::menu ( ) const

Returns the Menu used by this output view.

Exceptions

MenuOutputNotAttached This object hasn't been attached to a MenuView. This can happen if it is constructed using the default constructor and attach() is not called.

Definition at line 32 of file MenuOutput.cpp.

Referenced by fore(), lock(), duds::ui::menu::MenuOutputAccess::MenuOutputAccess(), revr(), updateVisible(), and view().

◆ revr()

bool duds::ui::menu::MenuOutput::revr ( Menu::ItemVec::const_iterator & iter )

private

A helper function for update() that moves iter towards the back of the menu until it finds a visible menu item or the end of the menu.

Parameters

iter	The location to start the search.

Returns: True if a visible item was found, or false if there isn't an item in the backward direction that is visble.

Definition at line 85 of file MenuOutput.cpp.

Referenced by updateVisible().

◆ unlock()

void duds::ui::menu::MenuOutput::unlock ( )

private

Informs the MenuView that it has one fewer MenuOutput objects acting upon it, and releases the shared lock on the menu data.

Definition at line 56 of file MenuOutput.cpp.

Referenced by duds::ui::menu::MenuOutputAccess::retire().

◆ updateVisible()

void duds::ui::menu::MenuOutput::updateVisible ( )

private

Updates which items should be visible.

If an even number of items are visible, an additional item will be in the direction of the last change from the selected item so that the user will see more items ahead of the change.

Precondition: mview's MenuView::block is locked by the calling thread.

Postcondition: The values in first and last will be updated, and updateIdx will match the value from the parent Menu.

Definition at line 98 of file MenuOutput.cpp.

Referenced by lock(), and maxVisible().

◆ view()

const std::shared_ptr<MenuView>& duds::ui::menu::MenuOutput::view ( ) const

inline

Returns the MenuView used by this output view.

Definition at line 215 of file MenuOutput.hpp.

Referenced by attach(), and make().

Member Data Documentation

◆ firstIdx

std::size_t duds::ui::menu::MenuOutput::firstIdx

private

Index of the first menu item that is visible.

Definition at line 77 of file MenuOutput.hpp.

Referenced by duds::ui::menu::MenuOutputAccess::firstIndex(), and updateVisible().

◆ items

MenuVisibleList duds::ui::menu::MenuOutput::items

private

The currently visible menu items.

This data is only guarenteed to be valid while a MenuOutputAccess object is acting upon this MenuOutput. The data may or may not remain valid between accesses. The locks caused by the access object include a shared lock on the menu, which is why shared pointers are not needed here.

Definition at line 58 of file MenuOutput.hpp.

Referenced by attach(), duds::ui::menu::MenuOutputAccess::begin(), duds::ui::menu::MenuOutputAccess::empty(), duds::ui::menu::MenuOutputAccess::end(), duds::ui::menu::MenuOutputAccess::MenuOutputAccess(), duds::ui::menu::MenuOutputAccess::showingAll(), duds::ui::menu::MenuOutputAccess::size(), and updateVisible().

◆ lastIdx

std::size_t duds::ui::menu::MenuOutput::lastIdx

private

Index of the last menu item that is visible.

Definition at line 81 of file MenuOutput.hpp.

Referenced by duds::ui::menu::MenuOutputAccess::lastIndex(), and updateVisible().

◆ MenuOutputAccess

friend duds::ui::menu::MenuOutput::MenuOutputAccess

private

Definition at line 173 of file MenuOutput.hpp.

◆ mview

std::shared_ptr<MenuView> duds::ui::menu::MenuOutput::mview

private

The menu view handling the selected menu item.

Definition at line 50 of file MenuOutput.hpp.

Referenced by attach(), lock(), menu(), unlock(), updateVisible(), and view().

◆ range

std::size_t duds::ui::menu::MenuOutput::range = 1

private

The maximum number of visible items.

Definition at line 85 of file MenuOutput.hpp.

Referenced by attach(), lock(), duds::ui::menu::MenuOutputAccess::maxVisible(), maxVisible(), and updateVisible().

◆ selected

std::size_t duds::ui::menu::MenuOutput::selected = 0

private

Index of the selected item from the container of all menu items.

When a MenuOutputAccess is operating upon this object, it is the currently selected item. Otherwise it is the previously selected item.

Definition at line 91 of file MenuOutput.hpp.

Referenced by duds::ui::menu::MenuOutputAccess::selectedIndex(), and updateVisible().

◆ selectedVis

std::size_t duds::ui::menu::MenuOutput::selectedVis

private

Index of the selected item within the list of currently visible menu items.

When a MenuOutputAccess is not operating upon this object, this value has no meaning. Otherwise, it is the number of items from the first in the visible list to the selected item. If the menu is empty, this value should not be used.

Definition at line 73 of file MenuOutput.hpp.

Referenced by duds::ui::menu::MenuOutputAccess::selectedVisible(), and updateVisible().

◆ seliter

MenuVisibleList::const_iterator duds::ui::menu::MenuOutput::seliter

private

Iterator to the currently selected item.

It will be the end iterator only if no item is selected. A view of a menu with at least one item will have a selected item when a MenuOutputAccess object is operating on the view.

Definition at line 65 of file MenuOutput.hpp.

Referenced by duds::ui::menu::MenuOutputAccess::selectedItem(), duds::ui::menu::MenuOutputAccess::selectedIter(), and updateVisible().

◆ showFirst

bool duds::ui::menu::MenuOutput::showFirst

private

True if the visible list includes the first visible item on the menu.

Definition at line 104 of file MenuOutput.hpp.

Referenced by duds::ui::menu::MenuOutputAccess::showingAll(), duds::ui::menu::MenuOutputAccess::showingFirst(), and updateVisible().

◆ showLast

bool duds::ui::menu::MenuOutput::showLast

private

True if the visible list includes the last visible item on the menu.

Definition at line 108 of file MenuOutput.hpp.

Referenced by duds::ui::menu::MenuOutputAccess::showingAll(), duds::ui::menu::MenuOutputAccess::showingLast(), and updateVisible().

◆ updateIdx

int duds::ui::menu::MenuOutput::updateIdx = -1

private

The menu's update index value when this subview was last rendered.

Definition at line 95 of file MenuOutput.hpp.

Referenced by attach(), lock(), maxVisible(), and updateVisible().

◆ vchg

bool duds::ui::menu::MenuOutput::vchg

private

True when the view has changed since the last access, and false otherwise.

Changed in updateVisible().

Definition at line 100 of file MenuOutput.hpp.

Referenced by changed(), and updateVisible().

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

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ MenuOutput() [1/2]

◆ MenuOutput() [2/2]

Member Function Documentation

◆ attach()

◆ changed()

◆ fore()

◆ lock()

◆ make()

◆ maxVisible()

◆ menu()

◆ revr()

◆ unlock()

◆ updateVisible()

◆ view()

Member Data Documentation

◆ firstIdx

◆ items

◆ lastIdx

◆ MenuOutputAccess

◆ mview

◆ range

◆ selected

◆ selectedVis

◆ seliter

◆ showFirst

◆ showLast

◆ updateIdx

◆ vchg