guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
navigation_drawer.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/entities/navigation_drawer_destination.hpp"
24#include "guillaume/entities/navigation_drawer.hpp"
25
26#include <memory>
27#include <utility>
28#include <vector>
29
30#include "guillaume/components/navigation_drawer_destination.hpp"
31#include "guillaume/entities/builder_base.hpp"
32#include "guillaume/entities/content_helpers.hpp"
33#include "guillaume/entities/divider.hpp"
35#include "guillaume/entities/text.hpp"
36#include "guillaume/systems/navigation_drawer.hpp"
37#include "guillaume/theme.hpp"
38
39namespace guillaume::entities
40{
41 namespace
42 {
44
50 std::vector<NavigationDrawer::Entry> toEntries(
51 const std::vector<std::pair<std::string, std::string>> &pairs)
52 {
53 std::vector<NavigationDrawer::Entry> entries;
54 entries.reserve(pairs.size());
55 for (const auto &pair: pairs) {
57 entry.icon = pair.first;
58 entry.label = pair.second;
59 entries.push_back(entry);
60 }
61 return entries;
62 }
63 } // namespace
64
66 ecs::ComponentRegistry &componentRegistry,
67 ecs::EntityRegistry &entityRegistry)
68 : EntityBuilderBase<NavigationDrawer>(componentRegistry, entityRegistry)
69 {
70 reset();
71 }
72
73 std::shared_ptr<NavigationDrawer>
75 {
76 auto entity =
78 _variant, _entries, _onIndexChange);
79 return entity;
80 }
81
83 {
84 _config = SurfaceConfig();
85 _variant = Variant::Standard;
86 _entries.clear();
87 _onIndexChange = {};
88
90 _config.mainAxisAlignment =
92 _config.crossAxisAlignment =
94 _config.padding = systems::NavigationDrawer::Padding;
95 _config.spacing = systems::NavigationDrawer::Spacing;
96 _config.setFixedWidth(components::NavigationDrawer::Width);
97 _config.setFixedHeight(components::NavigationDrawer::Height);
98 }
99
101 NavigationDrawer::Builder::withPose(const utility::graphic::PoseF &pose)
102 {
103 _config.pose = pose;
104 return *this;
105 }
106
109 {
110 _variant = variant;
111 return *this;
112 }
113
115 const std::string &iconGlyph, const std::string &label,
116 const std::string &right, bool disabled)
117 {
118 Entry entry;
119 entry.kind = EntryKind::Destination;
120 entry.icon = iconGlyph;
121 entry.label = label;
122 entry.right = right;
123 entry.disabled = disabled;
124 _entries.push_back(entry);
125 return *this;
126 }
127
130 {
131 Entry entry;
132 entry.kind = EntryKind::Section;
133 entry.label = title;
134 _entries.push_back(entry);
135 return *this;
136 }
137
139 {
140 Entry entry;
141 entry.kind = EntryKind::Divider;
142 _entries.push_back(entry);
143 return *this;
144 }
145
147 std::function<void(std::size_t)> onIndexChange)
148 {
149 _onIndexChange = std::move(onIndexChange);
150 return *this;
151 }
152
153 std::shared_ptr<NavigationDrawer>
155 std::shared_ptr<ecs::Entity> parent, Variant variant,
156 const std::vector<std::pair<std::string, std::string>>
157 &destinations)
158 {
159 withVariant(variant);
160
161 for (const auto &destination: destinations) {
162 addDestination(destination.first, destination.second);
163 }
164
165 return registerEntity(parent);
166 }
167
168 NavigationDrawer::NavigationDrawer(
169 ecs::ComponentRegistry &registry, const SurfaceConfig &config,
170 Variant variant,
171 const std::vector<std::pair<std::string, std::string>> &destinations)
172 : NavigationDrawer(registry, config, variant, toEntries(destinations),
173 {})
174 {
175 }
176
177 NavigationDrawer::NavigationDrawer(
178 ecs::ComponentRegistry &registry, const SurfaceConfig &config,
179 Variant variant, const std::vector<Entry> &entries,
180 std::function<void(std::size_t)> onIndexChange)
181 : SurfaceBase<components::Overlay, components::SelectionGroup,
182 components::NavigationDrawer>(registry, config)
183 {
186 .setVariant(variant)
187 .setEntries(entries)
188 .setOnIndexChange(std::move(onIndexChange));
190 getIdentifier());
192 getIdentifier());
193 }
194
198
199 void NavigationDrawer::buildDestinations(void)
200 {
201 // Children need the owning handle as their parent.
202 if (weak_from_this().expired()) {
203 return;
204 }
205
206 auto &registry = getComponentRegistry();
207 // Copy: building children may move the component storage.
208 const std::vector<Entry> entries =
210 .getEntries();
211 const bool collapsed =
213 .getVariant()
214 == Variant::Collapsed;
215 const float itemWidth =
216 systems::NavigationDrawer::widthOf(collapsed ? Variant::Collapsed
217 : Variant::Standard)
219
221 .getBackdrop()
223 const auto backdrop = Backdrop::create(registry);
224 backdrop->setParent(shared_from_this());
225 addEntity(backdrop);
227 .setBackdrop(backdrop->getIdentifier());
228 }
229
230 // Remove the entries of a previous build (a rail and a sheet use
231 // different children); the backdrop is kept.
232 const auto previousEntries =
233 registry.getComponent<components::NavigationDrawer>(getIdentifier())
234 .getEntryEntities();
235 for (const auto previous: previousEntries) {
236 removeEntity(previous);
237 }
238
239 Children children;
240 std::vector<ecs::Entity::Identifier> entryIdentifiers;
241 std::vector<ecs::Entity::Identifier> destinationIdentifiers;
242 std::vector<ecs::Entity::Identifier> sectionIdentifiers;
243 std::vector<ecs::Entity::Identifier> dividerIdentifiers;
244
245 for (const auto &entry: entries) {
246 std::shared_ptr<ecs::Entity> child;
247
248 switch (entry.kind) {
249 case EntryKind::Section: {
250 // A rail has no room for section titles.
251 // systems::NavigationDrawer::install gives the header
252 // its semantics.
253 if (collapsed) {
254 break;
255 }
256 child = buildText(
257 registry, *this, shared_from_this(), entry.label,
259 schemeColor(SchemeColorRole::OnSurfaceVariant));
260 if (child != nullptr) {
261 sectionIdentifiers.push_back(child->getIdentifier());
262 }
263 break;
264 }
265 case EntryKind::Divider: {
266 Divider::Builder builder(registry, *this);
267 child = builder.makeDivider(shared_from_this(), itemWidth,
268 Divider::Variant::FullWidth);
269 if (child != nullptr) {
270 dividerIdentifiers.push_back(child->getIdentifier());
271 }
272 break;
273 }
274 case EntryKind::Destination:
275 default: {
276 // systems::NavigationDrawer::install wires its press
277 // and selection change.
278 child = DrawerDestination::create(registry, entry,
279 collapsed, itemWidth);
280 child->setParent(shared_from_this());
281 addEntity(child);
282 destinationIdentifiers.push_back(child->getIdentifier());
283 break;
284 }
285 }
286
287 if (child != nullptr) {
288 entryIdentifiers.push_back(child->getIdentifier());
289 children.push_back(std::move(child));
290 }
291 }
292
293 registry.getComponent<components::NavigationDrawer>(getIdentifier())
294 .setEntryEntities(entryIdentifiers)
295 .setDestinationEntities(destinationIdentifiers)
296 .setSectionEntities(sectionIdentifiers)
297 .setDividerEntities(dividerIdentifiers);
298
299 // Hand the layout children to the surface.
300 setChildren(children);
301
303 }
304
305 NavigationDrawer &NavigationDrawer::setVariant(Variant variant)
306 {
307 auto &registry = getComponentRegistry();
308 const Variant previous =
310 .getVariant();
311 const bool rebuild =
312 (variant == Variant::Collapsed) != (previous == Variant::Collapsed);
313 const std::size_t selected =
315
317 .setVariant(variant);
318 // A rail and a sheet are made of different children.
319 if (rebuild
320 && !registry
321 .getComponent<components::NavigationDrawer>(getIdentifier())
322 .getDestinationEntities()
323 .empty()) {
324 buildDestinations();
326 selected);
327 }
329 return *this;
330 }
331
338
339 NavigationDrawer &NavigationDrawer::select(std::size_t index)
340 {
342 getIdentifier(), index);
343 return *this;
344 }
345
351
354 bool disabled)
355 {
357 getComponentRegistry(), getIdentifier(), index, disabled);
358 return *this;
359 }
360
362 std::function<void(std::size_t)> onIndexChange)
363 {
366 .setOnIndexChange(std::move(onIndexChange));
367 return *this;
368 }
369
370 NavigationDrawer &NavigationDrawer::show(void)
371 {
373 getIdentifier());
374 return *this;
375 }
376
377 NavigationDrawer &NavigationDrawer::hide(void)
378 {
380 getIdentifier());
381 return *this;
382 }
383
390
391 NavigationDrawer &NavigationDrawer::open(void)
392 {
393 return show();
394 }
395
396 NavigationDrawer &NavigationDrawer::close(void)
397 {
398 return hide();
399 }
400
402 {
403 return isVisible();
404 }
405
412
415 {
416 const auto &destinations =
419 .getDestinationEntities();
420
421 return index < destinations.size() ? destinations[index]
423 }
424
427 {
428 const auto &registry = getComponentRegistry();
429 const auto destination = getDestinationIdentifier(index);
430
432 destination)) {
434 }
435 return registry
437 .getRightEntity();
438 }
439
440 std::size_t NavigationDrawer::getSectionCount(void) const
441 {
442 return getComponentRegistry()
444 .getSectionEntities()
445 .size();
446 }
447
450 {
451 const auto &sections =
454 .getSectionEntities();
455
456 return index < sections.size() ? sections[index]
458 }
459
460 std::size_t NavigationDrawer::getDividerCount(void) const
461 {
462 return getComponentRegistry()
464 .getDividerEntities()
465 .size();
466 }
467
474
475 void NavigationDrawer::build(void)
476 {
477 auto &registry = getComponentRegistry();
478
480 .getDestinationEntities()
481 .empty()) {
482 buildDestinations();
483 }
485 getIdentifier());
486 }
487
488} // 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 one destination of a navigation drawer: an icon, a label and an optional text at the trailin...
State of a navigation drawer: the side sheet that lists the destinations of an app,...
static constexpr float Width
Width of a standard or modal drawer, in dp.
static constexpr float Height
Height of the drawer, in dp.
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.
bool hasComponent(const Entity::Identifier &entityIdentifier) const
Tell whether an entity has a component of a given type.
ComponentRegistry & getComponentRegistry(void)
Get the registry in which the builder creates components.
Owns entities and gives the systems the list of entities to visit.
bool removeEntity(Entity::Identifier identifier)
Remove an entity, with its children and all their components.
void addEntity(std::shared_ptr< Entity > entity)
Make this registry own an entity, so that it stays alive and systems visit it.
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
static std::shared_ptr< Backdrop > create(Arguments &&...arguments)
Build a hidden backdrop without registering it in an entity registry.
Definition backdrop.hpp:100
static std::shared_ptr< DrawerDestination > create(Arguments &&...arguments)
Create a destination and its children, without registering it in an entity registry or setting its pa...
std::shared_ptr< NavigationDrawer > registerEntity(std::shared_ptr< ecs::Entity > parent)
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Configures a NavigationDrawer, creates it and registers it in an entity registry.
Builder & withPose(const utility::graphic::PoseF &pose)
Set where the drawer is placed.
Builder & addDivider(void)
Append a horizontal divider after the entries already added.
Builder & withVariant(Variant variant)
Set the variant.
void reset(void) override
Restore the defaults.
Builder & addDestination(const std::string &iconGlyph, const std::string &label, const std::string &right="", bool disabled=false)
Append a destination after the entries already added.
std::shared_ptr< NavigationDrawer > buildEntity(void) override
Build a drawer and its children from the current configuration, without registering it or setting its...
Builder & addSection(const std::string &title)
Append a section title after the entries already added.
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Create a builder set to the defaults of reset().
std::shared_ptr< NavigationDrawer > makeNavigationDrawer(std::shared_ptr< ecs::Entity > parent, Variant variant, const std::vector< std::pair< std::string, std::string > > &destinations)
Build a drawer, register it under parent and reset the builder.
Builder & withOnIndexChange(std::function< void(std::size_t)> onIndexChange)
Set the handler called when the user selects another destination.
A side sheet listing destinations, of which exactly one is selected, with optional section titles and...
NavigationDrawer & setDestinationDisabled(std::size_t index, bool disabled)
Enable or disable a destination. Restyles it at once.
NavigationDrawer & select(std::size_t index)
Select a destination and deselect the others.
components::NavigationDrawer::Variant Variant
Variant getVariant(void) const
Get the variant.
NavigationDrawer & close(void)
Close the drawer. Same as hide().
NavigationDrawer & open(void)
Open the drawer. Same as show().
static std::shared_ptr< NavigationDrawer > create(Arguments &&...arguments)
Create a drawer and its children, without registering it in an entity registry.
std::size_t getSelectedIndex(void) const
Get the index of the selected destination.
~NavigationDrawer(void) override
Default destructor.
bool isOpen(void) const
Whether the drawer is open. Same as isVisible().
NavigationDrawer & hide(void)
Hide the drawer and its backdrop.
ecs::Entity::Identifier getDestinationIdentifier(std::size_t index) const
Get the child entity of a destination: its pressable row.
NavigationDrawer & setVariant(Variant variant)
Change the variant.
std::size_t getDividerCount(void) const
Get the number of dividers.
components::NavigationDrawer::Entry Entry
NavigationDrawer & show(void)
Show the drawer, and its backdrop when the variant is Modal.
ecs::Entity::Identifier getBackdropIdentifier(void) const
Get the backdrop: the child that dims what is behind an open Modal drawer.
std::size_t getSectionCount(void) const
Get the number of section titles built.
bool isVisible(void) const
Whether the drawer is shown.
std::size_t getDestinationCount(void) const
Get the number of destinations.
NavigationDrawer & setOnIndexChange(std::function< void(std::size_t)> onIndexChange)
Set the handler called when the user selects another destination.
ecs::Entity::Identifier getRightIdentifier(std::size_t index) const
Get the trailing text entity of a destination.
ecs::Entity::Identifier getSectionIdentifier(std::size_t index) const
Get the text entity of a section title.
One destination of a NavigationDrawer: a pressable row with an icon, a label and an optional trailing...
static float widthOf(components::NavigationDrawer::Variant variant)
Get the drawer width of a variant, in dp.
static constexpr float Spacing
Gap between two stacked entries: 4 dp.
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Shape and color the drawer, style its destinations, stack its entries and place its backdrop.
static void select(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Select a destination from code.
static void hide(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Hide the drawer and its backdrop.
static void setDestinationDisabled(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, bool disabled)
Enable or disable one destination and restyle it.
static void show(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Show the drawer, and its backdrop when it is modal.
static void selectFirstEnabled(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Select the first destination that is not disabled, then restyle.
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Connect a navigation drawer to its destinations and section headers.
static constexpr float Padding
Space between the edge of the drawer and its entries: 12 dp.
static std::size_t selectedIndex(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Get the index of the selected destination.
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.
@ TitleSmall
14 / 20, medium weight.
Definition typescale.hpp:56
std::string label
Destination label or section title.
std::string icon
Icon glyph name of a destination.
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