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

An animation that loops for as long as work is in progress: a rotating arc or a sliding bar, with no value. More...

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

Inheritance diagram for guillaume::entities::LoadingIndicator:
Collaboration diagram for guillaume::entities::LoadingIndicator:

Classes

class  Builder
 Configures a LoadingIndicator, then builds it and registers it in the entity registry given at construction. More...

Public Types

using Variant = components::LoadingIndicator::Variant
Public Types inherited from guillaume::entities::SurfaceBase< components::Animation, components::Accessibility, components::LoadingIndicator >
using Children
Public Types inherited from guillaume::ecs::Entity
using Identifier = std::size_t
 The key under which an entity's components are stored. Systems and components refer to entities by this value.
using Signature = std::bitset<128>
 A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits).

Public Member Functions

 ~LoadingIndicator (void) override
 Default destructor.
LoadingIndicator & setVariant (Variant variant)
 Change the indicator variant.
Variant getVariant (void) const
 Get the indicator variant.
LoadingIndicator & start (void)
 Start the looping animation and fade the indicator in over 200 ms.
LoadingIndicator & stop (void)
 Stop the looping animation.
bool isRunning (void) const
 Check whether the looping animation is playing.
LoadingIndicator & setHidesWhenStopped (bool hides)
 Choose whether a stopped indicator is hidden (Paper hidesWhenStopped).
bool hidesWhenStopped (void) const
 Check whether a stopped indicator is hidden.
float getOpacity (void) const
 Get the opacity of the fade.
LoadingIndicator & setIndicatorColor (const utility::graphic::Color32Bit &color)
 Set the color of the arc or bar. Redraws at once.
utility::graphic::Color32Bit getIndicatorColor (void) const
 Get the color of the arc or bar.
LoadingIndicator & setSize (float size)
 Set the diameter of the Circular variant (Paper size).
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.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Animation, components::Accessibility, components::LoadingIndicator >
 ~SurfaceBase (void) override=default
 Default destructor.
SurfaceBase & setPose (const utility::graphic::PoseF &pose)
 Move the surface.
SurfaceBase & setColor (const utility::graphic::Color32Bit &color)
 Set the fill color (Color component).
SurfaceBase & setBorderRadius (float radius)
 Set the radius of the four corners (Borders component).
SurfaceBase & setSurfaceConfig (const SurfaceConfig &config)
 Apply every field of a configuration at once.
SurfaceConfig getSurfaceConfig (void) const
 Read the current configuration back from the components.
SurfaceBase & setChildren (const Children &children)
 Choose the children this surface arranges, in order.
std::vector< ecs::Entity::Identifier > getChildren (void) const
 Get the children this surface arranges.
Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
 ParentEntityFiller (ComponentRegistry &componentRegistry)
 Create the entity, its listed components and its components::Hierarchy. It owns no child yet.
virtual ~ParentEntityFiller (void)=default
 Destroy the entity object and release the children it owns; components stay in the registry (see EntityRegistry::removeEntity).
Public Member Functions inherited from guillaume::ecs::Entity
 Entity (void)
 Create an entity with a fresh identifier, an empty signature, no parent and no component.
virtual ~Entity (void)=default
 Destroy the entity object.
Entity::Identifier getIdentifier (void) const noexcept
 Get the identifier of the entity.
Entity::Signature getSignature (void) const noexcept
 Get the set of component types the entity declares.
void setSignature (const Signature &signature)
 Replace the signature of the entity.
std::int32_t getLayer (void) const noexcept
 Get the depth of the entity in the tree.
Entity & setParent (std::shared_ptr< Entity > parent)
 Attach the entity under another one, or detach it.
std::vector< Identifier > releaseComponents (void)
 Drop the entity's place in the tree and all its components.
std::shared_ptr< Entity > getParent (void) const noexcept
 Get the parent entity.
Public Member Functions inherited from guillaume::ecs::EntityRegistry
 EntityRegistry (void)=default
 Create a registry.
virtual ~EntityRegistry (void)=default
 Virtual destructor.
void addEntity (std::shared_ptr< Entity > entity)
 Make this registry own an entity, so that it stays alive and systems visit it.
bool removeEntity (Entity::Identifier identifier)
 Remove an entity, with its children and all their components.
void clearEntities (void)
 Remove every entity owned by this registry, with everything they own and all their components.
const std::vector< std::shared_ptr< Entity > > & getEntities (void) const
 Get the entities this registry owns directly.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void)
 List every entity of this registry and of the registries nested in it, level by level.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void) const
 List every entity of this registry and of the registries nested in it, level by level (const overload).
