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

A pop-up column of pressable items, shown on demand next to an anchor entity (Paper Menu and Menu.Item). More...

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

Inheritance diagram for guillaume::entities::Menu:
Collaboration diagram for guillaume::entities::Menu:

Classes

class  Builder
 Configures a Menu, creates it and registers it in an entity registry. More...

Public Types

using Variant = components::Menu::Variant
 Menu variant (Dropdown, Context, Cascading); stored only.
using Mode = components::Menu::Mode
using AnchorPosition = components::Menu::AnchorPosition
using Item = components::Menu::Item
Public Types inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Accessibility, components::Menu >
using Children
Public Types inherited from guillaume::ecs::Entity
using Identifier = std::size_t
 The key under which an entity's components are stored. Systems and components refer to entities by this value.
using Signature = std::bitset<128>
 A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits).

Public Member Functions

 ~Menu (void) override=default
 Default destructor.
Menu & setVariant (Variant variant)
 Change the variant stored in components::Menu.
Variant getVariant (void) const
 Get the variant.
Menu & setMode (Mode mode)
 Change the surface mode (Paper mode). Restyles at once.
Mode getMode (void) const
 Get the surface mode.
Menu & setItems (const std::vector< Item > &items)
 Replace the items.
std::size_t getItemCount (void) const
 Get the number of items.
ecs::Entity::Identifier getItemIdentifier (std::size_t index) const
 Get the row entity of an item: the pressable container of its icons and label.
Menu & setItemDisabled (std::size_t index, bool disabled)
 Enable or disable an item. Restyles at once.
Menu & setAnchor (ecs::Entity::Identifier anchor)
 Anchor the menu to another entity.
ecs::Entity::Identifier getAnchor (void) const
 Get the anchor entity.
Menu & setAnchorPosition (AnchorPosition position)
 Choose on which side of its anchor the menu opens. Moves the menu at once.
AnchorPosition getAnchorPosition (void) const
 Get the side of the anchor the menu opens on.
Menu & setOnDismiss (std::function< void(void)> onDismiss)
 Set the handler called when the menu is dismissed (Paper onDismiss).
Menu & dismiss (void)
 Close the menu as the user would: hide it, then call the dismiss handler.
Menu & open (void)
 Open the menu. Same as show().
Menu & close (void)
 Close the menu without calling the dismiss handler. Same as hide().
bool isOpen (void) const
 Whether the menu is open. Same as isVisible().
Menu & show (void)
 Move the menu next to its anchor, then show it.
Menu & hide (void)
 Hide the menu without calling the dismiss handler.
bool isVisible (void) const
 Whether the menu is shown.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Accessibility, components::Menu >
 ~SurfaceBase (void) override=default
 Default destructor.
SurfaceBase & setPose (const utility::graphic::PoseF &pose)
 Move the surface.
SurfaceBase & setColor (const utility::graphic::Color32Bit &color)
 Set the fill color (Color component).
SurfaceBase & setBorderRadius (float radius)
 Set the radius of the four corners (Borders component).
SurfaceBase & setSurfaceConfig (const SurfaceConfig &config)
 Apply every field of a configuration at once.
SurfaceConfig getSurfaceConfig (void) const
 Read the current configuration back from the components.
SurfaceBase & setChildren (const Children &children)
 Choose the children this surface arranges, in order.
std::vector< ecs::Entity::Identifier > getChildren (void) const
 Get the children this surface arranges.
Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
 ParentEntityFiller (ComponentRegistry &componentRegistry)
 Create the entity, its listed components and its components::Hierarchy. It owns no child yet.
virtual ~ParentEntityFiller (void)=default
 Destroy the entity object and release the children it owns; components stay in the registry (see EntityRegistry::removeEntity).
Public Member Functions inherited from guillaume::ecs::Entity
 Entity (void)
 Create an entity with a fresh identifier, an empty signature, no parent and no component.
virtual ~Entity (void)=default
 Destroy the entity object.
Entity::Identifier getIdentifier (void) const noexcept
 Get the identifier of the entity.
Entity::Signature getSignature (void) const noexcept
 Get the set of component types the entity declares.
void setSignature (const Signature &signature)
 Replace the signature of the entity.
