guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
navigation_bar.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_bar.hpp"
39#include "guillaume/components/selection.hpp"
40
41#include "guillaume/entities/builder_base.hpp"
42#include "guillaume/entities/surface.hpp"
43
44namespace guillaume::entities
45{
46
94 class NavigationBar:
95 public SurfaceBase<components::SelectionGroup,
96 components::NavigationBar>
97 {
98 public:
102
106
111 class Builder: public EntityBuilderBase<NavigationBar>
112 {
113 private:
114 SurfaceConfig _config;
115 Variant _variant { Variant::WithLabels };
116 std::vector<std::pair<std::string, std::string>>
117 _destinations {};
118 std::vector<Destination> _specs {};
119 std::function<void(std::size_t)>
120 _onIndexChange {};
121
122 public:
129 Builder(ecs::ComponentRegistry &componentRegistry,
130 ecs::EntityRegistry &entityRegistry);
131
138 std::shared_ptr<NavigationBar> buildEntity(void) override;
139
147 void reset(void) override;
148
155 Builder &withPose(const utility::graphic::PoseF &pose);
156
164 Builder &withVariant(Variant variant);
165
176 Builder &addDestination(const std::string &iconGlyph,
177 const std::string &label,
178 const std::string &focusedIconGlyph = "",
179 const std::string &badge = "");
180
189 std::function<void(std::size_t)> onIndexChange);
190
204 std::shared_ptr<NavigationBar> makeNavigationBar(
205 std::shared_ptr<ecs::Entity> parent, Variant variant,
206 const std::vector<std::pair<std::string, std::string>>
207 &destinations);
208 };
209
210 private:
218 void buildDestinations(void);
219
220 public:
236 template<typename... Arguments>
237 static std::shared_ptr<NavigationBar> create(Arguments &&...arguments)
238 {
239 std::shared_ptr<NavigationBar> entity(
240 new NavigationBar(std::forward<Arguments>(arguments)...));
241 entity->build();
242 return entity;
243 }
244
248 ~NavigationBar(void) override;
249
257
262 Variant getVariant(void) const;
263
272 NavigationBar &addDestination(const std::string &iconGlyph,
273 const std::string &label);
274
285 NavigationBar &addDestination(const Destination &destination);
286
298 NavigationBar &setBadge(std::size_t index, const std::string &badge);
299
309 setOnIndexChange(std::function<void(std::size_t)> onIndexChange);
310
319 setOnTabPress(std::function<void(std::size_t)> onTabPress);
320
328 ecs::Entity::Identifier getIndicatorIdentifier(std::size_t index) const;
329
337 ecs::Entity::Identifier getIconIdentifier(std::size_t index) const;
338
346 ecs::Entity::Identifier getLabelIdentifier(std::size_t index) const;
347
355 ecs::Entity::Identifier getBadgeIdentifier(std::size_t index) const;
356
365 NavigationBar &select(std::size_t index);
366
372 std::size_t getSelectedIndex(void) const;
373
378 std::size_t getDestinationCount(void) const;
379
388 getDestinationIdentifier(std::size_t index) const;
389
390 private:
401 const SurfaceConfig &config, Variant variant,
402 const std::vector<std::pair<std::string, std::string>>
403 &destinations);
404
418 const SurfaceConfig &config, Variant variant,
419 const std::vector<Destination> &destinations,
420 std::function<void(std::size_t)> onIndexChange);
421
429 void build(void);
430 };
431
432} // namespace guillaume::entities
Variant
Whether every destination shows its label (WithLabels) or only the selected one does (WithoutLabels).
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< NavigationBar > buildEntity(void) override
Build a navigation bar and its destinations from the current configuration, without registering it or...
Builder & withOnIndexChange(std::function< void(std::size_t)> onIndexChange)
Set the handler called when the user selects another destination (Paper onIndexChange).
Builder & withPose(const utility::graphic::PoseF &pose)
Set where the bar is placed.
std::shared_ptr< NavigationBar > makeNavigationBar(std::shared_ptr< ecs::Entity > parent, Variant variant, const std::vector< std::pair< std::string, std::string > > &destinations)
Build a navigation bar, register it under parent and reset the builder.
Builder & addDestination(const std::string &iconGlyph, const std::string &label, const std::string &focusedIconGlyph="", const std::string &badge="")
Append a destination after the ones already added.
Builder & withVariant(Variant variant)
Set the variant.
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Create a builder set to the defaults of reset().
void reset(void) override
Restore the defaults.
A bottom bar of destinations (icon, label, optional badge) of which exactly one is selected.
NavigationBar & setOnTabPress(std::function< void(std::size_t)> onTabPress)
Set the handler called on every destination press, even on the selected one (Paper onTabPress).
std::size_t getSelectedIndex(void) const
Get the index of the selected destination.
components::NavigationBar::Destination Destination
ecs::Entity::Identifier getBadgeIdentifier(std::size_t index) const
Get the badge entity of a destination.
NavigationBar & setOnIndexChange(std::function< void(std::size_t)> onIndexChange)
Set the handler called when the user selects another destination (Paper onIndexChange).
components::NavigationBar::Variant Variant
NavigationBar & addDestination(const std::string &iconGlyph, const std::string &label)
Append a destination without focused icon or badge.
ecs::Entity::Identifier getLabelIdentifier(std::size_t index) const
Get the label entity of a destination.
NavigationBar & setVariant(Variant variant)
Change the variant. Restyles at once.
NavigationBar & setBadge(std::size_t index, const std::string &badge)
Change the badge label of a destination.
Variant getVariant(void) const
Get the variant.
std::size_t getDestinationCount(void) const
Get the number of destinations.
ecs::Entity::Identifier getIconIdentifier(std::size_t index) const
Get the icon entity of a destination.
NavigationBar & select(std::size_t index)
Select a destination and deselect the others.
ecs::Entity::Identifier getIndicatorIdentifier(std::size_t index) const
Get the active-indicator pill of a destination: the rounded shape behind the icon.
static std::shared_ptr< NavigationBar > create(Arguments &&...arguments)
Create a navigation bar and its destination children, without registering it in an entity registry.
ecs::Entity::Identifier getDestinationIdentifier(std::size_t index) const
Get the child entity of a destination: the pressable area holding its indicator, icon and label.
~NavigationBar(void) override
Default destructor.
SurfaceBase(ecs::ComponentRegistry &registry, const SurfaceConfig &config)
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
Description of one destination, 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