template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > getEntity (Entity::Identifier identifier)
 Find an entity owned directly by this registry, by identifier.
template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > getEntity (Entity::Identifier identifier) const
 Find an entity owned directly by this registry, by identifier (const overload).
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature) const
 List the entities that have every component type of a signature, from the root down.
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const
 List the entities that have every component type of a signature, in the order chosen by a traveler.

Static Public Member Functions

template<typename... Arguments>
static std::shared_ptr< LoadingIndicator > create (Arguments &&...arguments)
 Create a loading indicator and its animated child, without registering it in an entity registry.
Static Public Member Functions inherited from guillaume::ecs::Entity
template<InheritFromComponent... ComponentTypes>
static Signature getSignatureFromTypes (void)
 Build the signature that has exactly the bits of the given component types.

Additional Inherited Members

Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity
Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::Animation, components::Accessibility, components::LoadingIndicator >
 SurfaceBase (ecs::ComponentRegistry &registry, const SurfaceConfig &config)
 Create the entity with its components and apply a configuration.
void applyGeometry (void)
 Arrange the layout children now with systems::Layout::apply.
Protected Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
ComponentRegistry & getComponentRegistry (void)
 Get the registry that stores this entity's components.
Protected Member Functions inherited from guillaume::ecs::ParentEntity
std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) override
 Give access to the list of entities this entity owns directly.
const std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) const override
 Give read access to the list of entities this entity owns directly.
Protected Member Functions inherited from guillaume::ecs::Entity
void attachHierarchy (ComponentRegistry &componentRegistry)
 Give the entity a components::Hierarchy in a registry and add that component to its signature.
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.

Detailed Description

An animation that loops for as long as work is in progress: a rotating arc or a sliding bar, with no value.

Its state lives in components::LoadingIndicator (variant, diameter, color, running animation and fade values). systems::LoadingIndicator sizes the widget and draws its animated child each frame, in the Layout phase. The class itself holds no field: its setters write the component and redraw at once.

getEntityRegistry());
auto spinner = builder.makeLoadingIndicator(parent,
LoadingIndicator::Variant::Circular);
// later, when the work is done:
spinner->stop();
Configures a LoadingIndicator, then builds it and registers it in the entity registry given at constr...

LoadingIndicator::create(registry, config, variant) builds the same widget without registering it in an entity registry.

What drives the animation: the indicator has one child, the arc or the bar, which carries a looping components::Animation of 1.5 second per cycle. systems::Animation samples it every frame, in the Event phase, and the sample moves the child. The widget's own components::Animation runs the 200 ms fade used by stop() and start().

The variants are:

  • Circular: an arc of three quarters of a turn rotating in a 48 dp square by default (see setSize()).
  • Linear: an 80 dp bar sliding along a 200 dp long, 4 dp thick strip.

Things to know:

  • The animation starts as soon as the indicator is created.
  • By default a stopped indicator fades out and stays invisible, but it keeps its place in its parent's layout.
  • systems::LoadingIndicator overwrites the widget's size, padding, color and corner radius every frame; set the size with setSize().
See also
components::LoadingIndicator, systems::LoadingIndicator, ProgressIndicator

Definition at line 90 of file loading_indicator.hpp.

Member Typedef Documentation

◆ Variant

Shape of the indicator: Linear (sliding bar) or Circular (rotating arc).

Definition at line 97 of file loading_indicator.hpp.

Constructor & Destructor Documentation

◆ ~LoadingIndicator()

guillaume::entities::LoadingIndicator::~LoadingIndicator ( void )
override

Default destructor.

Definition at line 269 of file loading_indicator.cpp.

Member Function Documentation

◆ create()

template<typename... Arguments>
std::shared_ptr< LoadingIndicator > guillaume::entities::LoadingIndicator::create ( Arguments &&... arguments)
inlinestatic

Create a loading indicator and its animated child, without registering it in an entity registry.

The arguments are forwarded to the private constructor: (registry, config, variant). For the Circular variant, a fixed height in config is taken as the diameter. The child is built here, by build(), because a child needs its parent to be owned by a shared pointer.

Template Parameters
ArgumentsThe constructor argument types.
Parameters
argumentsThe constructor arguments, as listed above.
Returns
The new indicator, already animating, with no parent.

Definition at line 189 of file loading_indicator.hpp.

Here is the caller graph for this function:

◆ getIndicatorColor()