std::int32_t getLayer (void) const noexcept
 Get the depth of the entity in the tree.
Entity & setParent (std::shared_ptr< Entity > parent)
 Attach the entity under another one, or detach it.
std::vector< Identifier > releaseComponents (void)
 Drop the entity's place in the tree and all its components.
std::shared_ptr< Entity > getParent (void) const noexcept
 Get the parent entity.
Public Member Functions inherited from guillaume::ecs::EntityRegistry
 EntityRegistry (void)=default
 Create a registry.
virtual ~EntityRegistry (void)=default
 Virtual destructor.
void addEntity (std::shared_ptr< Entity > entity)
 Make this registry own an entity, so that it stays alive and systems visit it.
bool removeEntity (Entity::Identifier identifier)
 Remove an entity, with its children and all their components.
void clearEntities (void)
 Remove every entity owned by this registry, with everything they own and all their components.
const std::vector< std::shared_ptr< Entity > > & getEntities (void) const
 Get the entities this registry owns directly.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void)
 List every entity of this registry and of the registries nested in it, level by level.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void) const
 List every entity of this registry and of the registries nested in it, level by level (const overload).
template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > getEntity (Entity::Identifier identifier)
 Find an entity owned directly by this registry, by identifier.
template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > getEntity (Entity::Identifier identifier) const
 Find an entity owned directly by this registry, by identifier (const overload).
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature) const
 List the entities that have every component type of a signature, from the root down.
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const
 List the entities that have every component type of a signature, in the order chosen by a traveler.

Static Public Member Functions

template<typename... Arguments>
static std::shared_ptr< Menu > create (Arguments &&...arguments)
 Create a menu and its rows, without registering it in an entity registry.
Static Public Member Functions inherited from guillaume::ecs::Entity
template<InheritFromComponent... ComponentTypes>
static Signature getSignatureFromTypes (void)
 Build the signature that has exactly the bits of the given component types.

Static Public Attributes

static constexpr float MinWidth = components::Menu::MinWidth
 Smallest M3 menu width, in dp.
static constexpr float MaxWidth = components::Menu::MaxWidth
 Largest M3 menu width, in dp.
Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity

Additional Inherited Members

Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::Overlay, components::Elevation, components::Accessibility, components::Menu >
 SurfaceBase (ecs::ComponentRegistry &registry, const SurfaceConfig &config)
 Create the entity with its components and apply a configuration.
void applyGeometry (void)
 Arrange the layout children now with systems::Layout::apply.
Protected Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
ComponentRegistry & getComponentRegistry (void)
 Get the registry that stores this entity's components.
Protected Member Functions inherited from guillaume::ecs::ParentEntity
std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) override
 Give access to the list of entities this entity owns directly.
const std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) const override
 Give read access to the list of entities this entity owns directly.
Protected Member Functions inherited from guillaume::ecs::Entity
void attachHierarchy (ComponentRegistry &componentRegistry)
 Give the entity a components::Hierarchy in a registry and add that component to its signature.
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.

Detailed Description

A pop-up column of pressable items, shown on demand next to an anchor entity (Paper Menu and Menu.Item).

Its state lives in components::Menu (variant, mode, items, row identifiers, anchor); whether it is shown and its dismiss handler live in components::Overlay. systems::Menu styles the menu, sizes its rows and moves it next to its anchor each frame, in the Layout phase. The class itself holds no field: it builds the row entities, and its setters write the component and restyle at once.

Menu::Item remove;
remove.label = "Delete";
remove.leadingIcon = "delete";
remove.onPress = [] {
// called when the user presses the row
};
Menu::Builder builder(getComponentRegistry(), getEntityRegistry());
auto menu = builder.addItem("Rename", "edit")
.addItem(remove)
.makeMenu(parent, Menu::Variant::Dropdown, {});
menu->setAnchor(button->getIdentifier());
menu->open();
Configures a Menu, creates it and registers it in an entity registry.
Definition menu.hpp:134
components::Menu::Item Item
Definition menu.hpp:121
std::function< void(void)> onPress
Called on press.
Definition menu.hpp:92
std::string label
Text of the item.
Definition menu.hpp:87

