guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
loading_indicator.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/loading_indicator.hpp"
24
25#include <stdexcept>
26
27#include <memory>
28
29#include "guillaume/ecs/entity_filler.hpp"
30
31#include "guillaume/components/animation.hpp"
32#include "guillaume/components/arc.hpp"
33#include "guillaume/components/borders.hpp"
34#include "guillaume/components/bound.hpp"
35#include "guillaume/components/color.hpp"
36#include "guillaume/components/transform.hpp"
37
38#include "guillaume/entities/builder_base.hpp"
40#include "guillaume/systems/loading_indicator.hpp"
41#include "guillaume/theme.hpp"
42
43namespace guillaume::entities
44{
45 namespace
46 {
47 constexpr float LinearHeight =
49 constexpr float LinearWidth = components::LoadingIndicator::LinearWidth;
50 const float LinearRadius = getShapeRadius(theme::ShapeRole::Full);
51 constexpr float CircularSize =
53
57 class LinearBar:
58 public ecs::EntityFiller<components::Transform, components::Bound,
59 components::Color, components::Borders,
60 components::Animation>
61 {
62 public:
67 explicit LinearBar(ecs::ComponentRegistry &registry)
68 : ecs::EntityFiller<components::Transform, components::Bound,
69 components::Color, components::Borders,
70 components::Animation>(registry)
71 {
72 }
73
77 ~LinearBar(void) override = default;
78 };
79
83 class RotatingArc:
84 public ecs::EntityFiller<components::Transform, components::Bound,
85 components::Color, components::Arc,
86 components::Animation>
87 {
88 public:
93 explicit RotatingArc(ecs::ComponentRegistry &registry)
94 : ecs::EntityFiller<components::Transform, components::Bound,
95 components::Color, components::Arc,
96 components::Animation>(registry)
97 {
98 }
99
103 ~RotatingArc(void) override = default;
104 };
105 } // namespace
106
108 ecs::ComponentRegistry &componentRegistry,
109 ecs::EntityRegistry &entityRegistry)
110 : EntityBuilderBase<LoadingIndicator>(componentRegistry, entityRegistry)
111 {
112 reset();
113 }
114
115 std::shared_ptr<LoadingIndicator>
117 {
118 if (_variant == Variant::Circular) {
119 _config.setFixedWidth(_size).setFixedHeight(_size);
120 _config.borderRadius = _size * 0.5f;
121 } else {
122 _config.setFixedWidth(LinearWidth).setFixedHeight(LinearHeight);
123 _config.borderRadius = LinearRadius;
124 }
125
127 _config, _variant);
128 return entity;
129 }
130
132 {
133 _config = SurfaceConfig();
134 _variant = Variant::Circular;
135 _size = CircularSize;
136
137 _config.borderRadius = LinearRadius;
139 _config.mainAxisAlignment =
141 _config.crossAxisAlignment =
143 _config.padding = 0.0f;
144 _config.spacing = 0.0f;
145 _config.setFixedWidth(LinearWidth);
146 _config.setFixedHeight(LinearHeight);
147 }
148
150 LoadingIndicator::Builder::withPose(const utility::graphic::PoseF &pose)
151 {
152 _config.pose = pose;
153 return *this;
154 }
155
158 {
159 _variant = variant;
160 return *this;
161 }
162
164 {
165 _size = size;
166 return *this;
167 }
168
169 std::shared_ptr<LoadingIndicator>
171 std::shared_ptr<ecs::Entity> parent, Variant variant)
172 {
173 return withVariant(variant).registerEntity(parent);
174 }
175
176 LoadingIndicator::LoadingIndicator(ecs::ComponentRegistry &registry,
177 const SurfaceConfig &config,
178 Variant variant)
179 : SurfaceBase<components::Animation, components::Accessibility,
180 components::LoadingIndicator>(registry, config)
181 {
184 .setVariant(variant)
185 .setSize(variant == Variant::Circular && config.hasFixedHeight
186 ? config.fixedHeight
187 : CircularSize);
189 getIdentifier());
191 getIdentifier());
192 }
193
203
210
217
219 const utility::graphic::Color32Bit &color)
220 {
223 .setIndicatorColor(color);
225 getIdentifier());
226 return *this;
227 }
228
229 utility::graphic::Color32Bit LoadingIndicator::getIndicatorColor(void) const
230 {
232 getIdentifier());
233 }
234
235 LoadingIndicator &LoadingIndicator::setSize(float size)
236 {
237 if (size <= 0.0f) {
238 throw std::invalid_argument(
239 "Loading indicator size must be positive");
240 }
241
242 auto &state =
244 getIdentifier());
245
246 state.setSize(size);
247 if (state.getVariant() == Variant::Circular) {
248 state.setBuilt(false);
249 buildChild();
251 getIdentifier());
252 }
253 return *this;
254 }
255
262
268
272
273 void LoadingIndicator::buildChild(void)
274 {
275 auto &registry = getComponentRegistry();
276 auto &state = registry.getComponent<components::LoadingIndicator>(
277 getIdentifier());
278
279 if (state.isBuilt()) {
280 return;
281 }
282
283 // Remove any child left over from a previous variant with its
284 // components, and silence its animation first so it no longer
285 // drives this indicator.
287 state.getIndicator())) {
288 registry.getComponent<components::Animation>(state.getIndicator())
290 .stop();
291 }
292 this->clearEntities();
293
294 std::shared_ptr<ecs::Entity> child;
295 if (state.getVariant() == Variant::Circular) {
296 child = std::make_shared<RotatingArc>(registry);
297 } else {
298 child = std::make_shared<LinearBar>(registry);
299 }
300 child->setParent(shared_from_this());
301 this->addEntity(child);
302 state.setIndicator(child->getIdentifier()).setBuilt(true);
304
305 // The animated child is positioned by systems::LoadingIndicator, so
306 // it is not registered as a layout child of the surface.
307 setChildren({});
308 }
309
310 LoadingIndicator &LoadingIndicator::setVariant(Variant variant)
311 {
312 auto &state =
314 getIdentifier());
315
316 if (state.getVariant() == variant) {
317 return *this;
318 }
319
320 // The child is built from the variant: rebuild it so the new shape
321 // (bar vs. arc) is adopted.
322 state.setVariant(variant).setBuilt(false);
323 buildChild();
325 getIdentifier());
326
327 return *this;
328 }
329
336
337 LoadingIndicator &LoadingIndicator::start(void)
338 {
340 getIdentifier());
341 return *this;
342 }
343
344 LoadingIndicator &LoadingIndicator::stop(void)
345 {
347 getIdentifier());
348 return *this;
349 }
350
356
357 void LoadingIndicator::build(void)
358 {
359 buildChild();
361 getIdentifier());
362 }
363
364} // namespace guillaume::entities
A timer that runs from 0 to a duration and reports its eased progress, from 0 to 1,...
Definition animation.hpp:61
Animation & setOnSampleHandler(const SampleHandler &handler)
Store the callback that applies the animation.
std::function< void(float)> SampleHandler
Receives the eased progress.
Definition animation.hpp:63
@ Start
Packed at the left (row) or top (column).
Definition layout.hpp:87
@ Horizontal
Row: children placed left to right.
Definition layout.hpp:75
State of a loading indicator: an arc that turns, or a bar that slides, in a loop while something is i...
static constexpr float LinearWidth
Length of the linear variant, in dp.
LoadingIndicator & setVariant(Variant variant)
Set the shape of the indicator.
LoadingIndicator & setBuilt(bool built)
Record whether the animated child matches the current variant.
static constexpr float LinearHeight
Thickness of the linear variant, in dp.
LoadingIndicator & setSize(float size)
Set the diameter of the circular variant.
static constexpr float DefaultSize
Default diameter of the circular variant, in dp.
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.
void addEntity(std::shared_ptr< Entity > entity)
Make this registry own an entity, so that it stays alive and systems visit it.
void clearEntities(void)
Remove every entity owned by this registry, with everything they own and all their components.
Entity::Identifier getIdentifier(void) const noexcept
Get the identifier of the entity.
Definition entity.cpp:94
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Configures a LoadingIndicator, then builds it and registers it in the entity registry given at constr...
void reset(void) override
Restore the defaults: Circular variant, a 48 dp diameter and a default pose.
std::shared_ptr< LoadingIndicator > makeLoadingIndicator(std::shared_ptr< ecs::Entity > parent, Variant variant)
Build a loading indicator, register it under parent and reset the builder.
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Create a builder set to the defaults of reset().
Builder & withVariant(Variant variant)
Set the indicator variant.
Builder & withPose(const utility::graphic::PoseF &pose)
Set the pose the indicator is created with.
std::shared_ptr< LoadingIndicator > buildEntity(void) override
Build a loading indicator and its animated child from the current configuration, without registering ...
Builder & withSize(float size)
Set the diameter of the Circular variant.
float getSize(void) const
Get the diameter of the Circular variant.
float getStrokeWidth(void) const
Get the thickness of the arc of the Circular variant.
Variant getVariant(void) const
Get the indicator variant.
utility::graphic::Color32Bit getIndicatorColor(void) const
Get the color of the arc or bar.
float getOpacity(void) const
Get the opacity of the fade.
static std::shared_ptr< LoadingIndicator > create(Arguments &&...arguments)
Create a loading indicator and its animated child, without registering it in an entity registry.
LoadingIndicator & stop(void)
Stop the looping animation.
LoadingIndicator & start(void)
Start the looping animation and fade the indicator in over 200 ms.
components::LoadingIndicator::Variant Variant
LoadingIndicator & setIndicatorColor(const utility::graphic::Color32Bit &color)
Set the color of the arc or bar. Redraws at once.
LoadingIndicator & setSize(float size)
Set the diameter of the Circular variant (Paper size).
~LoadingIndicator(void) override
Default destructor.
bool hidesWhenStopped(void) const
Check whether a stopped indicator is hidden.
LoadingIndicator & setVariant(Variant variant)
Change the indicator variant.
bool isRunning(void) const
Check whether the looping animation is playing.
LoadingIndicator & setHidesWhenStopped(bool hides)
Choose whether a stopped indicator is hidden (Paper hidesWhenStopped).
static void installChildren(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Wire the looping animation of the animated child and start it.
static void startFade(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Start fading towards the opacity the running state calls for.
static bool isRunning(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the looping animation is running.
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Give a loading indicator its accessibility role and its fade.
static float strokeWidth(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Get the stroke width of the circular arc, in dp.
static utility::graphic::Color32Bit indicatorColor(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Get the color of the arc or bar at full opacity.
static void stop(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Stop the looping animation.
static void start(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Start the looping animation and fade the indicator in.
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Size one loading indicator and draw its animated child at the current loop progress and opacity.
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
@ Full
Fully rounded (buttons, icon buttons, badges).
Definition tokens.hpp:49
float getShapeRadius(theme::ShapeRole role)
Get the corner radius the active theme gives to a shape role.
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
bool hasFixedHeight
True when fixedHeight replaces the content height.
Definition surface.hpp:97
float fixedHeight
Height in dp, used only when hasFixedHeight.
Definition surface.hpp:100