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 "guillaume/systems/menu.hpp"
24
25#include <algorithm>
26#include <vector>
27
28#include "guillaume/components/accessibility.hpp"
29#include "guillaume/components/borders.hpp"
30#include "guillaume/components/bound.hpp"
31#include "guillaume/components/color.hpp"
32#include "guillaume/components/elevation.hpp"
33#include "guillaume/components/layout.hpp"
34#include "guillaume/components/overlay.hpp"
35#include "guillaume/components/transform.hpp"
38#include "guillaume/systems/layout.hpp"
39#include "guillaume/theme.hpp"
40
41namespace guillaume::systems
42{
43 namespace
44 {
45 using Mode = components::Menu::Mode;
46 using AnchorPosition = components::Menu::AnchorPosition;
47 using Row = components::Menu::Row;
51
53 constexpr float ItemHeight = 48.0f;
54
56 constexpr float DenseItemHeight = 32.0f;
57
59 constexpr float ItemPadding = theme::SpacingScale::get(3);
60
62 constexpr float ItemSpacing = theme::SpacingScale::get(3);
63
65 constexpr float RowRadius = 16.0f;
66
68 constexpr float AnchorGap = theme::SpacingScale::get(1);
69
76 void colorChild(ecs::ComponentRegistry &registry,
78 const utility::graphic::Color32Bit &color)
79 {
80 if (registry.hasComponent<components::Color>(child)) {
81 registry.getComponent<components::Color>(child).setColor(color);
82 }
83 }
84
91 float contentWidthOf(const ecs::ComponentRegistry &registry,
92 const Row &row)
93 {
94 float width = 2.0f * ItemPadding;
95 std::size_t count = 0;
96
97 for (const auto child: row.content) {
98 if (!registry.hasComponent<components::Bound>(child)) {
99 continue;
100 }
101 width +=
102 registry.getComponent<components::Bound>(child).getWidth();
103 ++count;
104 }
105 if (count > 1) {
106 width += ItemSpacing * static_cast<float>(count - 1);
107 }
108 return width;
109 }
110
116 void arrangeRows(ecs::ComponentRegistry &registry,
117 const std::vector<Row> &rows)
118 {
119 for (const auto &row: rows) {
120 Layout::apply(registry, row.view, row.content,
121 Layout::layerOf(registry, row.view));
122 }
123 }
124
131 void applyAnchor(ecs::ComponentRegistry &registry,
132 const ecs::Entity::Identifier &identifier,
133 const components::Menu &menu)
134 {
135 const auto anchor = menu.getAnchor();
136
138 || !registry.hasComponent<components::Transform>(anchor)
139 || !registry.hasComponent<components::Bound>(anchor)) {
140 return;
141 }
142
143 const auto anchorPose =
144 registry.getComponent<components::Transform>(anchor).getPose();
145 const auto &anchorBound =
146 registry.getComponent<components::Bound>(anchor);
147 const auto &bound =
148 registry.getComponent<components::Bound>(identifier);
149
150 const float offsetY =
151 menu.getAnchorPosition() == AnchorPosition::Bottom
152 ? anchorBound.getHeight() + AnchorGap
153 : -(bound.getHeight() + AnchorGap);
154
155 const utility::graphic::PositionF position(
156 anchorPose.getPosition().getX(),
157 // offsetY is measured downward; y points up.
158 anchorPose.getPosition().getY() - offsetY,
159 anchorPose.getPosition().getZ());
160 registry.getComponent<components::Transform>(identifier)
161 .setPose(utility::graphic::PoseF(position,
162 anchorPose.getOrientation()));
163 }
164 } // namespace
165
168 {
169 }
170
171 void Menu::install(ecs::ComponentRegistry &componentRegistry,
172 const ecs::Entity::Identifier &entityIdentifier)
173 {
174 componentRegistry
175 .getComponent<components::Accessibility>(entityIdentifier)
177 .setFocusable(false);
178
179 const std::size_t count =
180 componentRegistry.getComponent<components::Menu>(entityIdentifier)
181 .getRows()
182 .size();
183 for (std::size_t index = 0; index < count; ++index) {
184 installRow(componentRegistry, entityIdentifier, index);
185 }
186 }
187
189 const ecs::Entity::Identifier &entityIdentifier,
190 std::size_t index)
191 {
192 ecs::ComponentRegistry *registry = &componentRegistry;
193 const ecs::Entity::Identifier identifier = entityIdentifier;
194 const auto &menu =
195 componentRegistry.getComponent<components::Menu>(identifier);
196
197 if (index >= menu.getRows().size()) {
198 return;
199 }
200
201 const auto row = menu.getRows()[index].view;
203 componentRegistry, row, components::AccessibilityRole::MenuItem,
204 [registry, identifier, index]() {
205 pressItem(*registry, identifier, index);
206 },
207 [registry, identifier, index]() {
208 styleRow(*registry, identifier, index);
209 });
210 if (index < menu.getItems().size()) {
211 const auto &item = menu.getItems()[index];
212 componentRegistry.getComponent<components::Accessibility>(row)
213 .setLabel(item.label);
214 interaction::setEnabled(componentRegistry, row, !item.disabled);
215 }
216 }
217
218 bool Menu::isOpen(const ecs::ComponentRegistry &componentRegistry,
219 const ecs::Entity::Identifier &entityIdentifier)
220 {
221 return componentRegistry.hasComponent<components::Overlay>(
222 entityIdentifier)
223 && componentRegistry
224 .getComponent<components::Overlay>(entityIdentifier)
225 .isVisible();
226 }
227
228 void Menu::styleRow(ecs::ComponentRegistry &componentRegistry,
229 const ecs::Entity::Identifier &entityIdentifier,
230 std::size_t index)
231 {
232 const auto &rows =
233 componentRegistry.getComponent<components::Menu>(entityIdentifier)
234 .getRows();
235
236 if (index >= rows.size()) {
237 return;
238 }
239
240 const auto &row = rows[index];
241 const bool enabled =
242 interaction::isEnabled(componentRegistry, row.view);
243
244 // A closed menu draws nothing: its rows, labels and icons turn
245 // transparent, which the renderers skip.
246 if (!isOpen(componentRegistry, entityIdentifier)) {
247 colorChild(componentRegistry, row.view, transparentColor());
248 colorChild(componentRegistry, row.label, transparentColor());
249 for (const auto icon: row.icons) {
250 colorChild(componentRegistry, icon, transparentColor());
251 }
252 return;
253 }
254
255 colorChild(componentRegistry, row.view,
257 componentRegistry, row.view, transparentColor(),
258 schemeColor(SchemeColorRole::OnSurface)));
259 colorChild(componentRegistry, row.label,
260 enabled ? schemeColor(SchemeColorRole::OnSurface)
262 for (const auto icon: row.icons) {
263 colorChild(componentRegistry, icon,
264 enabled ? schemeColor(SchemeColorRole::OnSurfaceVariant)
266 }
267 }
268
270 const ecs::Entity::Identifier &entityIdentifier,
271 std::size_t index)
272 {
273 const auto &items =
274 componentRegistry.getComponent<components::Menu>(entityIdentifier)
275 .getItems();
276
277 if (index >= items.size() || items[index].disabled
278 || !isOpen(componentRegistry, entityIdentifier)) {
279 return;
280 }
281
282 // Copy: the handler may replace the items.
283 const auto onPress = items[index].onPress;
284 if (onPress) {
285 onPress();
286 }
287 }
288
290 const ecs::Entity::Identifier &entityIdentifier,
291 std::size_t index, bool disabled)
292 {
293 componentRegistry.getComponent<components::Menu>(entityIdentifier)
294 .setItemDisabled(index, disabled);
295 apply(componentRegistry, entityIdentifier);
296 }
297
298 void Menu::show(ecs::ComponentRegistry &componentRegistry,
299 const ecs::Entity::Identifier &entityIdentifier)
300 {
301 componentRegistry.getComponent<components::Overlay>(entityIdentifier)
302 .setVisible(true);
303 apply(componentRegistry, entityIdentifier);
304 }
305
306 void Menu::hide(ecs::ComponentRegistry &componentRegistry,
307 const ecs::Entity::Identifier &entityIdentifier)
308 {
309 componentRegistry.getComponent<components::Overlay>(entityIdentifier)
310 .setVisible(false);
311 apply(componentRegistry, entityIdentifier);
312 }
313
314 void Menu::dismiss(ecs::ComponentRegistry &componentRegistry,
315 const ecs::Entity::Identifier &entityIdentifier)
316 {
317 auto &overlay = componentRegistry.getComponent<components::Overlay>(
318 entityIdentifier);
319
320 if (!overlay.isVisible()) {
321 return;
322 }
323 hide(componentRegistry, entityIdentifier);
324
325 // Copy: the handler may replace itself.
326 const auto onDismiss = overlay.getOnDismissHandler();
327 if (onDismiss) {
328 onDismiss();
329 }
330 }
331
332 void Menu::apply(ecs::ComponentRegistry &componentRegistry,
333 const ecs::Entity::Identifier &entityIdentifier)
334 {
335 const auto &menu =
336 componentRegistry.getComponent<components::Menu>(entityIdentifier);
337 const auto &rows = menu.getRows();
338 const auto &items = menu.getItems();
339 const bool elevated = menu.getMode() == Mode::Elevated;
340
341 std::vector<ecs::Entity::Identifier> children;
342 children.reserve(rows.size());
343 float contentWidth = 0.0f;
344 for (const auto &row: rows) {
345 children.push_back(row.view);
346 contentWidth =
347 std::max(contentWidth, contentWidthOf(componentRegistry, row));
348 }
349
350 // The width follows the widest row within the M3 range.
351 const float width = std::clamp(contentWidth, components::Menu::MinWidth,
353
354 auto &layout = componentRegistry.getComponent<components::Layout>(
355 entityIdentifier);
360 .setPadding(0.0f)
361 .setSpacing(0.0f)
362 .setFixedWidth(width)
363 .setChildren(children);
364
365 componentRegistry.getComponent<components::Borders>(entityIdentifier)
367 const bool open = isOpen(componentRegistry, entityIdentifier);
368 componentRegistry.getComponent<components::Elevation>(entityIdentifier)
369 .setElevationLevel(elevated && open
372 componentRegistry.getComponent<components::Color>(entityIdentifier)
373 .setColor(
374 !open ? transparentColor()
375 : elevated
377 : schemeColor(SchemeColorRole::SurfaceContainer));
378
379 componentRegistry.getComponent<components::Overlay>(entityIdentifier)
380 .setModal(false)
382 .setDismissOnEscape(true);
383
384 for (std::size_t index = 0; index < rows.size(); ++index) {
385 const auto &row = rows[index];
386 const bool dense = index < items.size() && items[index].dense;
387
388 componentRegistry.getComponent<components::Layout>(row.view)
394 .setSpacing(ItemSpacing)
395 .setPadding(ItemPadding)
396 .setFixedWidth(width)
397 .setFixedHeight(dense ? DenseItemHeight : ItemHeight)
398 .setChildren(row.content);
399 if (componentRegistry.hasComponent<components::Borders>(row.view)) {
400 componentRegistry.getComponent<components::Borders>(row.view)
401 .setBorderRadius(RowRadius);
402 }
403 if (index < items.size()) {
404 interaction::setEnabled(componentRegistry, row.view,
405 !items[index].disabled);
406 }
407 styleRow(componentRegistry, entityIdentifier, index);
408 }
409
410 // The rows are sized first, so the menu knows its height before it
411 // is anchored; everything is then placed at the anchored pose.
412 const auto layer = Layout::layerOf(componentRegistry, entityIdentifier);
413 arrangeRows(componentRegistry, rows);
414 Layout::apply(componentRegistry, entityIdentifier, children, layer);
415 applyAnchor(componentRegistry, entityIdentifier, menu);
416 Layout::apply(componentRegistry, entityIdentifier, children, layer);
417 arrangeRows(componentRegistry, rows);
418 }
419
420 void Menu::update(const ecs::Entity::Identifier &entityIdentifier)
421 {
422 if (!requireComponent<components::Menu>(entityIdentifier)) {
423 return;
424 }
425
426 apply(getComponentRegistry(), entityIdentifier);
427 }
428} // namespace guillaume::systems
What an entity means to a user who does not see it: its name, its role, its state and its place in th...
Accessibility & setFocusable(bool focusable)
Include the entity in the Tab traversal or leave it out.
Corner radii and outline stroke of a rectangular entity.
Definition borders.hpp:67
Main color of an entity: the fill of a shape, or the ink of a text or an icon.
Definition color.hpp:58
Soft shadow drawn around an elevated surface.
Definition elevation.hpp:63
How a container arranges its children: in a row or a column, with which alignment,...
Definition layout.hpp:69
Layout & setFixedWidth(float width)
Force the container width instead of wrapping the children.
Definition layout.cpp:112
Layout & setChildren(const std::vector< ecs::Entity::Identifier > &children)
Replace the list of children to arrange.
Definition layout.cpp:171
Layout & setAxis(Axis axis)
Choose between a row and a column.
Definition layout.cpp:32
Layout & setPadding(float padding)
Set the inset between the container's edges and its children.
Definition layout.cpp:92
Layout & setMainAxisAlignment(MainAxisAlignment alignment)
Set where the children go along the main axis.
Definition layout.cpp:47
@ Start
At the top (row) or left (column).
Definition layout.hpp:100
Layout & setFixedHeight(float height)
Force the container height instead of wrapping the children.
Definition layout.cpp:144
Layout & setCrossAxisAlignment(CrossAxisAlignment alignment)
Set where each child goes along the cross axis.
Definition layout.cpp:62
@ Start
Packed at the left (row) or top (column).
Definition layout.hpp:87
@ Vertical
Column: children placed top to bottom.
Definition layout.hpp:76
@ Horizontal
Row: children placed left to right.
Definition layout.hpp:75
Layout & setSpacing(float spacing)
Set the gap between two consecutive children.
Definition layout.cpp:77
State of a menu: a floating list of choices that opens next to an anchor.
Definition menu.hpp:59
static constexpr float MaxWidth
Largest width of a menu, in dp.
Definition menu.hpp:126
Mode
How the menu surface stands out from what is behind it.
Definition menu.hpp:70
AnchorPosition
Side of the anchor the menu opens on.
Definition menu.hpp:78
const std::vector< Row > & getRows(void) const noexcept
Get the entities built for the items.
Definition menu.cpp:97
static constexpr float MinWidth
Smallest width of a menu, in dp.
Definition menu.hpp:123
Marks an entity as something shown temporarily above the rest of the interface (a dialog,...
Definition overlay.hpp:55
Overlay & setDismissOnOutsideClick(bool dismiss)
Choose whether a click outside the overlay dismisses it.
Definition overlay.cpp:65
Overlay & setDismissOnEscape(bool dismiss)
Choose whether the Escape key dismisses the overlay.
Definition overlay.cpp:80
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.
bool hasComponent(const Entity::Identifier &entityIdentifier) const
Tell whether an entity has a component of a given type.
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
ecs::ComponentRegistry & getComponentRegistry(void)
Get the component registry of the scene being processed.
Definition system.cpp:53
ComponentType & getComponent(const ecs::Entity::Identifier &entityIdentifier)
Get a component of an entity from the bound registry, to read or modify it.
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...
Arranges the children of a container in a row or a column and sizes the container around them.
Definition layout.hpp:84
static void apply(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, std::uint32_t layer=0)
Arrange children inside a container and size the container.
Definition layout.cpp:126
static std::uint32_t layerOf(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Get the layer of an entity: its depth in the entity tree.
Definition layout.cpp:90
static void styleRow(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Recolor one row without sizing the menu again.
Definition menu.cpp:228
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
void update(const ecs::Entity::Identifier &entityIdentifier) override
Run apply() on one menu; called by the frame loop.
Definition menu.cpp:420
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 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
Menu(void)
Create the system in the Layout phase.
Definition menu.cpp:166
static bool isOpen(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether a menu is open.
Definition menu.cpp:218
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
static constexpr float get(unsigned int steps)
Get a spacing as a number of grid units.
Definition tokens.hpp:441
State. Every class here is plain data attached to an entity.
The entity-component-system core, independent of any widget.
Definition component.hpp:28
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit disabledContentColor(void)
Color of the icon, label or outline of a disabled widget.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
Rules. Every class here runs each frame on the entities that have the components it declares.
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit disabledContentColor(void)
Color of the icon, label or outline of a disabled widget.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
@ Level2
Second raised level.
Definition tokens.hpp:133
@ Level0
Flat: no shadow, no tint.
Definition tokens.hpp:131
@ ExtraSmall
4 dp (text fields, menus, snackbars).
Definition tokens.hpp:44
utility::graphic::Color32Bit getElevatedSurfaceColor(theme::ElevationLevel level)
Get the background color of a surface raised to an elevation level.
float getShapeRadius(theme::ShapeRole role)
Get the corner radius the active theme gives to a shape role.
Helpers of the namespace systems::interaction: what "pressable" means for a widget,...
bool isEnabled(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier)
Whether an entity accepts input.
void makeInteractive(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, components::AccessibilityRole role, std::function< void(void)> onPress, std::function< void(void)> onStateChange={})
Make an entity hoverable, pressable and focusable.
void setEnabled(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, bool enabled)
Enable or disable an entity.
utility::graphic::Color32Bit stateLayerColor(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, const utility::graphic::Color32Bit &base, const utility::graphic::Color32Bit &content)
Container color of a widget in its current input state.
Color helpers shared by the widget systems: scheme lookup, state layers and the disabled colors.