guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
menu.cpp
1/*
2 Copyright (c) 2026 ETIB Corporation
3
4 Permission is hereby granted, free of charge, to any person obtaining a copy of
5 this software and associated documentation files (the "Software"), to deal in
6 the Software without restriction, including without limitation the rights to
7 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
8 of the Software, and to permit persons to whom the Software is furnished to do
9 so, subject to the following conditions:
10
11 The above copyright notice and this permission notice shall be included in all
12 copies or substantial portions of the Software.
13
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20 SOFTWARE.
21 */
22
23#include <memory>
24#include <utility>
25
26#include "guillaume/entities/menu.hpp"
27
28#include "guillaume/components/borders.hpp"
29#include "guillaume/components/bound.hpp"
30#include "guillaume/components/color.hpp"
31#include "guillaume/components/layout.hpp"
32#include "guillaume/components/transform.hpp"
33#include "guillaume/ecs/parent_entity_filler.hpp"
34#include "guillaume/entities/builder_base.hpp"
35#include "guillaume/entities/content_helpers.hpp"
37#include "guillaume/systems/menu.hpp"
38#include "guillaume/theme.hpp"
39
40namespace guillaume::entities
41{
42 namespace
43 {
45 constexpr float MenuIconSize = 24.0f;
46
53 class MenuRow final:
54 public ecs::ParentEntityFiller<
55 components::Layout, components::Transform, components::Bound,
56 components::Color, components::Borders>
57 {
58 public:
63 explicit MenuRow(ecs::ComponentRegistry &registry)
64 : ecs::ParentEntityFiller<components::Layout,
65 components::Transform,
66 components::Bound, components::Color,
67 components::Borders>(registry)
68 {
69 }
70
74 ~MenuRow(void) override = default;
75 };
76 } // namespace
77
79 ecs::EntityRegistry &entityRegistry)
80 : EntityBuilderBase<Menu>(componentRegistry, entityRegistry)
81 {
82 reset();
83 }
84
85 std::shared_ptr<Menu> Menu::Builder::buildEntity(void)
86 {
87 auto entity = Menu::create(this->getComponentRegistry(), _config,
88 _variant, _items);
89 return entity;
90 }
91
93 {
94 _config = SurfaceConfig();
95 _variant = Variant::Dropdown;
96 _items.clear();
97
99 _config.mainAxisAlignment =
101 _config.crossAxisAlignment =
103 _config.padding = 0.0f;
104 _config.spacing = 0.0f;
105 _config.borderRadius = getShapeRadius(theme::ShapeRole::ExtraSmall);
106 _config.setFixedWidth(MinWidth);
107 }
108
109 Menu::Builder &Menu::Builder::withPose(const utility::graphic::PoseF &pose)
110 {
111 _config.pose = pose;
112 return *this;
113 }
114
116 {
117 _variant = variant;
118 return *this;
119 }
120
121 Menu::Builder &Menu::Builder::addItem(const std::string &label,
122 const std::string &leadingIcon)
123 {
124 Item item;
125 item.label = label;
126 item.leadingIcon = leadingIcon;
127 _items.push_back(item);
128 return *this;
129 }
130
132 {
133 _items.push_back(item);
134 return *this;
135 }
136
137 std::shared_ptr<Menu>
138 Menu::Builder::makeMenu(std::shared_ptr<ecs::Entity> parent,
139 Variant variant, const std::vector<Item> &items)
140 {
141 withVariant(variant);
142
143 for (const auto &item: items) {
144 addItem(item);
145 }
146
147 return registerEntity(parent);
148 }
149
150 Menu::Menu(ecs::ComponentRegistry &registry, const SurfaceConfig &config,
151 Variant variant, const std::vector<Item> &items)
152 : SurfaceBase<components::Overlay, components::Elevation,
153 components::Accessibility, components::Menu>(registry,
154 config)
155 {
158 .setVariant(variant)
159 .setItems(items);
162 }
163
172
179
188
195
196 Menu &Menu::setItems(const std::vector<Item> &items)
197 {
200 .setItems(items)
201 .setRowsDirty(true);
202 buildItems();
204 return *this;
205 }
206
207 std::size_t Menu::getItemCount(void) const
208 {
209 return getComponentRegistry()
211 .getItems()
212 .size();
213 }
214
216 {
217 const auto &rows = getComponentRegistry()
219 .getRows();
220
221 return index < rows.size() ? rows[index].view
223 }
224
225 Menu &Menu::setItemDisabled(std::size_t index, bool disabled)
226 {
228 index, disabled);
229 return *this;
230 }
231
240
247
256
263
264 Menu &Menu::setOnDismiss(std::function<void(void)> onDismiss)
265 {
268 .setOnDismissHandler(std::move(onDismiss));
269 return *this;
270 }
271
272 Menu &Menu::dismiss(void)
273 {
275 return *this;
276 }
277
278 Menu &Menu::open(void)
279 {
280 return show();
281 }
282
283 Menu &Menu::close(void)
284 {
285 return hide();
286 }
287
288 bool Menu::isOpen(void) const
289 {
290 return isVisible();
291 }
292
293 Menu &Menu::show(void)
294 {
296 return *this;
297 }
298
299 Menu &Menu::hide(void)
300 {
302 return *this;
303 }
304
305 bool Menu::isVisible(void) const
306 {
307 return getComponentRegistry()
309 .isVisible();
310 }
311
312 void Menu::build(void)
313 {
314 buildItems();
316 }
317
318 void Menu::buildItems(void)
319 {
320 // Children need the owning handle as their parent.
321 if (weak_from_this().expired()) {
322 return;
323 }
324
325 auto &registry = getComponentRegistry();
326 auto &menu = registry.getComponent<components::Menu>(getIdentifier());
327
328 if (!menu.isRowsDirty()) {
329 return;
330 }
331
332 // The rows are rebuilt from scratch: remove the previous generation
333 // with its components. Everything the menu owns is a row.
335
336 std::vector<components::Menu::Row> rows;
337 Children children;
338
339 for (const auto &item: menu.getItems()) {
340 const auto view = std::make_shared<MenuRow>(registry);
341 components::Menu::Row row;
342
343 view->setParent(shared_from_this());
344 addEntity(view);
345 row.view = view->getIdentifier();
346
347 if (const auto icon = buildIcon(
348 registry, *this, view, item.leadingIcon, MenuIconSize,
349 schemeColor(SchemeColorRole::OnSurfaceVariant))) {
350 row.content.push_back(icon->getIdentifier());
351 row.icons.push_back(icon->getIdentifier());
352 }
353 if (const auto label =
354 buildText(registry, *this, view, item.label,
356 schemeColor(SchemeColorRole::OnSurface))) {
357 row.content.push_back(label->getIdentifier());
358 row.label = label->getIdentifier();
359 }
360 if (const auto icon = buildIcon(
361 registry, *this, view, item.trailingIcon, MenuIconSize,
362 schemeColor(SchemeColorRole::OnSurfaceVariant))) {
363 row.content.push_back(icon->getIdentifier());
364 row.icons.push_back(icon->getIdentifier());
365 }
366
367 rows.push_back(row);
368 children.push_back(view);
369 }
370
371 menu.setRows(rows).setRowsDirty(false);
372 for (std::size_t index = 0; index < rows.size(); ++index) {
373 systems::Menu::installRow(registry, getIdentifier(), index);
374 }
375
376 // Hand the layout children to the surface.
377 setChildren(children);
378 }
379
380} // namespace guillaume::entities
@ Start
At the top (row) or left (column).
Definition layout.hpp:100
@ Start
Packed at the left (row) or top (column).
Definition layout.hpp:87
@ Vertical
Column: children placed top to bottom.
Definition layout.hpp:76
State of a menu: a floating list of choices that opens next to an anchor.
Definition menu.hpp:59
Marks an entity as something shown temporarily above the rest of the interface (a dialog,...
Definition overlay.hpp:55
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
ComponentType & getComponent(const Entity::Identifier &entityIdentifier)
Get a component of an entity, to read or modify it.
ComponentRegistry & getComponentRegistry(void)
Get the registry in which the builder creates components.
Owns entities and gives the systems the list of entities to visit.
void addEntity(std::shared_ptr< Entity > entity)
Make this registry own an entity, so that it stays alive and systems visit it.
void clearEntities(void)
Remove every entity owned by this registry, with everything they own and all their components.
Entity::Identifier getIdentifier(void) const noexcept
Get the identifier of the entity.
Definition entity.cpp:94
std::size_t Identifier
The key under which an entity's components are stored. Systems and components refer to entities by th...
Definition entity.hpp:86
static constexpr Identifier InvalidIdentifier
"No entity": never the identifier of a real entity
Definition entity.hpp:93
std::shared_ptr< Menu > registerEntity(std::shared_ptr< ecs::Entity > parent)
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Configures a Menu, creates it and registers it in an entity registry.
Definition menu.hpp:134
std::shared_ptr< Menu > makeMenu(std::shared_ptr< ecs::Entity > parent, Variant variant, const std::vector< Item > &items)
Build a menu, register it under parent and reset the builder.
Definition menu.cpp:138
Builder & addItem(const std::string &label, const std::string &leadingIcon="")
Append an enabled item without press handler.
Definition menu.cpp:121
std::shared_ptr< Menu > buildEntity(void) override
Build a menu and its rows from the current configuration, without registering it or setting its paren...
Definition menu.cpp:85
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Create a builder set to the defaults of reset().
Definition menu.cpp:78
void reset(void) override
Restore the defaults.
Definition menu.cpp:92
Builder & withVariant(Variant variant)
Set the variant.
Definition menu.cpp:115
Builder & withPose(const utility::graphic::PoseF &pose)
Set where the menu is placed while it has no anchor.
Definition menu.cpp:109
components::Menu::Variant Variant
Menu variant (Dropdown, Context, Cascading); stored only.
Definition menu.hpp:109
ecs::Entity::Identifier getAnchor(void) const
Get the anchor entity.
Definition menu.cpp:241
bool isVisible(void) const
Whether the menu is shown.
Definition menu.cpp:305
Menu & close(void)
Close the menu without calling the dismiss handler. Same as hide().
Definition menu.cpp:283
components::Menu::AnchorPosition AnchorPosition
Definition menu.hpp:117
components::Menu::Item Item
Definition menu.hpp:121
Menu & setVariant(Variant variant)
Change the variant stored in components::Menu.
Definition menu.cpp:164
Menu & show(void)
Move the menu next to its anchor, then show it.
Definition menu.cpp:293
components::Menu::Mode Mode
Definition menu.hpp:113
static constexpr float MinWidth
Smallest M3 menu width, in dp.
Definition menu.hpp:124
AnchorPosition getAnchorPosition(void) const
Get the side of the anchor the menu opens on.
Definition menu.cpp:257
Menu & dismiss(void)
Close the menu as the user would: hide it, then call the dismiss handler.
Definition menu.cpp:272
bool isOpen(void) const
Whether the menu is open. Same as isVisible().
Definition menu.cpp:288
Menu & hide(void)
Hide the menu without calling the dismiss handler.
Definition menu.cpp:299
Menu & setItemDisabled(std::size_t index, bool disabled)
Enable or disable an item. Restyles at once.
Definition menu.cpp:225
Menu & setOnDismiss(std::function< void(void)> onDismiss)
Set the handler called when the menu is dismissed (Paper onDismiss).
Definition menu.cpp:264
Menu & setAnchorPosition(AnchorPosition position)
Choose on which side of its anchor the menu opens. Moves the menu at once.
Definition menu.cpp:248
std::size_t getItemCount(void) const
Get the number of items.
Definition menu.cpp:207
Menu & open(void)
Open the menu. Same as show().
Definition menu.cpp:278
Menu & setItems(const std::vector< Item > &items)
Replace the items.
Definition menu.cpp:196
Menu & setMode(Mode mode)
Change the surface mode (Paper mode). Restyles at once.
Definition menu.cpp:180
Variant getVariant(void) const
Get the variant.
Definition menu.cpp:173
ecs::Entity::Identifier getItemIdentifier(std::size_t index) const
Get the row entity of an item: the pressable container of its icons and label.
Definition menu.cpp:215
Menu & setAnchor(ecs::Entity::Identifier anchor)
Anchor the menu to another entity.
Definition menu.cpp:232
static std::shared_ptr< Menu > create(Arguments &&...arguments)
Create a menu and its rows, without registering it in an entity registry.
Definition menu.hpp:230
Mode getMode(void) const
Get the surface mode.
Definition menu.cpp:189
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 setItemDisabled(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, bool disabled)
Enable or disable an item and restyle the menu.
Definition menu.cpp:289
static void hide(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Hide the menu without telling anyone.
Definition menu.cpp:306
static void installRow(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Make one row pressable.
Definition menu.cpp:188
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
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Style one menu, size its rows and move it next to its anchor.
Definition menu.cpp:332
Makes the color helpers callable from guillaume::entities without qualification.
State. Every class here is plain data attached to an entity.
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
std::shared_ptr< Text > buildText(ecs::ComponentRegistry &registry, ecs::EntityRegistry &entityRegistry, std::shared_ptr< ecs::Entity > parent, const std::string &content, float fontSize, const utility::graphic::Color32Bit &color)
Create a Text of a given font size as a child of a widget, or nothing when there is no content.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
std::shared_ptr< Icon > buildIcon(ecs::ComponentRegistry &registry, ecs::EntityRegistry &entityRegistry, std::shared_ptr< ecs::Entity > parent, const std::string &glyphName, float fontSize, const utility::graphic::Color32Bit &color, components::Glyph::Style style=components::Glyph::Style::Outlined)
Create an Icon as a child of a widget, or nothing when there is no glyph to show.
@ BodyLarge
16 / 24, regular.
Definition typescale.hpp:60
@ ExtraSmall
4 dp (text fields, menus, snackbars).
Definition tokens.hpp:44
float getShapeRadius(theme::ShapeRole role)
Get the corner radius the active theme gives to a shape role.
std::string label
Text of the item.
Definition menu.hpp:87
Everything needed to set up a surface in one value: where it is, how it looks and how it arranges its...
Definition surface.hpp:71