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/systems/loading_indicator.hpp"
24
25#include <cstdint>
26
27#include "guillaume/components/accessibility.hpp"
28#include "guillaume/components/animation.hpp"
29#include "guillaume/components/arc.hpp"
30#include "guillaume/components/borders.hpp"
31#include "guillaume/components/bound.hpp"
32#include "guillaume/components/color.hpp"
33#include "guillaume/components/layout.hpp"
36#include "guillaume/motion/easing.hpp"
37#include "guillaume/systems/layout.hpp"
38#include "guillaume/theme.hpp"
39
40namespace guillaume::systems
41{
42 namespace
43 {
45
46 constexpr float TwoPi = 6.28318530717958647692f;
47 constexpr float HalfPi = 1.57079632679489661923f;
48 constexpr float ArcSweep = 4.71238898038468985769f; // 1.5 * pi
49
59 void shape(ecs::ComponentRegistry &registry,
60 const ecs::Entity::Identifier &identifier, float width,
61 float height, float radius, std::uint32_t layer)
62 {
63 auto &layout =
64 registry.getComponent<components::Layout>(identifier);
65
66 layout.setPadding(0.0f)
67 .setSpacing(0.0f)
68 .setFixedWidth(width)
69 .setFixedHeight(height);
70 registry.getComponent<components::Borders>(identifier)
71 .setBorderRadius(radius);
72 registry.getComponent<components::Color>(identifier)
73 .setColor(style::transparentColor());
74 Layout::apply(registry, identifier, layout.getChildren(), layer);
75 }
76 } // namespace
77
82
84 ecs::ComponentRegistry &componentRegistry,
85 const ecs::Entity::Identifier &entityIdentifier)
86 {
87 ecs::ComponentRegistry *registry = &componentRegistry;
88 const ecs::Entity::Identifier identifier = entityIdentifier;
89
90 componentRegistry.getComponent<components::Accessibility>(identifier)
92 componentRegistry.getComponent<components::Animation>(identifier)
95 .setOnSampleHandler([registry, identifier](float progress) {
96 auto &state =
98 identifier);
99 state.setOpacity(
100 state.getOpacityFrom()
101 + (state.getOpacityTarget() - state.getOpacityFrom())
102 * progress);
103 apply(*registry, identifier);
104 });
105 }
106
108 ecs::ComponentRegistry &componentRegistry,
109 const ecs::Entity::Identifier &entityIdentifier)
110 {
111 ecs::ComponentRegistry *registry = &componentRegistry;
112 const ecs::Entity::Identifier identifier = entityIdentifier;
113 const auto child =
114 componentRegistry
116 .getIndicator();
117
118 if (!componentRegistry.hasComponent<components::Animation>(child)) {
119 return;
120 }
121 componentRegistry.getComponent<components::Animation>(child)
123 .setEasing(motion::Easing::Standard)
124 .setLooping(true)
125 .setOnSampleHandler([registry, identifier](float progress) {
126 registry->getComponent<components::LoadingIndicator>(identifier)
127 .setProgress(progress);
128 apply(*registry, identifier);
129 })
130 .play();
131 }
132
133 void
135 const ecs::Entity::Identifier &entityIdentifier)
136 {
137 const auto &state =
139 entityIdentifier);
140 const auto layer = Layout::layerOf(componentRegistry, entityIdentifier);
141 const bool circular = state.getVariant() == Variant::Circular;
142 const float size = state.getSize();
143 const float full = getShapeRadius(theme::ShapeRole::Full);
144 const auto child = state.getIndicator();
145
146 if (circular) {
147 shape(componentRegistry, entityIdentifier, size, size, size * 0.5f,
148 layer);
149 } else {
150 shape(componentRegistry, entityIdentifier,
153 }
154
155 if (!componentRegistry.hasComponent<components::Bound>(child)
156 || !componentRegistry.hasComponent<components::Color>(child)) {
157 return;
158 }
159
160 const auto color = indicatorColor(componentRegistry, entityIdentifier);
161 componentRegistry.getComponent<components::Color>(child).setColor(
163 color,
164 static_cast<std::uint8_t>(static_cast<float>(color.getAlpha())
165 * state.getOpacity()
166 + 0.5f)));
167
168 if (circular) {
169 if (componentRegistry.hasComponent<components::Arc>(child)) {
170 componentRegistry.getComponent<components::Arc>(child)
171 .setThickness(
172 strokeWidth(componentRegistry, entityIdentifier))
173 // y points up: the top is +pi/2 and clockwise is a
174 // negative sweep.
175 .setStartAngle(HalfPi - state.getProgress() * TwoPi)
176 .setSweepAngle(-ArcSweep);
177 }
178 placement::placeChild(componentRegistry, entityIdentifier, child,
179 utility::graphic::PositionF(0.0f, 0.0f, 0.0f),
180 layer);
181 componentRegistry.getComponent<components::Bound>(child)
182 .setWidth(size)
183 .setHeight(size);
184 return;
185 }
186
189
190 if (componentRegistry.hasComponent<components::Borders>(child)) {
191 componentRegistry.getComponent<components::Borders>(child)
192 .setBorderRadius(full);
193 }
195 componentRegistry, entityIdentifier, child,
196 utility::graphic::PositionF(
197 state.getProgress()
199 0.0f, 0.0f),
200 layer);
201 componentRegistry.getComponent<components::Bound>(child)
202 .setWidth(segment)
204 }
205
206 void
208 const ecs::Entity::Identifier &entityIdentifier)
209 {
210 const auto child =
211 componentRegistry
213 .getIndicator();
214
215 if (componentRegistry.hasComponent<components::Animation>(child)) {
216 componentRegistry.getComponent<components::Animation>(child).play();
217 }
218 startFade(componentRegistry, entityIdentifier);
219 }
220
222 const ecs::Entity::Identifier &entityIdentifier)
223 {
224 const auto child =
225 componentRegistry
227 .getIndicator();
228
229 if (componentRegistry.hasComponent<components::Animation>(child)) {
230 componentRegistry.getComponent<components::Animation>(child).stop();
231 }
232 startFade(componentRegistry, entityIdentifier);
233 }
234
236 const ecs::ComponentRegistry &componentRegistry,
237 const ecs::Entity::Identifier &entityIdentifier)
238 {
239 const auto child =
240 componentRegistry
242 .getIndicator();
243
244 return componentRegistry.hasComponent<components::Animation>(child)
245 && componentRegistry.getComponent<components::Animation>(child)
246 .isPlaying();
247 }
248
250 ecs::ComponentRegistry &componentRegistry,
251 const ecs::Entity::Identifier &entityIdentifier)
252 {
253 auto &state =
255 entityIdentifier);
256 const float target = (isRunning(componentRegistry, entityIdentifier)
257 || !state.hidesWhenStopped())
258 ? 1.0f
259 : 0.0f;
260
261 if (target == state.getOpacityTarget()
262 && target == state.getOpacity()) {
263 return;
264 }
265 state.setOpacityFrom(state.getOpacity()).setOpacityTarget(target);
266 componentRegistry.getComponent<components::Animation>(entityIdentifier)
267 .play();
268 }
269
270 utility::graphic::Color32Bit LoadingIndicator::indicatorColor(
271 const ecs::ComponentRegistry &componentRegistry,
272 const ecs::Entity::Identifier &entityIdentifier)
273 {
274 return componentRegistry
276 .getIndicatorColor()
277 .value_or(style::schemeColor(SchemeColorRole::Primary));
278 }
279
281 const ecs::ComponentRegistry &componentRegistry,
282 const ecs::Entity::Identifier &entityIdentifier)
283 {
284 return componentRegistry
286 .getSize()
288 }
289
291 const ecs::Entity::Identifier &entityIdentifier)
292 {
293 if (!requireComponent<components::LoadingIndicator>(entityIdentifier)) {
294 return;
295 }
296
297 apply(getComponentRegistry(), entityIdentifier);
298 }
299} // namespace guillaume::systems
What an entity means to a user who does not see it: its name, its role, its state and its place in th...
A timer that runs from 0 to a duration and reports its eased progress, from 0 to 1,...
Definition animation.hpp:61
Animation & setEasing(motion::Easing easing)
Set the curve that turns the linear progress into the value passed to the sample handler.
Animation & setOnSampleHandler(const SampleHandler &handler)
Store the callback that applies the animation.
Animation & setLooping(bool looping)
Set whether the animation starts again when it completes.
bool isPlaying(void) const
Check whether the animation is running.
Definition animation.cpp:74
A portion of a ring: the moving part of a circular progress or loading indicator.
Definition arc.hpp:59
Arc & setStartAngle(float startAngle)
Set the angle the arc starts at.
Definition arc.cpp:55
Arc & setSweepAngle(float sweepAngle)
Set the angle the arc covers from its start angle.
Definition arc.cpp:70
Corner radii and outline stroke of a rectangular entity.
Definition borders.hpp:67
Size of an entity: the width and height, in dp, of the rectangle that starts at the position of its c...
Definition bound.hpp:62
Bound & setHeight(float height) noexcept
Set the height.
Definition bound.cpp:42
Main color of an entity: the fill of a shape, or the ink of a text or an icon.
Definition color.hpp:58
State of a loading indicator: an arc that turns, or a bar that slides, in a loop while something is i...
LoadingIndicator & setOpacity(float opacity)
Store the opacity the indicator is drawn with.
static constexpr float LinearWidth
Length of the linear variant, in dp.
static constexpr float LinearHeight
Thickness of the linear 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.
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
ecs::ComponentRegistry & getComponentRegistry(void)
Get the component registry of the scene being processed.
Definition system.cpp:53
bool requireComponent(const ecs::Entity::Identifier &entityIdentifier)
Tell whether an entity has a component, and log a warning naming the entity and the component when it...
Arranges the children of a container in a row or a column and sizes the container around them.
Definition layout.hpp:84
static void apply(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, std::uint32_t layer=0)
Arrange children inside a container and size the container.
Definition layout.cpp:126
static std::uint32_t layerOf(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Get the layer of an entity: its depth in the entity tree.
Definition layout.cpp:90
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.
void update(const ecs::Entity::Identifier &entityIdentifier) override
Run apply() on one loading indicator; called by the frame loop.
LoadingIndicator(void)
Create the system in the Layout phase.
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.
static constexpr float IndeterminateCycle
Duration of one cycle of an indeterminate progress or loading indicator, in seconds (1....
Definition tokens.hpp:341
static constexpr motion::Easing standard(void)
Get the easing for elements that move or change while staying on screen.
Definition tokens.hpp:380
State. Every class here is plain data attached to an entity.
@ ProgressBar
Determinate or indeterminate progress.
The entity-component-system core, independent of any widget.
Definition component.hpp:28
void placeChild(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const ecs::Entity::Identifier &childIdentifier, const utility::graphic::PositionF &offset, std::uint32_t parentLayer)
Place a child at an offset from the position of its parent.
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit withAlpha(const utility::graphic::Color32Bit &color, std::uint8_t alpha)
Copy a color with another alpha channel.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
Rules. Every class here runs each frame on the entities that have the components it declares.
@ Full
Fully rounded (buttons, icon buttons, badges).
Definition tokens.hpp:49
float getMotionDuration(theme::MotionDuration duration)
Get the length the active theme gives to a duration token.
float getShapeRadius(theme::ShapeRole role)
Get the corner radius the active theme gives to a shape role.
Placement helpers for the children systems::Layout does not arrange.
Color helpers shared by the widget systems: scheme lookup, state layers and the disabled colors.