Menu::create(registry, config, variant, items) builds the same widget without registering it in an entity registry.

Things to know:

  • The menu is closed at creation: call open().
  • Pressing an item calls its press handler and leaves the menu open; close it from the handler when needed.
  • close() and hide() do not call the dismiss handler themselves; dismiss() and Escape do.
  • Each row holds an optional leading icon, a label and an optional trailing icon. A row is 48 dp high, or 32 dp when the item is dense. The width follows the widest row, kept between MinWidth (112 dp) and MaxWidth (280 dp); it is overwritten each frame, like the menu's layout, color, corners, elevation and overlay flags.
  • With an anchor, the pose is overwritten each frame: the menu takes the position of the anchor and sits 4 dp below or above it. Without one, the menu stays at the pose it was given.
  • The variant is stored but systems::Menu does not read it: the three variants look and behave the same.
  • The menu is the entity registry that owns its rows. setItems() removes every row and builds new ones: identifiers returned before by getItemIdentifier() are then invalid.
See also
components::Menu, systems::Menu, components::Overlay

Definition at line 103 of file menu.hpp.

Member Typedef Documentation

◆ AnchorPosition

Where the menu opens relative to its anchor: Bottom (below) or Top (above).

Definition at line 117 of file menu.hpp.

◆ Item

Menu item: label, leading and trailing icon glyph names, press handler, disabled and dense flags.

Definition at line 121 of file menu.hpp.

◆ Mode

Surface mode (Paper mode): Elevated (level-2 shadow and tint) or Flat (no shadow).

Definition at line 113 of file menu.hpp.

◆ Variant

Menu variant (Dropdown, Context, Cascading); stored only.

Definition at line 109 of file menu.hpp.

Member Function Documentation

◆ close()

Menu & guillaume::entities::Menu::close ( void )

Close the menu without calling the dismiss handler. Same as hide().

Returns
This menu, for chaining.

Definition at line 283 of file menu.cpp.

Here is the call graph for this function:

◆ create()

template<typename... Arguments>
std::shared_ptr< Menu > guillaume::entities::Menu::create ( Arguments &&... arguments)
inlinestatic

Create a menu and its rows, without registering it in an entity registry.

The constructor is private because the rows need the menu to be owned by a shared pointer before they can take it as parent; create() constructs the menu, then builds one row per item.

Template Parameters
ArgumentsThe types of the constructor arguments.
Parameters
argumentsForwarded to the private constructor: (registry, config, variant, items).
Returns
The new menu, closed.

Definition at line 230 of file menu.hpp.

Here is the caller graph for this function:

◆ dismiss()

Menu & guillaume::entities::Menu::dismiss ( void )

Close the menu as the user would: hide it, then call the dismiss handler.

Does nothing when the menu is already closed.

Returns
This menu, for chaining.

Definition at line 272 of file menu.cpp.

Here is the call graph for this function:

◆ getAnchor()

ecs::Entity::Identifier guillaume::entities::Menu::getAnchor ( void ) const

Get the anchor entity.

Returns
The identifier of the anchor, or ecs::Entity::InvalidIdentifier when the menu has none.

Definition at line 241 of file menu.cpp.

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

◆ getAnchorPosition()

Menu::AnchorPosition guillaume::entities::Menu::getAnchorPosition ( void ) const

Get the side of the anchor the menu opens on.

Returns
Bottom or Top.

Definition at line 257 of file menu.cpp.

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

◆ getItemCount()

std::size_t guillaume::entities::Menu::getItemCount ( void ) const

Get the number of items.

Returns
How many items the menu has.

Definition at line 207 of file menu.cpp.

Here is the call graph for this function:

◆ getItemIdentifier()

ecs::Entity::Identifier guillaume::entities::Menu::getItemIdentifier ( std::size_t index) const

Get the row entity of an item: the pressable container of its icons and label.

Parameters
indexThe index of the item, from 0.
Returns
The identifier of the row, or ecs::Entity::InvalidIdentifier when index is out of range.

Definition at line 215 of file menu.cpp.

Here is the call graph for this function:

◆ getMode()

Menu::Mode guillaume::entities::Menu::getMode ( void ) const

