guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::components::Menu Class Reference

State of a menu: a floating list of choices that opens next to an anchor. More...

#include <headers/guillaume/components/menu.hpp>

Inheritance diagram for guillaume::components::Menu:
Collaboration diagram for guillaume::components::Menu:

Classes

struct  Item
 Description of one menu item, as given by the user. More...
struct  Row
 Identifiers of the entities built for one item. More...

Public Types

enum class  Variant { Dropdown , Context , Cascading }
 Kind of menu. It is stored for the application; the menu system styles and places every kind alike. More...
enum class  Mode { Elevated , Flat }
 How the menu surface stands out from what is behind it. More...
enum class  AnchorPosition { Bottom , Top }
 Side of the anchor the menu opens on. More...

Public Member Functions

 Menu (void)=default
 Create the configuration of an empty, elevated dropdown menu with no anchor.
 ~Menu (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get the kind of menu.
Menu & setVariant (Variant variant)
 Set the kind of menu.
Mode getMode (void) const noexcept
 Get how the menu surface stands out.
Menu & setMode (Mode mode)
 Choose between an elevated and a flat menu surface.
const std::vector< Item > & getItems (void) const noexcept
 Get the description of every item.
Menu & setItems (std::vector< Item > items)
 Replace the items.
Menu & setItemDisabled (std::size_t index, bool disabled)
 Change the disabled flag recorded for one item.
const std::vector< Row > & getRows (void) const noexcept
 Get the entities built for the items.
Menu & setRows (const std::vector< Row > &rows)
 Record the entities built for the items.
bool isRowsDirty (void) const noexcept
 Tell whether the rows must be rebuilt from the items.
Menu & setRowsDirty (bool dirty)
 Mark the rows as out of date or as up to date.
ecs::Entity::Identifier getAnchor (void) const noexcept
 Get the entity the menu opens next to.
Menu & setAnchor (ecs::Entity::Identifier anchor)
 Set the entity the menu opens next to.
AnchorPosition getAnchorPosition (void) const noexcept
 Get the side of the anchor the menu opens on.
Menu & setAnchorPosition (AnchorPosition position)
 Choose the side of the anchor the menu opens on.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Static Public Attributes

static constexpr float MinWidth = 112.0f
 Smallest width of a menu, in dp.
static constexpr float MaxWidth = 280.0f
 Largest width of a menu, in dp.

Detailed Description

State of a menu: a floating list of choices that opens next to an anchor.

The entities::Menu widget writes it: the items, the anchor, and one Row of entity identifiers per item it builds. systems::Menu reads it every frame in the Layout phase and turns it into the menu's Layout, Color, Borders, Elevation, Overlay flags and Transform (placed next to the anchor), and into the Layout, Color and enabled state of each row.

Whether the menu is shown, and the callback run when it is dismissed, are not stored here: they are in the components::Overlay of the same entity (see systems::Menu::show and systems::Menu::hide).

Items and rows are two lists that must stay in step: getRows()[i] holds the entities built for getItems()[i]. Replacing the items does not rebuild the rows; the widget raises the rows-dirty flag and rebuilds them.

See also
systems::Menu, components::Overlay, entities::Menu

Definition at line 58 of file menu.hpp.

Member Enumeration Documentation

◆ AnchorPosition

Side of the anchor the menu opens on.

Enumerator
Bottom 

Below the anchor.

Top 

Above the anchor.

Definition at line 78 of file menu.hpp.

◆ Mode

How the menu surface stands out from what is behind it.

Enumerator
Elevated 

Level 2 shadow and tonal tint.

Flat 

No shadow.

Definition at line 70 of file menu.hpp.

◆ Variant

Kind of menu. It is stored for the application; the menu system styles and places every kind alike.

Definition at line 65 of file menu.hpp.

Member Function Documentation

◆ getAnchor()

ecs::Entity::Identifier guillaume::components::Menu::getAnchor ( void ) const
noexcept

Get the entity the menu opens next to.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the menu has no anchor.

Definition at line 125 of file menu.cpp.

◆ getAnchorPosition()

Menu::AnchorPosition guillaume::components::Menu::getAnchorPosition ( void ) const
noexcept

Get the side of the anchor the menu opens on.

Returns
The position, AnchorPosition::Bottom by default.

Definition at line 139 of file menu.cpp.

◆ getItems()

const std::vector< Menu::Item > & guillaume::components::Menu::getItems ( void ) const
noexcept

Get the description of every item.

Returns
The items, from top to bottom.

Definition at line 64 of file menu.cpp.

◆ getMode()

Menu::Mode guillaume::components::Menu::getMode ( void ) const
noexcept

Get how the menu surface stands out.

Returns
The mode, Mode::Elevated by default.

Definition at line 50 of file menu.cpp.

◆ getRows()

const std::vector< Menu::Row > & guillaume::components::Menu::getRows ( void ) const
noexcept

Get the entities built for the items.

Returns
One row per built item, in item order. Empty until the widget has built them.

Definition at line 97 of file menu.cpp.

Here is the caller graph for this function:

◆ getVariant()

Menu::Variant guillaume::components::Menu::getVariant ( void ) const
noexcept

Get the kind of menu.

Returns
The variant, Variant::Dropdown by default.

Definition at line 36 of file menu.cpp.

◆ isRowsDirty()

bool guillaume::components::Menu::isRowsDirty ( void ) const
noexcept

Tell whether the rows must be rebuilt from the items.

Returns
True when the items changed since the rows were built. True for a new component.

Definition at line 111 of file menu.cpp.

◆ setAnchor()

Menu & guillaume::components::Menu::setAnchor ( ecs::Entity::Identifier anchor)

Set the entity the menu opens next to.

Every frame, systems::Menu aligns the menu with the leading edge of the anchor, below or above it. The anchor needs a Transform and a Bound; without an anchor the menu keeps its own pose. Marks the component changed only when the identifier differs.

Parameters
anchorThe anchor's identifier, or ecs::Entity::InvalidIdentifier for none.
Returns
This component, for chaining.

Definition at line 130 of file menu.cpp.

Here is the call graph for this function:

◆ setAnchorPosition()

Menu & guillaume::components::Menu::setAnchorPosition ( AnchorPosition position)

Choose the side of the anchor the menu opens on.

Marks the component changed only when the position differs.

Parameters
positionBelow or above the anchor.
Returns
This component, for chaining.

Definition at line 144 of file menu.cpp.

Here is the call graph for this function:

◆ setItemDisabled()

Menu & guillaume::components::Menu::setItemDisabled ( std::size_t index,
bool disabled )

Change the disabled flag recorded for one item.

To update the row on screen too, call systems::Menu::setItemDisabled. Marks the component changed only when the flag differs.

Parameters
indexThe item index, starting at 0. An index out of range is ignored.
disabledTrue to disable the item.
Returns
This component, for chaining.

Definition at line 88 of file menu.cpp.

Here is the call graph for this function:

◆ setItems()

Menu & guillaume::components::Menu::setItems ( std::vector< Item > items)

Replace the items.

The press handlers are always replaced. The component is marked changed only when the labels, icons or flags differ, because handlers cannot be compared. The rows are left as they are: whoever owns the row entities rebuilds them.

Parameters
itemsThe new items, from top to bottom.
Returns
This component, for chaining.

Definition at line 69 of file menu.cpp.

Here is the call graph for this function:

◆ setMode()

Menu & guillaume::components::Menu::setMode ( Mode mode)

Choose between an elevated and a flat menu surface.

Marks the component changed only when the mode differs.

Parameters
modeThe new mode.
Returns
This component, for chaining.

Definition at line 55 of file menu.cpp.

Here is the call graph for this function:

◆ setRows()

Menu & guillaume::components::Menu::setRows ( const std::vector< Row > & rows)

Record the entities built for the items.

Marks the component changed only when the rows differ.

Parameters
rowsOne row per item, in item order.
Returns
This component, for chaining.

Definition at line 102 of file menu.cpp.

Here is the call graph for this function:

◆ setRowsDirty()

Menu & guillaume::components::Menu::setRowsDirty ( bool dirty)

Mark the rows as out of date or as up to date.

The widget raises the flag when it replaces the items and lowers it once it has rebuilt the row entities. Marks the component changed only when the flag differs.

Parameters
dirtyTrue when the rows must be rebuilt.
Returns
This component, for chaining.

Definition at line 116 of file menu.cpp.

Here is the call graph for this function:

◆ setVariant()

Menu & guillaume::components::Menu::setVariant ( Variant variant)

Set the kind of menu.

Marks the component changed only when the variant differs.

Parameters
variantThe new variant.
Returns
This component, for chaining.

Definition at line 41 of file menu.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ MaxWidth

float guillaume::components::Menu::MaxWidth = 280.0f
staticconstexpr

Largest width of a menu, in dp.

Definition at line 126 of file menu.hpp.

◆ MinWidth

float guillaume::components::Menu::MinWidth = 112.0f
staticconstexpr

Smallest width of a menu, in dp.

Definition at line 123 of file menu.hpp.


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