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

A bar or a ring that fills up to show how far a task has progressed, or that loops when the progress is unknown. More...

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

Inheritance diagram for guillaume::entities::ProgressIndicator:
Collaboration diagram for guillaume::entities::ProgressIndicator:

Classes

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

Public Types

using Variant = components::ProgressIndicator::Variant
Public Types inherited from guillaume::entities::SurfaceBase< components::Value, components::Animation, components::Accessibility, components::ProgressIndicator >
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

 ~ProgressIndicator (void) override
 Default destructor.
ProgressIndicator & setVariant (Variant variant)
 Change the indicator variant.
Variant getVariant (void) const
 Get the indicator variant.
ProgressIndicator & setValue (float value)
 Set the progress.
float getValue (void) const
 Get the progress last set.
float getDisplayedValue (void) const
 Get the progress drawn at the moment.
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.
float getOpacity (void) const
 Get the opacity of the fade.
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.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Value, components::Animation, components::Accessibility, components::ProgressIndicator >
 ~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< ProgressIndicator > create (Arguments &&...arguments)
 Create a progress indicator and its track and fill children, 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.

Static Public Attributes

static constexpr float IndeterminateSegment
 Length of the sliding segment of the LinearIndeterminate variant, as a fraction of the bar length: 0.6 (Paper uses 60%).
Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity

Additional Inherited Members

Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::Value, components::Animation, components::Accessibility, components::ProgressIndicator >
 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

A bar or a ring that fills up to show how far a task has progressed, or that loops when the progress is unknown.

The progress, 0 (nothing done) to 1 (complete), lives in components::Value. The rest of the state lives in components::ProgressIndicator (variant, dimensions, color, visibility, running transition values). systems::ProgressIndicator sizes the widget and draws its track and fill each frame, in the Layout phase. The class itself holds no field: its setters write the components and redraw at once.

getEntityRegistry());
auto progress = builder.withWidth(240.0f).makeProgressIndicator(parent,
ProgressIndicator::Variant::LinearDeterminate, 0.0f);
// later, as the task advances:
progress->setValue(0.5f);
Configures a ProgressIndicator, then builds it and registers it in the entity registry given at const...

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

The widget has two children: the track, drawn in full, and the fill, drawn over it. The variants are:

  • LinearDeterminate: a 4 dp thick bar, 200 dp long by default, filled from its start up to the value.
  • LinearIndeterminate: the same bar, with a segment of 60% of its length sliding along it.
  • CircularDeterminate: a 4 dp thick ring, 48 dp wide by default, whose arc starts at the top and covers the value.
  • CircularIndeterminate: the same ring, with a quarter-turn arc rotating around it.

What drives the animations: the widget's own components::Animation runs the 200 ms transition of the drawn value toward a new value, and the 200 ms fade of setVisible(). In the indeterminate variants the fill child carries a looping components::Animation of 1.5 second per cycle, started when the child is built. systems::Animation samples both every frame, in the Event phase.

Things to know:

  • Values outside 0 to 1 are clamped. The indeterminate variants store the value but do not draw it.
  • The value given at creation is drawn as is; only later changes are animated.
  • The length and the diameter are chosen in the builder and cannot be changed afterwards. After a setVariant() from a bar to a ring or back, the shape the indicator was not created with has its default size (200 dp long or 48 dp wide).
  • A hidden indicator keeps its place in its parent's layout.
  • systems::ProgressIndicator overwrites the widget's size, padding, color and corner radius every frame.
See also
components::ProgressIndicator, systems::ProgressIndicator, LoadingIndicator

Definition at line 104 of file progress_indicator.hpp.

Member Typedef Documentation

◆ Variant

Shape and kind of the indicator: a bar or a ring, determinate (shows a value) or indeterminate (loops).

Definition at line 112 of file progress_indicator.hpp.

Constructor & Destructor Documentation

◆ ~ProgressIndicator()

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

Default destructor.

Definition at line 324 of file progress_indicator.cpp.

Member Function Documentation

◆ create()

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

Create a progress indicator and its track and fill children, without registering it in an entity registry.

The arguments are forwarded to the private constructor: (registry, config, variant, value). A fixed width in the config is taken as the length of the bar (linear variants) and a fixed height as the diameter of the ring (circular variants). The children are 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, visible, with no parent.

Definition at line 226 of file progress_indicator.hpp.

Here is the caller graph for this function:

◆ getDisplayedValue()

float guillaume::entities::ProgressIndicator::getDisplayedValue ( void ) const

Get the progress drawn at the moment.

Returns
The drawn progress, 0 to 1. It follows getValue() with a 200 ms transition and equals it once the transition is over.

Definition at line 278 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ getIndicatorColor()

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

Get the color of the fill.

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 318 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ getOpacity()

float guillaume::entities::ProgressIndicator::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 299 of file progress_indicator.cpp.

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

◆ getValue()

float guillaume::entities::ProgressIndicator::getValue ( void ) const

Get the progress last set.

Returns
The progress, 0 to 1. It is the target value, not the one being drawn during a transition.

Definition at line 405 of file progress_indicator.cpp.

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

◆ getVariant()

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

Get the indicator variant.

Returns
The variant stored in components::ProgressIndicator.

Definition at line 391 of file progress_indicator.cpp.

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

◆ isVisible()

bool guillaume::entities::ProgressIndicator::isVisible ( void ) const

Check whether the indicator is meant to be visible.

Returns
The value last given to setVisible(), true by default. It changes at once, before the fade ends; see getOpacity().

Definition at line 292 of file progress_indicator.cpp.

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

◆ setIndicatorColor()

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

Set the color of the fill. Redraws at once.

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

Definition at line 306 of file progress_indicator.cpp.

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

◆ setValue()

ProgressIndicator & guillaume::entities::ProgressIndicator::setValue ( float value)

Set the progress.

Writes components::Value. The fill does not jump: the drawn value moves to the new one over 200 ms (see getDisplayedValue()).

Parameters
valueThe new progress, 0 (nothing done) to 1 (complete); a value outside is clamped.
Returns
This indicator, for chaining.

Definition at line 398 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setVariant()

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

Change the indicator variant.

Does nothing when variant is the current one. Otherwise replaces the track and fill children by those of the new variant, starts the looping animation when it is indeterminate, and redraws at once. The value is kept.

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

Definition at line 371 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setVisible()

ProgressIndicator & guillaume::entities::ProgressIndicator::setVisible ( bool visible)

Show or hide the indicator with a 200 ms fade (Paper visible).

Does nothing when the indicator is already in that state.

Parameters
visibleTrue to fade in, false to fade out.
Returns
This indicator, for chaining.

Definition at line 285 of file progress_indicator.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ IndeterminateSegment

float guillaume::entities::ProgressIndicator::IndeterminateSegment
staticconstexpr
Initial value:

Length of the sliding segment of the LinearIndeterminate variant, as a fraction of the bar length: 0.6 (Paper uses 60%).

Definition at line 328 of file progress_indicator.hpp.


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