Represents an option that a user can chose from a menu of options. More...

#include <MenuItem.hpp>

Inheritance diagram for duds::ui::menu::MenuItem:

Collaboration diagram for duds::ui::menu::MenuItem:

Classes
struct	MenuItemToken
	This token is needed to construct MenuItem objects; use to force all objects to be managed by shared pointers. More...

Public Types
typedef duds::general::BitFlags< struct MenuItemFlags >	Flags
	A set of option and state flags for menu items. More...

Public Member Functions
void	changeEnabledState (bool state)
	Changes the state of the item to either enabled or disabled. More...

void	changeToggle (bool state)
	Changes the toggle state of the item to the indicated state. More...

void	changeVisibility (bool vis)
	Changes the visibility of the item. More...

virtual void	chose (MenuView &invokingView, const MenuAccess &access)=0
	Called by MenuView when the user choses this MenuItem. More...

void	clearToggle ()
	Clears the toggle state of the item. More...

const std::string &	description () const
	Returns the optional description text for this item. More...

void	description (const std::string &d)
	Changes the optional description text for this item. More...

virtual void	deselect (MenuView &invokingView, const MenuAccess &access)
	Invoked when the user has selected another item, and before the select() function for that item is invoked. More...

void	disable ()
	Makes the item disabled. More...

void	enable ()
	Makes the item enabled. More...

Flags	flags () const
	Returns the option flags for the item. More...

bool	hasValue () const
	True if the item is flagged as having a value. More...

void	hide ()
	Makes the item invisible. More...

bool	isDisabled () const
	True if the item is flagged as disabled. More...

bool	isEnabled () const
	True if the item is flagged as enabled. More...

bool	isInvisible () const
	True if the item is flagged as invisible. More...

bool	isSelectable () const
	Returns true if the item is both visible and enabled. More...

bool	isToggle () const
	True if the item is flagged as being a toggle. More...

bool	isToggledOn () const
	True if the item is in the toggled on (true) state. More...

bool	isVisible () const
	True if the item is flagged as visible. More...

const std::string &	label () const
	Returns the label text for this item. More...

void	label (const std::string &l)
	Changes the label text for this item. More...

Menu *	menu () const
	Returns the menu object that owns this item. More...

void	remove ()
	Removes the item from its parent menu. More...

virtual void	select (MenuView &invokingView, const MenuAccess &access)
	Invoked when the user has selected, but has not chosen, the item. More...

void	setToggle ()
	Sets the toggle state of the item. More...

void	show ()
	Makes the item visible. More...

bool	toggle ()
	Toggles the toggle state of the item and returns the new toggle state. More...

const std::string &	value () const
	Returns the optional value text for the item. More...

void	value (const std::string &v)
	Changes the optional value text for the item. More...

Static Public Attributes
static constexpr Flags	Disabled = Flags::Bit(0)
	Indicates that the item may not be chosen by the user. More...

static constexpr Flags	HasValue = Flags::Bit(2)
	Indicates that the item has a value, or setting, that should be shown in the menu if possible. More...

static constexpr Flags	Invisible = Flags::Bit(1)
	Indicates that the item will not be rendered. More...

static constexpr Flags	Toggle = Flags::Bit(3)
	Denotes that the item is a toggle, and that the toggle state should be visible on the menu. More...

static constexpr Flags	ToggledOn = Flags::Bit(4)
	The toggle state; true when the state is on, when the item is true. More...

Protected Member Functions
	MenuItem (MenuItemToken, const std::string &label, Flags flags=Flags::Zero())
	Constructs a new MenuItem. More...

	MenuItem (MenuItemToken, const std::string &label, const std::string &description, Flags flags=Flags::Zero())
	Constructs a new MenuItem. More...

	MenuItem (MenuItemToken, const std::string &label, const std::string &description, const std::string &value, Flags flags=Flags::Zero())
	Constructs a new MenuItem with an associated value. More...

	MenuItem (MenuItemToken, const MenuItem &mi)
	Copy constructs a new MenuItem. More...

