guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::systems::LoadingIndicator Class Reference

Draws an indeterminate loading indicator: a rotating arc (circular variant) or a bar sliding along a track (linear variant). More...

#include <headers/guillaume/systems/loading_indicator.hpp>

Inheritance diagram for guillaume::systems::LoadingIndicator:
Collaboration diagram for guillaume::systems::LoadingIndicator:

Public Member Functions

 LoadingIndicator (void)
 Create the system in the Layout phase.
 ~LoadingIndicator (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Run apply() on one loading indicator; called by the frame loop.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::LoadingIndicator >
 SystemFiller (Phase phase)
 Create the system and set its signature from ComponentTypes.
virtual ~SystemFiller (void)=default
 Virtual destructor.
Public Member Functions inherited from guillaume::ecs::System
 System (Phase phase)
 Create a system that runs in a given phase, with an empty signature.
virtual ~System (void)=default
 Virtual destructor.
Phase getPhase (void) const noexcept
 Get the phase of the frame in which the system runs.
Entity::Signature getSignature (void) const noexcept
 Get the component types an entity must declare to be visited by this system.
void routine (ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry, const ecs::EntityTreeTraveler &traveler)
 Run the system once over a scene: prepare(), update() on each matching entity, cleanup().
void bindComponentRegistry (ecs::ComponentRegistry &componentRegistry)
 Bind a component registry so update() can be called directly, without routine().
void unbindComponentRegistry (void)
 Drop the binding made by bindComponentRegistry().
virtual void prepare (void)
 Called once per pass, before the first update().
virtual void cleanup (void)
 Called once per pass, after the last update().

Static Public Member Functions

static void install (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Give a loading indicator its accessibility role and its fade.
static void installChildren (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Wire the looping animation of the animated child and start it.
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 void start (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Start the looping animation and fade the indicator in.
static void stop (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Stop the looping animation.
static bool isRunning (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the looping animation is running.
static void startFade (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Start fading towards the opacity the running state calls for.
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 float strokeWidth (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Get the stroke width of the circular arc, in dp.

Additional Inherited Members

Protected Member Functions inherited from guillaume::ecs::System
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.
ecs::EntityRegistry & getEntityRegistry (void)
 Get the entity registry of the scene being processed.
const ecs::EntityRegistry & getEntityRegistry (void) const
 Get the entity registry of the scene being processed, read-only.
ecs::ComponentRegistry & getComponentRegistry (void)
 Get the component registry of the scene being processed.
const ecs::ComponentRegistry & getComponentRegistry (void) const
 Get the component registry of the scene being processed, read-only.
template<InheritFromComponent ComponentType>
bool hasComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Tell whether an entity has a component, in the bound registry.
template<InheritFromComponent ComponentType>
ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier)
 Get a component of an entity from the bound registry, to read or modify it.
template<InheritFromComponent ComponentType>
const ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Get a component of an entity from the bound registry, read-only.
template<InheritFromComponent ComponentType>
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 does not.

Detailed Description

Draws an indeterminate loading indicator: a rotating arc (circular variant) or a bar sliding along a track (linear variant).

Runs in the Layout phase on every entity that has a components::LoadingIndicator, after systems::Layout.

Two components::Animation drive the widget, and both restyle it on every sample, so the indicator moves even between two frames of this system:

  • the one on the child loops and writes the loop progress (0 to 1), which becomes the start angle of the arc or the offset of the bar. It is wired by installChildren();
  • the one on the widget runs the fade in and out and writes the opacity (0 to 1). It is wired by install().
// once the child entity is recorded in the component:
systems::LoadingIndicator::stop(registry, indicator);
static void installChildren(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Wire the looping animation of the animated child and start it.
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Give a loading indicator its accessibility role and its fade.
static void stop(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Stop the looping animation.
See also
components::LoadingIndicator, entities::LoadingIndicator, systems::Animation, systems::ProgressIndicator

Definition at line 67 of file loading_indicator.hpp.

Constructor & Destructor Documentation

◆ LoadingIndicator()

guillaume::systems::LoadingIndicator::LoadingIndicator ( void )

Create the system in the Layout phase.

Definition at line 78 of file loading_indicator.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

Member Function Documentation

◆ apply()

void guillaume::systems::LoadingIndicator::apply ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Size one loading indicator and draw its animated child at the current loop progress and opacity.

This is what update() runs each frame, and what both animations call on each sample. Call it directly after changing components::LoadingIndicator to see the result before the next frame.

A circular indicator is a square of the configured size holding an arc of three quarters of a turn whose start angle follows the progress. A linear indicator is a track of components::LoadingIndicator::LinearWidth by LinearHeight in which a shorter bar slides from the left edge to the right edge. The child is left untouched while it has no Bound or no Color.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe loading indicator entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::LoadingIndicator, Layout, Borders or Color.

Definition at line 134 of file loading_indicator.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ indicatorColor()

utility::graphic::Color32Bit guillaume::systems::LoadingIndicator::indicatorColor ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Get the color of the arc or bar at full opacity.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe loading indicator entity.
Returns
The color override of components::LoadingIndicator when one is set, otherwise the primary color of the active theme.

Definition at line 270 of file loading_indicator.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ install()

void guillaume::systems::LoadingIndicator::install ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Give a loading indicator its accessibility role and its fade.

Sets the role of its components::Accessibility to ProgressBar, and sets up the widget's own components::Animation so that each sample moves the opacity from the value recorded by startFade() to its target and calls apply(). Call it once, after the entity has its components::LoadingIndicator, Animation, Accessibility, Layout, Borders, Color, Transform and Bound.

Parameters
componentRegistryThe registry holding the components. It is captured by the sample handler and must outlive the entity.
entityIdentifierThe loading indicator entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity has no components::Accessibility or components::Animation.

Definition at line 83 of file loading_indicator.cpp.

Here is the call graph for this function:

◆ installChildren()

void guillaume::systems::LoadingIndicator::installChildren ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Wire the looping animation of the animated child and start it.

Makes the components::Animation of the child recorded in components::LoadingIndicator loop, write the loop progress on each sample and call apply(), then plays it: the indicator runs as soon as this returns. Call it each time a child has been recorded in the component, for instance after the variant changed and the child was rebuilt. Does nothing when the child has no components::Animation.

Parameters
componentRegistryThe registry holding the components. It is captured by the sample handler and must outlive the entity.
entityIdentifierThe loading indicator entity.

Definition at line 107 of file loading_indicator.cpp.

Here is the call graph for this function:

◆ isRunning()

bool guillaume::systems::LoadingIndicator::isRunning ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Whether the looping animation is running.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe loading indicator entity.
Returns
True when the animated child has a components::Animation that is playing; false when there is no such child.

Definition at line 235 of file loading_indicator.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ start()

void guillaume::systems::LoadingIndicator::start ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Start the looping animation and fade the indicator in.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe loading indicator entity.

Definition at line 207 of file loading_indicator.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ startFade()

void guillaume::systems::LoadingIndicator::startFade ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Start fading towards the opacity the running state calls for.

The target opacity is 1 while the indicator is running, or when it does not hide when stopped, and 0 otherwise. The fade starts from the current opacity and is played by the widget's own components::Animation. Does nothing when the indicator is already at the target. start() and stop() call it; call it yourself after changing the hide-when-stopped setting.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe loading indicator entity.

Definition at line 249 of file loading_indicator.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ stop()

void guillaume::systems::LoadingIndicator::stop ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Stop the looping animation.

The indicator also fades out when its component is set to hide when stopped; otherwise it stays visible, frozen where it stopped.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe loading indicator entity.

Definition at line 221 of file loading_indicator.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ strokeWidth()

float guillaume::systems::LoadingIndicator::strokeWidth ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Get the stroke width of the circular arc, in dp.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe loading indicator entity.
Returns
The configured size multiplied by components::LoadingIndicator::StrokeRatio (4 dp for a 48 dp indicator).

Definition at line 280 of file loading_indicator.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ update()

void guillaume::systems::LoadingIndicator::update ( const ecs::Entity::Identifier & entityIdentifier)
overridevirtual

Run apply() on one loading indicator; called by the frame loop.

Logs a warning and does nothing when the entity has no components::LoadingIndicator.

Parameters
entityIdentifierThe loading indicator entity.

Implements guillaume::ecs::System.

Definition at line 290 of file loading_indicator.cpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files: