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

Styles a menu, sizes its rows to the widest one and places the menu below or above its anchor. More...

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

Inheritance diagram for guillaume::systems::Menu:
Collaboration diagram for guillaume::systems::Menu:

Public Member Functions

 Menu (void)
 Create the system in the Layout phase.
 ~Menu (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Run apply() on one menu; called by the frame loop.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Menu >
 SystemFiller (Phase phase)
 Create the system and set its signature from ComponentTypes.
virtual ~SystemFiller (void)=default
 Virtual destructor.
Public Member Functions inherited from guillaume::ecs::System
 System (Phase phase)
 Create a system that runs in a given phase, with an empty signature.
virtual ~System (void)=default
 Virtual destructor.
Phase getPhase (void) const noexcept
 Get the phase of the frame in which the system runs.
Entity::Signature getSignature (void) const noexcept
 Get the component types an entity must declare to be visited by this system.
void routine (ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry, const ecs::EntityTreeTraveler &traveler)
 Run the system once over a scene: prepare(), update() on each matching entity, cleanup().
void bindComponentRegistry (ecs::ComponentRegistry &componentRegistry)
 Bind a component registry so update() can be called directly, without routine().
void unbindComponentRegistry (void)
 Drop the binding made by bindComponentRegistry().
virtual void prepare (void)
 Called once per pass, before the first update().
virtual void cleanup (void)
 Called once per pass, after the last update().

Static Public Member Functions

static void install (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Give a menu its accessibility semantics and make its rows pressable.
static void installRow (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Make one row pressable.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Style one menu, size its rows and move it next to its anchor.
static bool isOpen (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether a menu is open.
static void styleRow (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Recolor one row without sizing the menu again.
static void pressItem (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Activate an item as a press on its row would.
static void setItemDisabled (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, bool disabled)
 Enable or disable an item and restyle the menu.
static void show (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Place the menu next to its anchor, then show it.
static void hide (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Hide the menu without telling anyone.
static void dismiss (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Close the menu as the user would with Escape or a click outside.

Additional Inherited Members

Protected Member Functions inherited from guillaume::ecs::System
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.
ecs::EntityRegistry & getEntityRegistry (void)
 Get the entity registry of the scene being processed.
const ecs::EntityRegistry & getEntityRegistry (void) const
 Get the entity registry of the scene being processed, read-only.
ecs::ComponentRegistry & getComponentRegistry (void)
 Get the component registry of the scene being processed.
const ecs::ComponentRegistry & getComponentRegistry (void) const
 Get the component registry of the scene being processed, read-only.
template<InheritFromComponent ComponentType>
bool hasComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Tell whether an entity has a component, in the bound registry.
template<InheritFromComponent ComponentType>
ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier)
 Get a component of an entity from the bound registry, to read or modify it.
template<InheritFromComponent ComponentType>
const ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Get a component of an entity from the bound registry, read-only.
template<InheritFromComponent ComponentType>
bool requireComponent (const ecs::Entity::Identifier &entityIdentifier)
 Tell whether an entity has a component, and log a warning naming the entity and the component when it does not.

Detailed Description

Styles a menu, sizes its rows to the widest one and places the menu below or above its anchor.

Runs in the Layout phase on every entity that has a components::Menu. It is registered after systems::Layout, so the labels and icons of the rows are already measured when the menu is sized.

Whether the menu is shown is the visible flag of its components::Overlay; show(), hide() and dismiss() change it. A menu is never modal and closes on Escape or on a click outside. Pressing an item does not close it: the press handler decides.

The Transform of the menu is overwritten every frame while the anchor has a Transform and a Bound. Without such an anchor the menu keeps the pose it was given.

systems::Menu::install(registry, menu);
systems::Menu::show(registry, menu);
systems::Menu::pressItem(registry, menu, 0); // as a click would
systems::Menu::dismiss(registry, menu);
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Give a menu its accessibility semantics and make its rows pressable.
Definition menu.cpp:171
static void pressItem(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Activate an item as a press on its row would.
Definition menu.cpp:269
static void dismiss(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Close the menu as the user would with Escape or a click outside.
Definition menu.cpp:314
static void show(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Place the menu next to its anchor, then show it.
Definition menu.cpp:298
See also
components::Menu, components::Overlay, entities::Menu, systems::Overlay

Definition at line 72 of file menu.hpp.

Constructor & Destructor Documentation

◆ Menu()

guillaume::systems::Menu::Menu ( void )

Create the system in the Layout phase.

Definition at line 166 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

Member Function Documentation

◆ apply()

void guillaume::systems::Menu::apply ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Style one menu, size its rows and move it next to its anchor.

This is what update() runs each frame. Call it directly after changing components::Menu to see the result before the next frame, which is what the setters of entities::Menu do.

The menu is as wide as its widest row, kept between components::Menu::MinWidth and components::Menu::MaxWidth; every row takes that width and is 48 dp high, or 32 dp for a dense item. With the Bottom anchor position the menu starts 4 dp below the anchor, otherwise it ends 4 dp above it; in both cases their left edges are aligned.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe menu entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::Menu, Layout, Borders, Elevation, Color or Overlay, or when a recorded row has no components::Layout.

Definition at line 332 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ dismiss()

void guillaume::systems::Menu::dismiss ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Close the menu as the user would with Escape or a click outside.

Hides the menu, then calls the dismiss handler of its components::Overlay when there is one. Does nothing when the menu is already hidden.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe menu entity.

Definition at line 314 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ hide()

void guillaume::systems::Menu::hide ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Hide the menu without telling anyone.

Clears the visible flag of its components::Overlay. The dismiss handler is not called: use dismiss() when the application must be notified.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe menu entity.

Definition at line 306 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ install()

void guillaume::systems::Menu::install ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Give a menu its accessibility semantics and make its rows pressable.

Sets the role of the menu's components::Accessibility to Menu, makes the menu itself non-focusable, and calls installRow() on every row recorded in components::Menu. Call it once, after the entity has its components::Menu, Overlay, Elevation, Accessibility, Layout, Transform, Bound, Color and Borders; rows recorded later need their own installRow().

Parameters
componentRegistryThe registry holding the components. It is captured by the row handlers and must outlive the entity.
entityIdentifierThe menu entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity has no components::Accessibility or components::Menu.

Definition at line 171 of file menu.cpp.

Here is the call graph for this function:

◆ installRow()

void guillaume::systems::Menu::installRow ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Make one row pressable.

Adds the interaction components (hover and press state, focus, the MenuItem accessibility role) to the row entity, and wires its activation to pressItem() and its hover and press changes to styleRow(). When an item exists at the same index, its label becomes the accessible name of the row and its disabled flag the enabled state of the row.

Parameters
componentRegistryThe registry holding the components. It is captured by the row handlers and must outlive the entity.
entityIdentifierThe menu entity.
indexPosition of the row in the row list of components::Menu, starting at 0. An index past the end is ignored.

Definition at line 188 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ isOpen()

bool guillaume::systems::Menu::isOpen ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Whether a menu is open.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe menu entity.
Returns
True when its Overlay is visible. A closed menu draws nothing and ignores presses on its rows.

Definition at line 218 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ pressItem()

void guillaume::systems::Menu::pressItem ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Activate an item as a press on its row would.

Calls the press handler of the item when it has one. Does nothing for a disabled item. The menu stays open: a handler that should close it calls hide() or dismiss() itself.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe menu entity.
indexPosition of the item in the item list of components::Menu, starting at 0. An index past the end is ignored.

Definition at line 269 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setItemDisabled()

void guillaume::systems::Menu::setItemDisabled ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index,
bool disabled )
static

Enable or disable an item and restyle the menu.

A disabled item is drawn with the disabled content color and ignores pressItem().

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe menu entity.
indexPosition of the item in the item list of components::Menu, starting at 0.
disabledTrue to disable the item, false to enable it.

Definition at line 289 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ show()

void guillaume::systems::Menu::show ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Place the menu next to its anchor, then show it.

Calls apply() first, so the menu appears at the anchor's current position, then sets the visible flag of its components::Overlay.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe menu entity.

Definition at line 298 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ styleRow()

void guillaume::systems::Menu::styleRow ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Recolor one row without sizing the menu again.

Writes the Color of the row (its hover or press state layer), of its label and of its icons; a disabled row uses the disabled content color. This is the cheap restyle run when the pointer enters, leaves or presses a row.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe menu entity.
indexPosition of the row in the row list of components::Menu, starting at 0. An index past the end is ignored.

Definition at line 228 of file menu.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ update()

void guillaume::systems::Menu::update ( const ecs::Entity::Identifier & entityIdentifier)
overridevirtual

Run apply() on one menu; called by the frame loop.

Logs a warning and does nothing when the entity has no components::Menu.

Parameters
entityIdentifierThe menu entity.

Implements guillaume::ecs::System.

Definition at line 420 of file menu.cpp.

Here is the call graph for this function:

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