Private Attributes
std::string	descr
	Additional text that may be shown to provide users with a better idea of what the option does. More...

Flags	flgs
	The item's option flags. More...

std::string	lbl
	The text shown to represent the item. More...

friend	Menu

Menu *	parent = nullptr
	The owning Menu object. More...

std::string	val
	An optional string for the current setting of the item. More...

Detailed Description

Represents an option that a user can chose from a menu of options.

An item may only be added to one Menu.

This is an abstract class to allow implementations to bind an item to whatever the program needs. This can be used to minimize overhead. GenericMenuItem can be used for many cases, but may be cumbersome in cases where it would be helpful for the item to retain additional arbitrary data beyond what this class holds.

Items have the following attributes:

Label: short text presented on the menu as the option.
Description: optional longer text, like a helpful description, that normally is only shown when the item is selected, if shown at all.
Disabled flag: prevents the item from being selected, but does not make it invisible.
Invisible flag: hides the item from view.
Toggle: items can have a toggle state. This is enabled with the Toggle flag.
Value: items can have a string value stored with them. This is intended as an arbitrary setting for the menu item that should be displayed to the user along with the menu. This is enabled with the HasValue flag.

Functions are provided to modify the item's attributes, but the flags, save for the current toggle state (ToggledOn), cannot be changed after construction. Once the item has been added to a menu, these modifications require an exclusive lock on the owning menu. The modification functions will automatically acquire the lock if needed, and the release it afterwards.

If an item is removed from a menu, it may be further modified and added to another menu.

Author: Jeff Jackowski

Definition at line 58 of file MenuItem.hpp.

Member Typedef Documentation

◆ Flags

typedef duds::general::BitFlags<struct MenuItemFlags> duds::ui::menu::MenuItem::Flags

A set of option and state flags for menu items.

Definition at line 63 of file MenuItem.hpp.

Constructor & Destructor Documentation

◆ MenuItem() [1/4]

duds::ui::menu::MenuItem::MenuItem	(	MenuItemToken	,
		const std::string &	label,
		Flags	flags = `Flags::Zero()`
	)

inlineprotected

Constructs a new MenuItem.

Note: All MenuItem objects must be managed by std::shared_ptr.

Parameters

label	Short text presented to the user as the menu item.
flags	The option flags for the item. The default is zero: enabled, visible, no value, and not a toggle.

Definition at line 129 of file MenuItem.hpp.

◆ MenuItem() [2/4]

duds::ui::menu::MenuItem::MenuItem	(	MenuItemToken	,
		const std::string &	label,
		const std::string &	description,
		Flags	flags = `Flags::Zero()`
	)

inlineprotected

Constructs a new MenuItem.

Note: All MenuItem objects must be managed by std::shared_ptr.

Parameters

label	Short text presented to the user as the menu item.
description	Longer text optionally presented to the user to provide a better idea of what the option does.
flags	The option flags for the item. The default is zero: enabled, visible, no value, and not a toggle.

Definition at line 144 of file MenuItem.hpp.

◆ MenuItem() [3/4]

duds::ui::menu::MenuItem::MenuItem	(	MenuItemToken	,
		const std::string &	label,
		const std::string &	description,
		const std::string &	value,
		Flags	flags = `Flags::Zero()`
	)

inlineprotected

Constructs a new MenuItem with an associated value.

Note: All MenuItem objects must be managed by std::shared_ptr.

Parameters

label	Short text presented to the user as the menu item.
description	Longer text optionally presented to the user to provide a better idea of what the option does.
value	The current value associated with the menu item.
flags	The option flags for the item. While the default is zero, the MenuItem::HasValue flag will be OR'd with the value given to this constructor so it is implicit when an item's value string is provided.

Definition at line 163 of file MenuItem.hpp.

◆ MenuItem() [4/4]

duds::ui::menu::MenuItem::MenuItem	(	MenuItemToken	,
		const MenuItem &	mi
	)

inlineprotected

Copy constructs a new MenuItem.

The new item will contain the same data as the original, except that it is not yet part of any menu.

Definition at line 175 of file MenuItem.hpp.

