guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
navigation_bar.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_bar_destination.hpp"
24#include "guillaume/entities/navigation_bar.hpp"
25
26#include <memory>
27#include <utility>
28#include <vector>
29
30#include "guillaume/components/navigation_bar_destination.hpp"
31#include "guillaume/entities/builder_base.hpp"
32#include "guillaume/systems/navigation_bar.hpp"
33#include "guillaume/theme.hpp"
34
35namespace guillaume::entities
36{
37 namespace
38 {
40
47 std::vector<NavigationBar::Destination> toDestinations(
48 const std::vector<std::pair<std::string, std::string>> &pairs)
49 {
50 std::vector<NavigationBar::Destination> destinations;
51 destinations.reserve(pairs.size());
52 for (const auto &pair: pairs) {
53 destinations.push_back(NavigationBar::Destination {
54 pair.first, pair.second, "", "" });
55 }
56 return destinations;
57 }
58
67 ecs::Entity::Identifier destinationPart(
68 const ecs::ComponentRegistry &registry,
69 ecs::Entity::Identifier identifier, std::size_t index,
71 components::NavigationBarDestination::*getter)(void)
72 const noexcept)
73 {
74 const auto &destinations =
75 registry.getComponent<components::NavigationBar>(identifier)
76 .getDestinationEntities();
77
78 if (index >= destinations.size()
79 || !registry.hasComponent<components::NavigationBarDestination>(
80 destinations[index])) {
82 }
83 return (registry.getComponent<components::NavigationBarDestination>(
84 destinations[index])
85 .*getter)();
86 }
87 } // namespace
88
90 ecs::EntityRegistry &entityRegistry)
91 : EntityBuilderBase<NavigationBar>(componentRegistry, entityRegistry)
92 {
93 reset();
94 }
95
96 std::shared_ptr<NavigationBar> NavigationBar::Builder::buildEntity(void)
97 {
98 auto entity =
100 _variant, _specs, _onIndexChange);
101 return entity;
102 }
103
105 {
106 _config = SurfaceConfig();
107 _variant = Variant::WithLabels;
108 _destinations.clear();
109 _specs.clear();
110 _onIndexChange = {};
111
113 _config.mainAxisAlignment =
115 _config.crossAxisAlignment =
117 _config.padding = theme::SpacingScale::get(2);
118 _config.spacing = 0.0f;
119 _config.setFixedWidth(360.0f);
120 _config.setFixedHeight(components::NavigationBar::Height);
121 }
122
124 NavigationBar::Builder::withPose(const utility::graphic::PoseF &pose)
125 {
126 _config.pose = pose;
127 return *this;
128 }
129
131 {
132 _variant = variant;
133 return *this;
134 }
135
137 const std::string &iconGlyph, const std::string &label,
138 const std::string &focusedIconGlyph, const std::string &badge)
139 {
140 _destinations.emplace_back(iconGlyph, label);
141 _specs.push_back(
142 Destination { iconGlyph, label, focusedIconGlyph, badge });
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<NavigationBar> NavigationBar::Builder::makeNavigationBar(
154 std::shared_ptr<ecs::Entity> parent, Variant variant,
155 const std::vector<std::pair<std::string, std::string>> &destinations)
156 {
157 withVariant(variant);
158
159 for (const auto &destination: destinations) {
160 addDestination(destination.first, destination.second);
161 }
162
163 return registerEntity(parent);
164 }
165
166 NavigationBar::NavigationBar(
167 ecs::ComponentRegistry &registry, const SurfaceConfig &config,
168 Variant variant,
169 const std::vector<std::pair<std::string, std::string>> &destinations)
170 : NavigationBar(registry, config, variant, toDestinations(destinations),
171 {})
172 {
173 }
174
175 NavigationBar::NavigationBar(ecs::ComponentRegistry &registry,
176 const SurfaceConfig &config, Variant variant,
177 const std::vector<Destination> &destinations,
178 std::function<void(std::size_t)> onIndexChange)
179 : SurfaceBase<components::SelectionGroup, components::NavigationBar>(
180 registry, config)
181 {
184 .setVariant(variant)
185 .setDestinations(destinations)
186 .setOnIndexChange(std::move(onIndexChange));
188 getIdentifier());
190 }
191
195
196 void NavigationBar::buildDestinations(void)
197 {
198 // Children need the owning handle as their parent.
199 if (weak_from_this().expired()) {
200 return;
201 }
202
203 auto &registry = getComponentRegistry();
204 // Copy: building children may move the component storage.
205 const std::vector<Destination> destinations =
207 .getDestinations();
208 std::vector<ecs::Entity::Identifier> identifiers =
210 .getDestinationEntities();
211
212 // systems::NavigationBar sizes the destinations and wires their
213 // press and selection change.
214 for (std::size_t index = identifiers.size();
215 index < destinations.size(); ++index) {
216 const auto destination =
217 BarDestination::create(registry, destinations[index]);
218 destination->setParent(shared_from_this());
219 addEntity(destination);
220 identifiers.push_back(destination->getIdentifier());
221 }
222
223 registry.getComponent<components::NavigationBar>(getIdentifier())
224 .setDestinationEntities(identifiers);
225
226 // Hand the layout children to the surface.
227 Children children;
228 for (const auto identifier: identifiers) {
229 if (auto destination = getEntity<BarDestination>(identifier)) {
230 children.push_back(std::move(destination));
231 }
232 }
233 setChildren(children);
234
236 }
237
246
253
254 NavigationBar &NavigationBar::addDestination(const std::string &iconGlyph,
255 const std::string &label)
256 {
257 return addDestination(Destination { iconGlyph, label, "", "" });
258 }
259
260 NavigationBar &NavigationBar::addDestination(const Destination &destination)
261 {
264 .addDestination(destination);
265 // A new destination needs its child entity.
266 buildDestinations();
268 0);
270 return *this;
271 }
272
273 NavigationBar &NavigationBar::setBadge(std::size_t index,
274 const std::string &badge)
275 {
276 auto &registry = getComponentRegistry();
277 const auto &bar =
279
280 if (index >= bar.getDestinations().size()) {
281 return *this;
282 }
283
284 // A first badge label needs the badge child, which only the
285 // destination entity can build.
286 const auto &destinations = bar.getDestinationEntities();
287 const auto destination = index < destinations.size()
288 ? getEntity<BarDestination>(destinations[index])
289 : nullptr;
290 if (destination != nullptr) {
291 destination->setBadge(badge);
292 }
294 badge);
295 return *this;
296 }
297
299 std::function<void(std::size_t)> onIndexChange)
300 {
303 .setOnIndexChange(std::move(onIndexChange));
304 return *this;
305 }
306
308 std::function<void(std::size_t)> onTabPress)
309 {
312 .setOnTabPress(std::move(onTabPress));
313 return *this;
314 }
315
316 NavigationBar &NavigationBar::select(std::size_t index)
317 {
319 index);
320 return *this;
321 }
322
328
330 {
331 return getComponentRegistry()
333 .getDestinations()
334 .size();
335 }
336
339 {
340 const auto &destinations =
343 .getDestinationEntities();
344
345 return index < destinations.size() ? destinations[index]
347 }
348
351 {
352 return destinationPart(
355 }
356
358 NavigationBar::getIconIdentifier(std::size_t index) const
359 {
360 return destinationPart(
363 }
364
366 NavigationBar::getLabelIdentifier(std::size_t index) const
367 {
368 return destinationPart(
371 }
372
374 NavigationBar::getBadgeIdentifier(std::size_t index) const
375 {
376 return destinationPart(
379 }
380
381 void NavigationBar::build(void)
382 {
383 buildDestinations();
385 0);
387 }
388
389} // namespace guillaume::entities
@ Horizontal
Row: children placed left to right.
Definition layout.hpp:75
ecs::Entity::Identifier getIndicator(void) const noexcept
Get the pill drawn behind the icon of the selected destination.
ecs::Entity::Identifier getIconEntity(void) const noexcept
Get the child that draws the icon.
ecs::Entity::Identifier getBadgeEntity(void) const noexcept
Get the child that draws the badge.
ecs::Entity::Identifier getLabelEntity(void) const noexcept
Get the child that draws the label.
State of a navigation bar: the bottom strip of three to five destinations that switches between the t...
static constexpr float Height
Height of the bar, in dp.
const std::vector< ecs::Entity::Identifier > & getDestinationEntities(void) const noexcept
Get the destination children.
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.
ComponentRegistry & getComponentRegistry(void)
Get the registry in which the builder creates components.
Owns entities and gives the systems the list of entities to visit.
void addEntity(std::shared_ptr< Entity > entity)
Make this registry own an entity, so that it stays alive and systems visit it.
std::shared_ptr< EntityType > getEntity(Entity::Identifier identifier)
Find an entity owned directly by this registry, by identifier.
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< BarDestination > create(Arguments &&...arguments)
Create a destination and its children, without registering it in an entity registry or setting its pa...
std::shared_ptr< NavigationBar > registerEntity(std::shared_ptr< ecs::Entity > parent)
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Configures a NavigationBar, creates it and registers it in an entity registry.
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.
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)
One destination of a NavigationBar: a pressable column with an active-indicator pill around the icon,...
static void setBadge(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, const std::string &badge)
Set the badge of a destination and restyle that destination.
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Connect a navigation bar to its destinations.
static std::size_t selectedIndex(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Get the index of the selected destination.
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Color the bar, size and style its destinations and place them in a row.
static void select(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Select a destination from code.
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.
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
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