Get the surface mode.

Returns
Elevated or Flat.

Definition at line 189 of file menu.cpp.

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

◆ getVariant()

Menu::Variant guillaume::entities::Menu::getVariant ( void ) const

Get the variant.

Returns
The variant stored in components::Menu.

Definition at line 173 of file menu.cpp.

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

◆ hide()

Menu & guillaume::entities::Menu::hide ( void )

Hide the menu without calling the dismiss handler.

Returns
This menu, for chaining.

Definition at line 299 of file menu.cpp.

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

◆ isOpen()

bool guillaume::entities::Menu::isOpen ( void ) const

Whether the menu is open. Same as isVisible().

Returns
True when shown; false at creation.

Definition at line 288 of file menu.cpp.

Here is the call graph for this function:

◆ isVisible()

bool guillaume::entities::Menu::isVisible ( void ) const

Whether the menu is shown.

Returns
True when its components::Overlay is visible; false at creation.

Definition at line 305 of file menu.cpp.

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

◆ open()

Menu & guillaume::entities::Menu::open ( void )

Open the menu. Same as show().

Returns
This menu, for chaining.

Definition at line 278 of file menu.cpp.

Here is the call graph for this function:

◆ setAnchor()

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

Anchor the menu to another entity.

While the anchor has a Transform and a Bound, systems::Menu moves the menu to the anchor's position, 4 dp below or above it (see setAnchorPosition()), at once and then each frame.

Parameters
anchorThe identifier of the anchor entity, or ecs::Entity::InvalidIdentifier to stop following an anchor; the menu then keeps its current pose.
Returns
This menu, for chaining.

Definition at line 232 of file menu.cpp.

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

◆ setAnchorPosition()

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

Choose on which side of its anchor the menu opens. Moves the menu at once.

Parameters
positionBottom (the default) to open below the anchor, Top to open above it.
Returns
This menu, for chaining.

Definition at line 248 of file menu.cpp.

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

◆ setItemDisabled()

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

Enable or disable an item. Restyles at once.

A disabled item ignores presses.

Parameters
indexThe index of the item; nothing happens when it is out of range.
disabledTrue to disable, false to enable.
Returns
This menu, for chaining.

Definition at line 225 of file menu.cpp.

Here is the call graph for this function:

◆ setItems()

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

Replace the items.

Removes every row entity of the menu and builds new ones, then restyles at once. Row identifiers obtained before the call are invalid afterwards, even for items that did not change.

Parameters
itemsThe new items, in display order.
Returns
This menu, for chaining.

Definition at line 196 of file menu.cpp.

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

◆ setMode()

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

Change the surface mode (Paper mode). Restyles at once.

Parameters
modeElevated (the default) for the level-2 elevation and its tinted surface color, Flat for no shadow.
Returns
This menu, for chaining.

Definition at line 180 of file menu.cpp.

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

◆ setOnDismiss()

Menu & guillaume::entities::Menu::setOnDismiss ( std::function< void(void)> onDismiss)

Set the handler called when the menu is dismissed (Paper onDismiss).

The handler is stored in the menu's components::Overlay.

Parameters
onDismissCalled after dismiss() or Escape closed the menu. close() and hide() do not call it themselves.
Returns
This menu, for chaining.

Definition at line 264 of file menu.cpp.

Here is the call graph for this function:

◆ setVariant()

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

Change the variant stored in components::Menu.

Runs systems::Menu::apply at once, which does not read the variant: the look and behaviour of the menu do not change.

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

Definition at line 164 of file menu.cpp.

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

◆ show()

Menu & guillaume::entities::Menu::show ( void )

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

Returns
This menu, for chaining.

Definition at line 293 of file menu.cpp.

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

Member Data Documentation

◆ MaxWidth

float guillaume::entities::Menu::MaxWidth = components::Menu::MaxWidth
staticconstexpr

Largest M3 menu width, in dp.

Definition at line 127 of file menu.hpp.

◆ MinWidth

float guillaume::entities::Menu::MinWidth = components::Menu::MinWidth
staticconstexpr

Smallest M3 menu width, in dp.

Definition at line 124 of file menu.hpp.


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