Member Function Documentation

◆ changeEnabledState()

void duds::ui::menu::MenuItem::changeEnabledState ( bool state )

Changes the state of the item to either enabled or disabled.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Parameters

state True to enable the item, or false to disable.

Definition at line 67 of file MenuItem.cpp.

Referenced by disable(), enable(), and value().

◆ changeToggle()

void duds::ui::menu::MenuItem::changeToggle ( bool state )

Changes the toggle state of the item to the indicated state.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Parameters

state The new toggle state. If this is the same as the current state, the menu's update index will not change.

Exceptions

MenuItemNotAToggle The MenuItem is not a toggle.

Definition at line 122 of file MenuItem.cpp.

Referenced by clearToggle(), setToggle(), and show().

◆ changeVisibility()

void duds::ui::menu::MenuItem::changeVisibility ( bool vis )

Changes the visibility of the item.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Parameters

vis	True to make the item visible, or false for invisible.

Definition at line 78 of file MenuItem.cpp.

Referenced by enable(), hide(), and show().

◆ chose()

virtual void duds::ui::menu::MenuItem::chose	(	MenuView &	invokingView,
		const MenuAccess &	access
	)

pure virtual

Called by MenuView when the user choses this MenuItem.

The call occurs during a MenuView::update() call. This thread will have an exclusive lock on the menu. If this function throws an exception, the caller of MenuView::update() can catch that exception.

Parameters

invokingView	The view used to chose this item.
access	An access object for the menu that may be used to modify the menu.

Implemented in duds::ui::menu::GenericMenuItem.

Referenced by isSelectable().

◆ clearToggle()

void duds::ui::menu::MenuItem::clearToggle ( )

inline

Clears the toggle state of the item.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Exceptions

MenuItemNotAToggle The MenuItem is not a toggle.

Definition at line 300 of file MenuItem.hpp.

◆ description() [1/2]

const std::string& duds::ui::menu::MenuItem::description ( ) const

inline

Returns the optional description text for this item.

Definition at line 194 of file MenuItem.hpp.

Referenced by duds::ui::menu::GenericMenuItem::make().

◆ description() [2/2]

void duds::ui::menu::MenuItem::description ( const std::string & d )

Changes the optional description text for this item.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Parameters

d	The new description text.

Definition at line 34 of file MenuItem.cpp.

◆ deselect()

void duds::ui::menu::MenuItem::deselect	(	MenuView &	invokingView,
		const MenuAccess &	access
	)

virtual

Invoked when the user has selected another item, and before the select() function for that item is invoked.

The implementation in MenuItem does nothing.

Note: This function will not be called when the item is currently selected and then removed from the menu. Issues with locking resources prevents a simple solution.

Reimplemented in duds::ui::menu::GenericMenuItem.

Definition at line 159 of file MenuItem.cpp.

Referenced by isSelectable().

◆ disable()

void duds::ui::menu::MenuItem::disable ( )

inline

Makes the item disabled.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Definition at line 237 of file MenuItem.hpp.

◆ enable()

void duds::ui::menu::MenuItem::enable ( )

inline

Makes the item enabled.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Definition at line 246 of file MenuItem.hpp.

◆ flags()

Flags duds::ui::menu::MenuItem::flags ( ) const

inline

Returns the option flags for the item.

Definition at line 322 of file MenuItem.hpp.

Referenced by duds::ui::menu::GenericMenuItem::make().

◆ hasValue()

bool duds::ui::menu::MenuItem::hasValue ( ) const

inline

True if the item is flagged as having a value.

Definition at line 352 of file MenuItem.hpp.

◆ hide()

void duds::ui::menu::MenuItem::hide ( )

inline

Makes the item invisible.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Definition at line 263 of file MenuItem.hpp.

◆ isDisabled()

bool duds::ui::menu::MenuItem::isDisabled ( ) const

inline

True if the item is flagged as disabled.

Definition at line 328 of file MenuItem.hpp.

◆ isEnabled()

bool duds::ui::menu::MenuItem::isEnabled ( ) const

inline

