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

Draws a progress indicator: a track and a fill that shows a value from 0 to 1, as a bar or as a ring. More...

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

Inheritance diagram for guillaume::systems::ProgressIndicator:
Collaboration diagram for guillaume::systems::ProgressIndicator:

Public Member Functions

 ProgressIndicator (void)
 Create the system in the Layout phase.
 ~ProgressIndicator (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Run apply() on one progress indicator; called by the frame loop.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::ProgressIndicator >
 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)
 Prepare the value, the transition and the accessibility role of a progress indicator.
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 and the opacity.
static void setValue (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, float value)
 Set the target value.
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 utility::graphic::Color32Bit indicatorColor (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Get the color of the fill at full opacity.

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 a progress indicator: a track and a fill that shows a value from 0 to 1, as a bar or as a ring.

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

Two numbers are kept apart: the target value, stored in components::Value, and the displayed value, stored in components::ProgressIndicator. When the target changes, the widget's components::Animation moves the displayed value to it over theme::MotionDuration::Short4 (200 ms). The same animation runs the fade started by setVisible().

The indeterminate variants ignore the value: a components::Animation on the fill child loops and moves a fixed-size segment along the track or around the ring. It is wired by installChildren().

systems::ProgressIndicator::setValue(registry, indicator, 0.4f);
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.
See also
components::ProgressIndicator, components::Value, entities::ProgressIndicator, systems::LoadingIndicator

Definition at line 71 of file progress_indicator.hpp.

Constructor & Destructor Documentation

◆ ProgressIndicator()

guillaume::systems::ProgressIndicator::ProgressIndicator ( void )

Create the system in the Layout phase.

Definition at line 120 of file progress_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::ProgressIndicator::apply ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Size one progress indicator and draw its track and fill from the displayed value, the cycle position and the opacity.

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

A linear indicator is a track of the configured length and components::ProgressIndicator::LinearHeight; its fill starts at the left edge and covers the displayed fraction of the track. A circular indicator is a ring of the configured diameter; its fill is an arc starting at the top and sweeping the displayed fraction of a turn. The accessibility value published is the target value, not the displayed one. The children are left untouched while the track or the fill has no Bound or no Color.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe progress indicator entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::ProgressIndicator, Layout, Borders, Color or Accessibility, or components::Value for a determinate variant.

Definition at line 199 of file progress_indicator.cpp.

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

◆ indicatorColor()

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

Get the color of the fill at full opacity.

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

Definition at line 358 of file progress_indicator.cpp.

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

◆ install()

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

Prepare the value, the transition and the accessibility role of a progress indicator.

  • Sets the range of the entity's components::Value to 0 to 1, without step.
  • Takes the value held at that moment as the displayed value, so it is drawn without a transition.
  • Makes every later change of the value call startTransition().
  • Sets up the widget's own components::Animation so that each sample moves the displayed value and the opacity towards their targets and calls apply().
  • Sets the role of components::Accessibility to ProgressBar.

Call it once, after the entity has its components::ProgressIndicator, Value, Animation, Accessibility, Layout, Borders, Color, Transform and Bound.

Parameters
componentRegistryThe registry holding the components. It is captured by the handlers and must outlive the entity.
entityIdentifierThe progress indicator entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::ProgressIndicator, Value, Animation or Accessibility.

Definition at line 125 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ installChildren()

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

Wire the looping animation of an indeterminate indicator and start it.

Makes the components::Animation of the fill child loop, write the cycle position (0 to 1) on each sample and call apply(), then plays it. Call it each time the track and fill children have been recorded in the component, for instance after the variant changed and they were rebuilt. Does nothing for a determinate variant or when the fill has no components::Animation.

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

Definition at line 171 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setValue()

void guillaume::systems::ProgressIndicator::setValue ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
float value )
static

Set the target value.

Writes components::Value. Once install() has been called, a real change starts the transition that moves the drawn value to the new target.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe progress indicator entity.
valueThe new progress, from 0 (empty) to 1 (complete). Values outside that range are clamped.

Definition at line 320 of file progress_indicator.cpp.

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

◆ setVisible()

void guillaume::systems::ProgressIndicator::setVisible ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
bool visible )
static

Show or hide the indicator with a fade.

Records the target visibility in components::ProgressIndicator and calls startTransition(). Does nothing when the visibility is already the requested one.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe progress indicator entity.
visibleTrue to fade in, false to fade out.

Definition at line 328 of file progress_indicator.cpp.

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

◆ startTransition()

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

Start moving the drawn value and opacity towards their targets.

Records what is drawn at that moment as the starting point, plays the widget's components::Animation and calls apply(). Starting from what is drawn keeps a transition that is interrupted by a new one continuous. setValue() and setVisible() end up here; there is usually no need to call it directly.

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

Definition at line 343 of file progress_indicator.cpp.

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

◆ update()

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

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

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

Parameters
entityIdentifierThe progress indicator entity.

Implements guillaume::ecs::System.

Definition at line 368 of file progress_indicator.cpp.

Here is the call graph for this function:

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