guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
navigation_drawer.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 <cstddef>
26#include <functional>
27#include <memory>
28#include <string>
29#include <utility>
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/navigation_drawer.hpp"
39#include "guillaume/components/overlay.hpp"
40#include "guillaume/components/selection.hpp"
41
42#include "guillaume/entities/backdrop.hpp"
43#include "guillaume/entities/builder_base.hpp"
44#include "guillaume/entities/surface.hpp"
45
46namespace guillaume::entities
47{
48
105 class NavigationDrawer:
106 public SurfaceBase<components::Overlay, components::SelectionGroup,
107 components::NavigationDrawer>
108 {
109 public:
113
116
120
125 class Builder: public EntityBuilderBase<NavigationDrawer>
126 {
127 private:
128 SurfaceConfig _config;
129 Variant _variant { Variant::Standard };
130 std::vector<Entry> _entries {};
131 std::function<void(std::size_t)>
132 _onIndexChange {};
133
134 public:
141 Builder(ecs::ComponentRegistry &componentRegistry,
142 ecs::EntityRegistry &entityRegistry);
143
149 std::shared_ptr<NavigationDrawer> buildEntity(void) override;
150
159 void reset(void) override;
160
167 Builder &withPose(const utility::graphic::PoseF &pose);
168
175 Builder &withVariant(Variant variant);
176
188 Builder &addDestination(const std::string &iconGlyph,
189 const std::string &label,
190 const std::string &right = "",
191 bool disabled = false);
192
200 Builder &addSection(const std::string &title);
201
207 Builder &addDivider(void);
208
218 std::function<void(std::size_t)> onIndexChange);
219
233 std::shared_ptr<NavigationDrawer> makeNavigationDrawer(
234 std::shared_ptr<ecs::Entity> parent, Variant variant,
235 const std::vector<std::pair<std::string, std::string>>
236 &destinations);
237 };
238
254 template<typename... Arguments> static std::shared_ptr<NavigationDrawer>
255 create(Arguments &&...arguments)
256 {
257 std::shared_ptr<NavigationDrawer> entity(
258 new NavigationDrawer(std::forward<Arguments>(arguments)...));
259 entity->build();
260 return entity;
261 }
262
266 ~NavigationDrawer(void) override;
267
282
287 Variant getVariant(void) const;
288
298 NavigationDrawer &select(std::size_t index);
299
305 std::size_t getSelectedIndex(void) const;
306
317 NavigationDrawer &setDestinationDisabled(std::size_t index,
318 bool disabled);
319
329 setOnIndexChange(std::function<void(std::size_t)> onIndexChange);
330
335 NavigationDrawer &open(void);
336
341 NavigationDrawer &close(void);
342
347 bool isOpen(void) const;
348
357 NavigationDrawer &show(void);
358
366 NavigationDrawer &hide(void);
367
373 bool isVisible(void) const;
374
379 std::size_t getDestinationCount(void) const;
380
389 getDestinationIdentifier(std::size_t index) const;
390
399 ecs::Entity::Identifier getRightIdentifier(std::size_t index) const;
400
407 std::size_t getSectionCount(void) const;
408
415 ecs::Entity::Identifier getSectionIdentifier(std::size_t index) const;
416
421 std::size_t getDividerCount(void) const;
422
433
434 private:
442 void buildDestinations(void);
443
444 private:
455 const SurfaceConfig &config, Variant variant,
456 const std::vector<std::pair<std::string, std::string>>
457 &destinations);
458
473 const SurfaceConfig &config, Variant variant,
474 const std::vector<Entry> &entries,
475 std::function<void(std::size_t)> onIndexChange);
476
484 void build(void);
485 };
486
487} // namespace guillaume::entities
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)
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.
components::NavigationDrawer::EntryKind EntryKind
Kind of a drawer entry: destination, section title or divider.
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.
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
Description of one drawer entry, as given by the user.
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