True if the item is flagged as enabled.

Definition at line 334 of file MenuItem.hpp.

◆ isInvisible()

bool duds::ui::menu::MenuItem::isInvisible ( ) const

inline

True if the item is flagged as invisible.

Definition at line 340 of file MenuItem.hpp.

◆ isSelectable()

bool duds::ui::menu::MenuItem::isSelectable ( ) const

inline

Returns true if the item is both visible and enabled.

Definition at line 371 of file MenuItem.hpp.

◆ isToggle()

bool duds::ui::menu::MenuItem::isToggle ( ) const

inline

True if the item is flagged as being a toggle.

Definition at line 358 of file MenuItem.hpp.

◆ isToggledOn()

bool duds::ui::menu::MenuItem::isToggledOn ( ) const

inline

True if the item is in the toggled on (true) state.

If the item is not a toggle, the result will be false.

Examples:: bppmenu.cpp.

Definition at line 365 of file MenuItem.hpp.

◆ isVisible()

bool duds::ui::menu::MenuItem::isVisible ( ) const

inline

True if the item is flagged as visible.

Definition at line 346 of file MenuItem.hpp.

◆ label() [1/2]

const std::string& duds::ui::menu::MenuItem::label ( ) const

inline

Returns the label text for this item.

Definition at line 180 of file MenuItem.hpp.

Referenced by duds::ui::menu::GenericMenuItem::make().

◆ label() [2/2]

void duds::ui::menu::MenuItem::label ( const std::string & l )

Changes the label text for this item.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Parameters

l	The new label text.

Definition at line 23 of file MenuItem.cpp.

◆ menu()

Menu* duds::ui::menu::MenuItem::menu ( ) const

inline

Returns the menu object that owns this item.

Definition at line 316 of file MenuItem.hpp.

◆ remove()

void duds::ui::menu::MenuItem::remove ( )

Removes the item from its parent menu.

If the item has not been added to a menu, this function has no effect.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Definition at line 147 of file MenuItem.cpp.

◆ select()

void duds::ui::menu::MenuItem::select	(	MenuView &	invokingView,
		const MenuAccess &	access
	)

virtual

Invoked when the user has selected, but has not chosen, the item.

The implementation in MenuItem does nothing.

Reimplemented in duds::ui::menu::GenericMenuItem.

Definition at line 157 of file MenuItem.cpp.

Referenced by isSelectable().

◆ setToggle()

void duds::ui::menu::MenuItem::setToggle ( )

inline

Sets the toggle state of the item.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Exceptions

MenuItemNotAToggle The MenuItem is not a toggle.

Definition at line 310 of file MenuItem.hpp.

◆ show()

void duds::ui::menu::MenuItem::show ( )

inline

Makes the item visible.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Definition at line 272 of file MenuItem.hpp.

◆ toggle()

bool duds::ui::menu::MenuItem::toggle ( )

Toggles the toggle state of the item and returns the new toggle state.

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Exceptions

MenuItemNotAToggle The MenuItem is not a toggle.

Examples:: bppmenu.cpp.

Definition at line 100 of file MenuItem.cpp.

Referenced by show().

◆ value() [1/2]

const std::string& duds::ui::menu::MenuItem::value ( ) const

inline

Returns the optional value text for the item.

If the item is not flagged to have a value (MenuItem::HasValue), the string will be empty. If the item is flagged as having a value, an empty string is valid.

Definition at line 210 of file MenuItem.hpp.

Referenced by duds::ui::menu::GenericMenuItem::make().

◆ value() [2/2]

void duds::ui::menu::MenuItem::value ( const std::string & v )

Changes the optional value text for the item.

The item must be flagged as having a value (MenuItem::HasValue).

Note: If the item has been added to a menu, this operation requires an exclusive lock on the parent Menu. The lock is recursive, and this function will acquire and release that lock if needed.

Parameters

v	The new value string.

Exceptions

MenuItemLacksValue The item is not flagged as having a value.

Definition at line 45 of file MenuItem.cpp.

Member Data Documentation

◆ descr