utility::graphic::Color32Bit guillaume::entities::LoadingIndicator::getIndicatorColor ( void ) const

Get the color of the arc or bar.

Returns
The color given to setIndicatorColor(), or the theme's primary color when none was given. The fade opacity is not applied to it.

Definition at line 229 of file loading_indicator.cpp.

Here is the call graph for this function:

◆ getOpacity()

float guillaume::entities::LoadingIndicator::getOpacity ( void ) const

Get the opacity of the fade.

Returns
The opacity, 0 (hidden) to 1 (fully drawn); in between while a fade is running.

Definition at line 211 of file loading_indicator.cpp.

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

◆ getSize()

float guillaume::entities::LoadingIndicator::getSize ( void ) const

Get the diameter of the Circular variant.

Returns
The diameter, in dp (48 by default).

Definition at line 256 of file loading_indicator.cpp.

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

◆ getStrokeWidth()

float guillaume::entities::LoadingIndicator::getStrokeWidth ( void ) const

Get the thickness of the arc of the Circular variant.

Returns
The thickness, in dp: the diameter divided by 12, which gives 4 dp at the default 48 dp.

Definition at line 263 of file loading_indicator.cpp.

Here is the call graph for this function:

◆ getVariant()

LoadingIndicator::Variant guillaume::entities::LoadingIndicator::getVariant ( void ) const

Get the indicator variant.

Returns
The variant stored in components::LoadingIndicator.

Definition at line 330 of file loading_indicator.cpp.

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

◆ hidesWhenStopped()

bool guillaume::entities::LoadingIndicator::hidesWhenStopped ( void ) const

Check whether a stopped indicator is hidden.

Returns
True when it fades out on stop().

Definition at line 204 of file loading_indicator.cpp.

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

◆ isRunning()

bool guillaume::entities::LoadingIndicator::isRunning ( void ) const

Check whether the looping animation is playing.

Returns
True between start() and stop(); true for a new indicator.

Definition at line 351 of file loading_indicator.cpp.

Here is the call graph for this function:

◆ setHidesWhenStopped()

LoadingIndicator & guillaume::entities::LoadingIndicator::setHidesWhenStopped ( bool hides)

Choose whether a stopped indicator is hidden (Paper hidesWhenStopped).

Takes effect at once: a stopped indicator fades out, or back in, over 200 ms.

Parameters
hidesTrue to hide the indicator while stopped. Default: true.
Returns
This indicator, for chaining.

Definition at line 194 of file loading_indicator.cpp.

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

◆ setIndicatorColor()

LoadingIndicator & guillaume::entities::LoadingIndicator::setIndicatorColor ( const utility::graphic::Color32Bit & color)

Set the color of the arc or bar. Redraws at once.

Parameters
colorThe color, used in place of the theme's primary color.
Returns
This indicator, for chaining.

Definition at line 218 of file loading_indicator.cpp.

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

◆ setSize()

LoadingIndicator & guillaume::entities::LoadingIndicator::setSize ( float size)

Set the diameter of the Circular variant (Paper size).

For a Circular indicator, rebuilds the arc, starts its animation and redraws at once. A Linear indicator only stores the value, for a later switch to Circular.

Parameters
sizeThe diameter, in dp; must be positive.
Returns
This indicator, for chaining.
Exceptions
std::invalid_argumentIf size is not positive.

Definition at line 235 of file loading_indicator.cpp.

Here is the call graph for this function:

◆ setVariant()

LoadingIndicator & guillaume::entities::LoadingIndicator::setVariant ( Variant variant)

Change the indicator variant.

Does nothing when variant is the current one. Otherwise replaces the animated child by the arc or the bar of the new variant, starts its animation (even if the indicator was stopped) and redraws at once.

Parameters
variantThe new variant.
Returns
This indicator, for chaining.

Definition at line 310 of file loading_indicator.cpp.

Here is the call graph for this function:

◆ start()

LoadingIndicator & guillaume::entities::LoadingIndicator::start ( void )

Start the looping animation and fade the indicator in over 200 ms.

A new indicator is already started.

Returns
This indicator, for chaining.

Definition at line 337 of file loading_indicator.cpp.

Here is the call graph for this function:

◆ stop()

LoadingIndicator & guillaume::entities::LoadingIndicator::stop ( void )

Stop the looping animation.

The indicator then fades out over 200 ms, unless setHidesWhenStopped(false) was called, in which case it stays drawn, still.

Returns
This indicator, for chaining.

Definition at line 344 of file loading_indicator.cpp.

Here is the call graph for this function:

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