guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
menu.hpp
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#pragma once
24
25#include <utility>
26#include <cstddef>
27#include <functional>
28#include <memory>
29#include <string>
30#include <vector>
31
32#include <utility/graphic/color.hpp>
33#include <utility/graphic/pose.hpp>
34
35#include "guillaume/ecs/component_registry.hpp"
36#include "guillaume/ecs/entity_builder.hpp"
37
38#include "guillaume/components/accessibility.hpp"
39#include "guillaume/components/elevation.hpp"
40#include "guillaume/components/menu.hpp"
41#include "guillaume/components/overlay.hpp"
42
43#include "guillaume/entities/builder_base.hpp"
44#include "guillaume/entities/surface.hpp"
45#include "guillaume/entities/text.hpp"
46#include "guillaume/entities/view.hpp"
47
48namespace guillaume::entities
49{
50
103 class Menu:
104 public SurfaceBase<components::Overlay, components::Elevation,
105 components::Accessibility, components::Menu>
106 {
107 public:
110
114
118
122
124 static constexpr float MinWidth = components::Menu::MinWidth;
125
127 static constexpr float MaxWidth = components::Menu::MaxWidth;
128
133 class Builder: public EntityBuilderBase<Menu>
134 {
135 private:
136 SurfaceConfig _config;
137 Variant _variant { Variant::Dropdown };
138 std::vector<Item> _items {};
139
140 public:
147 Builder(ecs::ComponentRegistry &componentRegistry,
148 ecs::EntityRegistry &entityRegistry);
149
155 std::shared_ptr<Menu> buildEntity(void) override;
156
164 void reset(void) override;
165
172 Builder &withPose(const utility::graphic::PoseF &pose);
173
179 Builder &withVariant(Variant variant);
180
188 Builder &addItem(const std::string &label,
189 const std::string &leadingIcon = "");
190
197 Builder &addItem(const Item &item);
198
212 std::shared_ptr<Menu> makeMenu(std::shared_ptr<ecs::Entity> parent,
213 Variant variant,
214 const std::vector<Item> &items);
215 };
216
229 template<typename... Arguments>
230 static std::shared_ptr<Menu> create(Arguments &&...arguments)
231 {
232 std::shared_ptr<Menu> entity(
233 new Menu(std::forward<Arguments>(arguments)...));
234 entity->build();
235 return entity;
236 }
237
241 ~Menu(void) override = default;
242
251 Menu &setVariant(Variant variant);
252
257 Variant getVariant(void) const;
258
265 Menu &setMode(Mode mode);
266
271 Mode getMode(void) const;
272
282 Menu &setItems(const std::vector<Item> &items);
283
288 std::size_t getItemCount(void) const;
289
297 ecs::Entity::Identifier getItemIdentifier(std::size_t index) const;
298
308 Menu &setItemDisabled(std::size_t index, bool disabled);
309
322
329
337 Menu &setAnchorPosition(AnchorPosition position);
338
344
354 Menu &setOnDismiss(std::function<void(void)> onDismiss);
355
363 Menu &dismiss(void);
364
369 Menu &open(void);
370
376 Menu &close(void);
377
382 bool isOpen(void) const;
383
388 Menu &show(void);
389
394 Menu &hide(void);
395
401 bool isVisible(void) const;
402
403 private:
412 void buildItems(void);
413
414 private:
425 Menu(ecs::ComponentRegistry &registry, const SurfaceConfig &config,
426 Variant variant, const std::vector<Item> &items);
427
434 void build(void);
435 };
436
437} // namespace guillaume::entities
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
Variant
Kind of menu. It is stored for the application; the menu system styles and places every kind alike.
Definition menu.hpp:65
static constexpr float MinWidth
Smallest width of a menu, in dp.
Definition menu.hpp:123
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
Owns entities and gives the systems the list of entities to visit.
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
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
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(void) override=default
Default destructor.
static constexpr float MaxWidth
Largest M3 menu width, in dp.
Definition menu.hpp:127
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
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
Description of one menu item, as given by the user.
Definition menu.hpp:86
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