std::string duds::ui::menu::MenuItem::descr

private

Additional text that may be shown to provide users with a better idea of what the option does.

Definition at line 100 of file MenuItem.hpp.

Referenced by description().

◆ Disabled

constexpr MenuItem::Flags duds::ui::menu::MenuItem::Disabled = Flags::Bit(0)

static

Indicates that the item may not be chosen by the user.

Items that are disabled and visible should be rendered in a way that tells the user they exist but are disabled.

Definition at line 69 of file MenuItem.hpp.

Referenced by changeEnabledState(), isDisabled(), and isEnabled().

◆ flgs

Flags duds::ui::menu::MenuItem::flgs

private

The item's option flags.

Definition at line 112 of file MenuItem.hpp.

Referenced by changeEnabledState(), changeToggle(), changeVisibility(), flags(), toggle(), and value().

◆ HasValue

constexpr MenuItem::Flags duds::ui::menu::MenuItem::HasValue = Flags::Bit(2)

static

Indicates that the item has a value, or setting, that should be shown in the menu if possible.

Definition at line 79 of file MenuItem.hpp.

Referenced by hasValue(), and value().

◆ Invisible

constexpr MenuItem::Flags duds::ui::menu::MenuItem::Invisible = Flags::Bit(1)

static

Indicates that the item will not be rendered.

This will also prevent the item from being chosen.

Definition at line 74 of file MenuItem.hpp.

Referenced by changeVisibility(), isInvisible(), isSelectable(), and isVisible().

◆ lbl

std::string duds::ui::menu::MenuItem::lbl

private

The text shown to represent the item.

Definition at line 95 of file MenuItem.hpp.

Referenced by label().

◆ Menu

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

private

Definition at line 113 of file MenuItem.hpp.

◆ parent

Menu* duds::ui::menu::MenuItem::parent = nullptr

private

The owning Menu object.

Definition at line 108 of file MenuItem.hpp.

Referenced by changeEnabledState(), changeToggle(), changeVisibility(), description(), label(), menu(), remove(), toggle(), and value().

◆ Toggle

constexpr MenuItem::Flags duds::ui::menu::MenuItem::Toggle = Flags::Bit(3)

static

Denotes that the item is a toggle, and that the toggle state should be visible on the menu.

Definition at line 84 of file MenuItem.hpp.

Referenced by changeToggle(), isToggle(), and toggle().

◆ ToggledOn

constexpr MenuItem::Flags duds::ui::menu::MenuItem::ToggledOn = Flags::Bit(4)

static

The toggle state; true when the state is on, when the item is true.

Only valid if toggle is also true. This value is not automatically changed by choosing the item.

Definition at line 90 of file MenuItem.hpp.

Referenced by changeToggle(), isToggledOn(), and toggle().

◆ val

std::string duds::ui::menu::MenuItem::val

private

An optional string for the current setting of the item.

Definition at line 104 of file MenuItem.hpp.

Referenced by value().

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

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Flags

Constructor & Destructor Documentation

◆ MenuItem() [1/4]

◆ MenuItem() [2/4]

◆ MenuItem() [3/4]

◆ MenuItem() [4/4]

Member Function Documentation

◆ changeEnabledState()

◆ changeToggle()

◆ changeVisibility()

◆ chose()

◆ clearToggle()

◆ description() [1/2]

◆ description() [2/2]

◆ deselect()

◆ disable()

◆ enable()

◆ flags()

◆ hasValue()

◆ hide()

◆ isDisabled()

◆ isEnabled()

◆ isInvisible()

◆ isSelectable()

◆ isToggle()

◆ isToggledOn()

◆ isVisible()

◆ label() [1/2]

◆ label() [2/2]

◆ menu()

◆ remove()

◆ select()

◆ setToggle()

◆ show()

◆ toggle()

◆ value() [1/2]

◆ value() [2/2]

Member Data Documentation

◆ descr

◆ Disabled

◆ flgs

◆ HasValue

◆ Invisible

◆ lbl

◆ Menu

◆ parent

◆ Toggle

◆ ToggledOn

◆ val