guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
progress_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/progress_indicator.hpp"
24
25#include <algorithm>
26#include <cstdint>
27#include <optional>
28
29#include "guillaume/components/accessibility.hpp"
30#include "guillaume/components/animation.hpp"
31#include "guillaume/components/arc.hpp"
32#include "guillaume/components/borders.hpp"
33#include "guillaume/components/bound.hpp"
34#include "guillaume/components/color.hpp"
35#include "guillaume/components/layout.hpp"
36#include "guillaume/components/ring.hpp"
37#include "guillaume/components/value.hpp"
40#include "guillaume/motion/easing.hpp"
41#include "guillaume/systems/layout.hpp"
42#include "guillaume/theme.hpp"
43
44namespace guillaume::systems
45{
46 namespace
47 {
48 constexpr float TwoPi = 6.28318530717958647692f;
49 constexpr float HalfPi = 1.57079632679489661923f;
50
60 void shape(ecs::ComponentRegistry &registry,
61 const ecs::Entity::Identifier &identifier, float width,
62 float height, float radius, std::uint32_t layer)
63 {
64 auto &layout =
65 registry.getComponent<components::Layout>(identifier);
66
67 layout.setPadding(0.0f)
68 .setSpacing(0.0f)
69 .setFixedWidth(width)
70 .setFixedHeight(height);
71 registry.getComponent<components::Borders>(identifier)
72 .setBorderRadius(radius);
73 registry.getComponent<components::Color>(identifier)
74 .setColor(style::transparentColor());
75 Layout::apply(registry, identifier, layout.getChildren(), layer);
76 }
77
87 void publish(ecs::ComponentRegistry &registry,
88 const ecs::Entity::Identifier &identifier,
89 const std::optional<components::AccessibilityValue> &value)
90 {
91 auto &accessibility =
92 registry.getComponent<components::Accessibility>(identifier);
93 const auto &current = accessibility.getValue();
94
95 if (current.has_value() == value.has_value()
96 && (!value.has_value()
97 || (current->min == value->min && current->max == value->max
98 && current->now == value->now))) {
99 return;
100 }
101 accessibility.setValue(value);
102 }
103
110 utility::graphic::Color32Bit
111 faded(const utility::graphic::Color32Bit &color, float opacity)
112 {
113 return style::withAlpha(
114 color,
115 static_cast<std::uint8_t>(
116 static_cast<float>(color.getAlpha()) * opacity + 0.5f));
117 }
118 } // namespace
119
124
126 ecs::ComponentRegistry &componentRegistry,
127 const ecs::Entity::Identifier &entityIdentifier)
128 {
129 ecs::ComponentRegistry *registry = &componentRegistry;
130 const ecs::Entity::Identifier identifier = entityIdentifier;
131 auto &state =
133 identifier);
134 auto &value =
135 componentRegistry.getComponent<components::Value>(identifier);
136
137 value.setMin(0.0f).setMax(1.0f).setStep(0.0f);
138 // The value held at installation is drawn as is: only later changes
139 // are animated.
140 state.setDisplayed(value.getValue()).setValueFrom(value.getValue());
141 value.setOnChangedHandler([registry, identifier](float) {
142 startTransition(*registry, identifier);
143 });
144
145 componentRegistry.getComponent<components::Animation>(identifier)
148 .setOnSampleHandler([registry, identifier](float progress) {
149 auto &current =
151 identifier);
152 const float target =
153 registry->getComponent<components::Value>(identifier)
154 .getValue();
155 const float opacityTarget = current.isVisible() ? 1.0f : 0.0f;
156
157 current
158 .setDisplayed(current.getValueFrom()
159 + (target - current.getValueFrom())
160 * progress)
161 .setOpacity(current.getOpacityFrom()
162 + (opacityTarget - current.getOpacityFrom())
163 * progress);
164 apply(*registry, identifier);
165 });
166
167 componentRegistry.getComponent<components::Accessibility>(identifier)
169 }
170
172 ecs::ComponentRegistry &componentRegistry,
173 const ecs::Entity::Identifier &entityIdentifier)
174 {
175 ecs::ComponentRegistry *registry = &componentRegistry;
176 const ecs::Entity::Identifier identifier = entityIdentifier;
177 const auto &state =
179 identifier);
180 const auto fill = state.getFill();
181
182 if (!state.isIndeterminate()
183 || !componentRegistry.hasComponent<components::Animation>(fill)) {
184 return;
185 }
186 componentRegistry.getComponent<components::Animation>(fill)
188 .setEasing(motion::Easing::Standard)
189 .setLooping(true)
190 .setOnSampleHandler([registry, identifier](float progress) {
191 registry
193 .setCycle(progress);
194 apply(*registry, identifier);
195 })
196 .play();
197 }
198
200 ecs::ComponentRegistry &componentRegistry,
201 const ecs::Entity::Identifier &entityIdentifier)
202 {
203 const auto &state =
205 entityIdentifier);
206 const auto layer = Layout::layerOf(componentRegistry, entityIdentifier);
207 const bool circular = state.isCircular();
208 const bool indeterminate = state.isIndeterminate();
209 const float diameter = state.getDiameter();
210 const float length = state.getTrackLength();
212 const float full = getShapeRadius(theme::ShapeRole::Full);
213 const float normalized = std::clamp(state.getDisplayed(), 0.0f, 1.0f);
214 const auto track = state.getTrack();
215 const auto fill = state.getFill();
216 const utility::graphic::PositionF origin(0.0f, 0.0f, 0.0f);
217
218 if (circular) {
219 shape(componentRegistry, entityIdentifier, diameter, diameter,
220 diameter * 0.5f, layer);
221 } else {
222 shape(componentRegistry, entityIdentifier, length, height, full,
223 layer);
224 }
225
226 if (indeterminate) {
227 publish(componentRegistry, entityIdentifier, std::nullopt);
228 } else {
229 publish(componentRegistry, entityIdentifier,
231 0.0f, 100.0f,
232 std::clamp(componentRegistry
234 entityIdentifier)
235 .getValue(),
236 0.0f, 1.0f)
237 * 100.0f });
238 }
239
240 if (!componentRegistry.hasComponent<components::Bound>(track)
241 || !componentRegistry.hasComponent<components::Color>(track)
242 || !componentRegistry.hasComponent<components::Bound>(fill)
243 || !componentRegistry.hasComponent<components::Color>(fill)) {
244 return;
245 }
246
247 componentRegistry.getComponent<components::Color>(track).setColor(
248 faded(style::schemeColor(SchemeColorRole::SurfaceVariant),
249 state.getOpacity()));
250 componentRegistry.getComponent<components::Color>(fill).setColor(
251 faded(indicatorColor(componentRegistry, entityIdentifier),
252 state.getOpacity()));
253 placement::placeChild(componentRegistry, entityIdentifier, track,
254 origin, layer);
255 // The fill covers the track: one step closer to the viewer, or the
256 // two would sit at the same depth and the track could hide it.
257 const auto fillLayer = layer + 1;
258
259 if (circular) {
260 placement::placeChild(componentRegistry, entityIdentifier, fill,
261 origin, fillLayer);
262 componentRegistry.getComponent<components::Bound>(track)
263 .setWidth(diameter)
264 .setHeight(diameter);
265 componentRegistry.getComponent<components::Bound>(fill)
266 .setWidth(diameter)
267 .setHeight(diameter);
268 if (componentRegistry.hasComponent<components::Ring>(track)) {
269 componentRegistry.getComponent<components::Ring>(track)
271 }
272 if (componentRegistry.hasComponent<components::Arc>(fill)) {
273 auto &arc =
274 componentRegistry.getComponent<components::Arc>(fill);
275
277 if (indeterminate) {
278 // y points up: the top is +pi/2 and clockwise is a
279 // negative sweep.
280 arc.setStartAngle(HalfPi - state.getCycle() * TwoPi)
281 .setSweepAngle(-TwoPi
283 IndeterminateSweep);
284 } else {
285 arc.setStartAngle(HalfPi).setSweepAngle(-normalized
286 * TwoPi);
287 }
288 }
289 return;
290 }
291
292 componentRegistry.getComponent<components::Bound>(track)
293 .setWidth(length)
294 .setHeight(height);
295 if (componentRegistry.hasComponent<components::Borders>(fill)) {
296 componentRegistry.getComponent<components::Borders>(fill)
297 .setBorderRadius(full);
298 }
299 if (indeterminate) {
300 const float segment =
302
304 componentRegistry, entityIdentifier, fill,
305 utility::graphic::PositionF(
306 state.getCycle() * (length - segment), 0.0f, 0.0f),
307 fillLayer);
308 componentRegistry.getComponent<components::Bound>(fill)
309 .setWidth(segment)
310 .setHeight(height);
311 } else {
312 placement::placeChild(componentRegistry, entityIdentifier, fill,
313 origin, fillLayer);
314 componentRegistry.getComponent<components::Bound>(fill)
315 .setWidth(length * normalized)
316 .setHeight(height);
317 }
318 }
319
321 ecs::ComponentRegistry &componentRegistry,
322 const ecs::Entity::Identifier &entityIdentifier, float value)
323 {
324 componentRegistry.getComponent<components::Value>(entityIdentifier)
325 .setNormalizedValue(std::clamp(value, 0.0f, 1.0f));
326 }
327
329 ecs::ComponentRegistry &componentRegistry,
330 const ecs::Entity::Identifier &entityIdentifier, bool visible)
331 {
332 auto &state =
334 entityIdentifier);
335
336 if (state.isVisible() == visible) {
337 return;
338 }
339 state.setVisible(visible);
340 startTransition(componentRegistry, entityIdentifier);
341 }
342
344 ecs::ComponentRegistry &componentRegistry,
345 const ecs::Entity::Identifier &entityIdentifier)
346 {
347 auto &state =
349 entityIdentifier);
350
351 state.setValueFrom(state.getDisplayed())
352 .setOpacityFrom(state.getOpacity());
353 componentRegistry.getComponent<components::Animation>(entityIdentifier)
354 .play();
355 apply(componentRegistry, entityIdentifier);
356 }
357
358 utility::graphic::Color32Bit ProgressIndicator::indicatorColor(
359 const ecs::ComponentRegistry &componentRegistry,
360 const ecs::Entity::Identifier &entityIdentifier)
361 {
362 return componentRegistry
364 .getIndicatorColor()
365 .value_or(style::schemeColor(SchemeColorRole::Primary));
366 }
367
369 const ecs::Entity::Identifier &entityIdentifier)
370 {
372 entityIdentifier)) {
373 return;
374 }
375
376 apply(getComponentRegistry(), entityIdentifier);
377 }
378} // 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.
A portion of a ring: the moving part of a circular progress or loading indicator.
Definition arc.hpp:59
Arc & setThickness(float thickness)
Set the thickness of the arc.
Definition arc.cpp:40
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 progress indicator: a bar or a ring that fills up with a value from 0 to 1,...
ProgressIndicator & setDisplayed(float displayed)
Store the value currently drawn.
static constexpr float LinearHeight
Thickness of the linear track, in dp.
static constexpr float RingThickness
Stroke width of the circular track and fill, in dp.
ProgressIndicator & setOpacityFrom(float opacity)
Store the opacity at the start of a fade.
ProgressIndicator & setVisible(bool visible)
Record whether the indicator is meant to be visible.
ProgressIndicator & setValueFrom(float value)
Store the value drawn at the start of a transition.
ecs::Entity::Identifier getFill(void) const noexcept
Get the child that draws the fill: the part of the bar or ring that shows the progress.
A full ring: the outline of a radio button, the track of a circular progress indicator.
Definition ring.hpp:53
A number kept inside a range, with a callback run when it changes.
Definition value.hpp:56
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
ComponentType & getComponent(const ecs::Entity::Identifier &entityIdentifier)
Get a component of an entity from the bound registry, to read or modify it.
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 setVisible(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool visible)
Show or hide the indicator with a fade.
static void startTransition(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Start moving the drawn value and opacity towards their targets.
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Prepare the value, the transition and the accessibility role of a progress indicator.
static void setValue(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, float value)
Set the target value.
ProgressIndicator(void)
Create the system in the Layout phase.
static void installChildren(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Wire the looping animation of an indeterminate indicator and start it.
void update(const ecs::Entity::Identifier &entityIdentifier) override
Run apply() on one progress indicator; called by the frame loop.
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Size one progress indicator and draw its track and fill from the displayed value, the cycle position ...
static utility::graphic::Color32Bit indicatorColor(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Get the color of the fill at full 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.
Position of a control within a range, such as a slider or a progress bar. Accessibility::setValue req...
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.