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/entities/progress_indicator.hpp"
24
25#include <algorithm>
26#include <cmath>
27#include <memory>
28#include <vector>
29
30#include "guillaume/ecs/entity_filler.hpp"
31
32#include "guillaume/components/animation.hpp"
33#include "guillaume/components/arc.hpp"
34#include "guillaume/components/borders.hpp"
35#include "guillaume/components/bound.hpp"
36#include "guillaume/components/color.hpp"
37#include "guillaume/components/ring.hpp"
38#include "guillaume/components/transform.hpp"
39
40#include "guillaume/components/accessibility.hpp"
41#include "guillaume/entities/builder_base.hpp"
43#include "guillaume/systems/progress_indicator.hpp"
44#include "guillaume/theme.hpp"
45
46namespace guillaume::entities
47{
48 namespace
49 {
50 constexpr float LinearHeight =
52 const float LinearRadius = getShapeRadius(theme::ShapeRole::Full);
53 constexpr float CircularSize =
55 constexpr float TrackLength =
57
61 class LinearTrack:
62 public ecs::EntityFiller<components::Transform, components::Bound,
63 components::Color, components::Borders>
64 {
65 public:
70 explicit LinearTrack(ecs::ComponentRegistry &registry)
71 : ecs::EntityFiller<components::Transform, components::Bound,
72 components::Color, components::Borders>(
73 registry)
74 {
75 }
76
80 ~LinearTrack(void) override = default;
81 };
82
86 class LinearFill:
87 public ecs::EntityFiller<components::Transform, components::Bound,
88 components::Color, components::Borders,
89 components::Animation>
90 {
91 public:
96 explicit LinearFill(ecs::ComponentRegistry &registry)
97 : ecs::EntityFiller<components::Transform, components::Bound,
98 components::Color, components::Borders,
99 components::Animation>(registry)
100 {
101 }
102
106 ~LinearFill(void) override = default;
107 };
108
112 class CircularTrack:
113 public ecs::EntityFiller<components::Transform, components::Bound,
114 components::Color, components::Ring>
115 {
116 public:
121 explicit CircularTrack(ecs::ComponentRegistry &registry)
122 : ecs::EntityFiller<components::Transform, components::Bound,
123 components::Color, components::Ring>(
124 registry)
125 {
126 }
127
131 ~CircularTrack(void) override = default;
132 };
133
137 class CircularFill:
138 public ecs::EntityFiller<components::Transform, components::Bound,
139 components::Color, components::Arc,
140 components::Animation>
141 {
142 public:
147 explicit CircularFill(ecs::ComponentRegistry &registry)
148 : ecs::EntityFiller<components::Transform, components::Bound,
149 components::Color, components::Arc,
150 components::Animation>(registry)
151 {
152 }
153
157 ~CircularFill(void) override = default;
158 };
159 } // namespace
160
162 ecs::ComponentRegistry &componentRegistry,
163 ecs::EntityRegistry &entityRegistry)
164 : EntityBuilderBase<ProgressIndicator>(componentRegistry,
165 entityRegistry)
166 {
167 reset();
168 }
169
170 std::shared_ptr<ProgressIndicator>
172 {
173 if (_variant == Variant::CircularDeterminate
174 || _variant == Variant::CircularIndeterminate) {
175 _config.setFixedWidth(_size).setFixedHeight(_size);
176 _config.borderRadius = _size * 0.5f;
177 } else {
178 _config.setFixedWidth(_width).setFixedHeight(LinearHeight);
179 _config.borderRadius = LinearRadius;
180 }
181
183 _config, _variant, _value);
184 return entity;
185 }
186
188 {
189 _config = SurfaceConfig();
190 _variant = Variant::LinearDeterminate;
191 _value = 0.0f;
192 _width = TrackLength;
193 _size = CircularSize;
194
195 _config.borderRadius = LinearRadius;
197 _config.mainAxisAlignment =
199 _config.crossAxisAlignment =
201 _config.padding = 0.0f;
202 _config.spacing = 0.0f;
203 _config.setFixedWidth(_width);
204 _config.setFixedHeight(LinearHeight);
205 }
206
208 const utility::graphic::PoseF &pose)
209 {
210 _config.pose = pose;
211 return *this;
212 }
213
216 {
217 _variant = variant;
218 return *this;
219 }
220
223 {
224 _value = std::clamp(value, 0.0f, 1.0f);
225 return *this;
226 }
227
230 {
231 _width = width;
232 return *this;
233 }
234
236 {
237 _size = size;
238 return *this;
239 }
240
241 std::shared_ptr<ProgressIndicator>
243 std::shared_ptr<ecs::Entity> parent, Variant variant, float value)
244 {
245 return withVariant(variant).withValue(value).registerEntity(parent);
246 }
247
248 ProgressIndicator::ProgressIndicator(ecs::ComponentRegistry &registry,
249 const SurfaceConfig &config,
250 Variant variant, float value)
251 : SurfaceBase<components::Value, components::Animation,
252 components::Accessibility, components::ProgressIndicator>(
253 registry, config)
254 {
255 auto &state =
257 getIdentifier());
258
259 state.setVariant(variant);
260 state
261 .setTrackLength(!state.isCircular() && config.hasFixedWidth
262 ? config.fixedWidth
263 : TrackLength)
264 .setDiameter(state.isCircular() && config.hasFixedHeight
265 ? config.fixedHeight
266 : CircularSize);
267 // Set before the system is installed, so the initial value is drawn
268 // as is instead of being animated from zero.
271 .setValue(std::clamp(value, 0.0f, 1.0f));
273 getIdentifier());
275 getIdentifier());
276 }
277
279 {
280 return getComponentRegistry()
282 .getDisplayed();
283 }
284
285 ProgressIndicator &ProgressIndicator::setVisible(bool visible)
286 {
288 getIdentifier(), visible);
289 return *this;
290 }
291
298
305
307 const utility::graphic::Color32Bit &color)
308 {
311 .setIndicatorColor(color);
313 getIdentifier());
314 return *this;
315 }
316
317 utility::graphic::Color32Bit
323
327
328 void ProgressIndicator::buildChildren(void)
329 {
330 auto &registry = getComponentRegistry();
331 auto &state = registry.getComponent<components::ProgressIndicator>(
332 getIdentifier());
333
334 if (state.isBuilt()) {
335 return;
336 }
337
338 // Remove any children left over from a previous variant, and silence
339 // the fill animation so it no longer drives this indicator.
340 if (registry.hasComponent<components::Animation>(state.getFill())) {
341 registry.getComponent<components::Animation>(state.getFill())
343 .stop();
344 }
345 this->clearEntities();
346
347 std::shared_ptr<ecs::Entity> track;
348 std::shared_ptr<ecs::Entity> fill;
349 if (state.isCircular()) {
350 track = std::make_shared<CircularTrack>(registry);
351 fill = std::make_shared<CircularFill>(registry);
352 } else {
353 track = std::make_shared<LinearTrack>(registry);
354 fill = std::make_shared<LinearFill>(registry);
355 }
356 track->setParent(shared_from_this());
357 this->addEntity(track);
358 fill->setParent(shared_from_this());
359 this->addEntity(fill);
360 state.setTrack(track->getIdentifier())
361 .setFill(fill->getIdentifier())
362 .setCycle(0.0f)
363 .setBuilt(true);
365
366 // Track and fill are positioned by systems::ProgressIndicator, so
367 // they are not registered as layout children of the surface.
368 setChildren({});
369 }
370
371 ProgressIndicator &ProgressIndicator::setVariant(Variant variant)
372 {
373 auto &state =
375 getIdentifier());
376
377 if (state.getVariant() == variant) {
378 return *this;
379 }
380
381 // Children are built from the variant: rebuild them so the new shape
382 // (bar vs. ring) is adopted.
383 state.setVariant(variant).setBuilt(false);
384 buildChildren();
386 getIdentifier());
387
388 return *this;
389 }
390
397
398 ProgressIndicator &ProgressIndicator::setValue(float value)
399 {
401 getIdentifier(), value);
402 return *this;
403 }
404
411
412 void ProgressIndicator::build(void)
413 {
414 buildChildren();
416 getIdentifier());
417 }
418
419} // 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 progress indicator: a bar or a ring that fills up with a value from 0 to 1,...
static constexpr float DefaultTrackLength
Default length of the linear track, in dp.
static constexpr float LinearHeight
Thickness of the linear track, in dp.
static constexpr float DefaultDiameter
Default diameter of the circular variants, in dp.
ProgressIndicator & setTrackLength(float length)
Set the length of the track of the linear variants.
ProgressIndicator & setDiameter(float diameter)
Set the diameter of the circular variants.
ProgressIndicator & setVariant(Variant variant)
Set the shape of the indicator and whether it shows a value.
ProgressIndicator & setBuilt(bool built)
Record whether the track and fill children match the current variant.
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.
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 ProgressIndicator, then builds it and registers it in the entity registry given at const...
std::shared_ptr< ProgressIndicator > makeProgressIndicator(std::shared_ptr< ecs::Entity > parent, Variant variant, float value)
Build a progress indicator, register it under parent and reset the builder.
Builder & withValue(float value)
Set the progress the indicator starts with.
Builder & withWidth(float width)
Set the length of the bar of the linear variants.
Builder & withSize(float size)
Set the diameter of the ring of the circular variants.
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Create a builder set to the defaults of reset().
Builder & withPose(const utility::graphic::PoseF &pose)
Set the pose the indicator is created with.
Builder & withVariant(Variant variant)
Set the indicator variant.
std::shared_ptr< ProgressIndicator > buildEntity(void) override
Build a progress indicator and its track and fill children from the current configuration,...
void reset(void) override
Restore the defaults: LinearDeterminate variant, value 0, a 200 dp long bar, a 48 dp wide ring and a ...
Variant getVariant(void) const
Get the indicator variant.
ProgressIndicator & setVariant(Variant variant)
Change the indicator variant.
ProgressIndicator & setVisible(bool visible)
Show or hide the indicator with a 200 ms fade (Paper visible).
bool isVisible(void) const
Check whether the indicator is meant to be visible.
ProgressIndicator & setValue(float value)
Set the progress.
float getOpacity(void) const
Get the opacity of the fade.
float getValue(void) const
Get the progress last set.
components::ProgressIndicator::Variant Variant
static std::shared_ptr< ProgressIndicator > create(Arguments &&...arguments)
Create a progress indicator and its track and fill children, without registering it in an entity regi...
ProgressIndicator & setIndicatorColor(const utility::graphic::Color32Bit &color)
Set the color of the fill. Redraws at once.
utility::graphic::Color32Bit getIndicatorColor(void) const
Get the color of the fill.
float getDisplayedValue(void) const
Get the progress drawn at the moment.
~ProgressIndicator(void) override
Default destructor.
static void setVisible(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool visible)
Show or hide the indicator with a fade.
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.
static void installChildren(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Wire the looping animation of an indeterminate indicator and start it.
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.
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 hasFixedWidth
True when fixedWidth replaces the content width.
Definition surface.hpp:91
float fixedWidth
Width in dp, used only when hasFixedWidth.
Definition surface.hpp:94
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