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

State of a progress indicator: a bar or a ring that fills up with a value from 0 to 1, or loops when the value is unknown. More...

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

Inheritance diagram for guillaume::components::ProgressIndicator:
Collaboration diagram for guillaume::components::ProgressIndicator:

Public Types

enum class  Variant { LinearDeterminate , LinearIndeterminate , CircularDeterminate , CircularIndeterminate }
 Shape of the indicator and whether it shows a value. More...

Public Member Functions

 ProgressIndicator (void)=default
 Create the state of a visible linear determinate indicator with the default sizes and no child.
 ~ProgressIndicator (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get the shape of the indicator and whether it shows a value.
ProgressIndicator & setVariant (Variant variant)
 Set the shape of the indicator and whether it shows a value.
bool isCircular (void) const noexcept
 Tell whether the indicator is a ring.
bool isIndeterminate (void) const noexcept
 Tell whether the indicator loops instead of showing a value.
float getTrackLength (void) const noexcept
 Get the length of the track of the linear variants.
ProgressIndicator & setTrackLength (float length)
 Set the length of the track of the linear variants.
float getDiameter (void) const noexcept
 Get the diameter of the circular variants.
ProgressIndicator & setDiameter (float diameter)
 Set the diameter of the circular variants.
ecs::Entity::Identifier getTrack (void) const noexcept
 Get the child that draws the track: the full bar or ring behind the fill.
ProgressIndicator & setTrack (ecs::Entity::Identifier identifier)
 Record the child that draws the track.
ecs::Entity::Identifier getFill (void) const noexcept
 Get the child that draws the fill: the part of the bar or ring that shows the progress.
ProgressIndicator & setFill (ecs::Entity::Identifier identifier)
 Record the child that draws the fill.
bool isBuilt (void) const noexcept
 Tell whether the track and fill children match the current variant.
ProgressIndicator & setBuilt (bool built)
 Record whether the track and fill children match the current variant.
float getDisplayed (void) const noexcept
 Get the value currently drawn.
ProgressIndicator & setDisplayed (float displayed)
 Store the value currently drawn.
float getValueFrom (void) const noexcept
 Get the value that was drawn when the running transition began.
ProgressIndicator & setValueFrom (float value)
 Store the value drawn at the start of a transition.
bool isVisible (void) const noexcept
 Tell whether the indicator is meant to be visible.
ProgressIndicator & setVisible (bool visible)
 Record whether the indicator is meant to be visible.
float getOpacity (void) const noexcept
 Get the opacity the indicator is drawn with.
ProgressIndicator & setOpacity (float opacity)
 Store the opacity the indicator is drawn with.
float getOpacityFrom (void) const noexcept
 Get the opacity the indicator had when the running fade began.
ProgressIndicator & setOpacityFrom (float opacity)
 Store the opacity at the start of a fade.
float getCycle (void) const noexcept
 Get how far the loop of an indeterminate variant has advanced.
ProgressIndicator & setCycle (float cycle)
 Store how far the loop of an indeterminate variant has advanced.
const std::optional< utility::graphic::Color32Bit > & getIndicatorColor (void) const noexcept
 Get the color chosen for the fill.
ProgressIndicator & setIndicatorColor (const std::optional< utility::graphic::Color32Bit > &color)
 Choose the color of the fill.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Static Public Attributes

static constexpr float DefaultTrackLength = 200.0f
 Default length of the linear track, in dp.
static constexpr float LinearHeight = 4.0f
 Thickness of the linear track, in dp.
static constexpr float DefaultDiameter = 48.0f
 Default diameter of the circular variants, in dp.
static constexpr float RingThickness = 4.0f
 Stroke width of the circular track and fill, in dp.
static constexpr float IndeterminateSegment = 0.6f
static constexpr float IndeterminateSweep = 0.25f

Detailed Description

State of a progress indicator: a bar or a ring that fills up with a value from 0 to 1, or loops when the value is unknown.

It holds two kinds of state. The configuration (variant, track length, diameter, color, visibility) and the identifiers of the track and fill children are written by the entities::ProgressIndicator widget. The running state (drawn value, fade opacity, loop progress) is written by systems::ProgressIndicator from the animations it installs. In the Layout phase, systems::ProgressIndicator turns all of it into the size of the widget and the geometry and color of the two children.

The value to reach is not stored here: it is the components::Value of the same entity. Set it with systems::ProgressIndicator::setValue; the drawn value then moves to it over a short animation.

See also
systems::ProgressIndicator, components::Value, entities::ProgressIndicator

Definition at line 55 of file progress_indicator.hpp.

Member Enumeration Documentation

◆ Variant

Shape of the indicator and whether it shows a value.

Enumerator
LinearDeterminate 

Bar filled up to the value.

LinearIndeterminate 

Bar with a segment that slides in a loop.

CircularDeterminate 

Ring filled up to the value.

CircularIndeterminate 

Ring with an arc that turns in a loop.

Definition at line 61 of file progress_indicator.hpp.

Member Function Documentation

◆ getCycle()

float guillaume::components::ProgressIndicator::getCycle ( void ) const
noexcept

Get how far the loop of an indeterminate variant has advanced.

Returns
The eased progress of the current loop, 0 to 1.

Definition at line 196 of file progress_indicator.cpp.

◆ getDiameter()

float guillaume::components::ProgressIndicator::getDiameter ( void ) const
noexcept

Get the diameter of the circular variants.

Returns
The diameter, in dp.

Definition at line 68 of file progress_indicator.cpp.

◆ getDisplayed()

float guillaume::components::ProgressIndicator::getDisplayed ( void ) const
noexcept

Get the value currently drawn.

Returns
The drawn value, 0 to 1. It trails the target value of components::Value while the transition runs.

Definition at line 126 of file progress_indicator.cpp.

◆ getFill()

ecs::Entity::Identifier guillaume::components::ProgressIndicator::getFill ( void ) const
noexcept

Get the child that draws the fill: the part of the bar or ring that shows the progress.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 97 of file progress_indicator.cpp.

Here is the caller graph for this function:

◆ getIndicatorColor()

const std::optional< utility::graphic::Color32Bit > & guillaume::components::ProgressIndicator::getIndicatorColor ( void ) const
noexcept

Get the color chosen for the fill.

Returns
The color, or std::nullopt when the fill uses the theme's Primary color.

Definition at line 211 of file progress_indicator.cpp.

◆ getOpacity()

float guillaume::components::ProgressIndicator::getOpacity ( void ) const
noexcept

Get the opacity the indicator is drawn with.

Returns
The opacity, 0 (hidden) to 1 (fully visible).

Definition at line 168 of file progress_indicator.cpp.

◆ getOpacityFrom()

float guillaume::components::ProgressIndicator::getOpacityFrom ( void ) const
noexcept

Get the opacity the indicator had when the running fade began.

Returns
The starting opacity, 0 to 1.

Definition at line 182 of file progress_indicator.cpp.

◆ getTrack()

ecs::Entity::Identifier guillaume::components::ProgressIndicator::getTrack ( void ) const
noexcept

Get the child that draws the track: the full bar or ring behind the fill.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when it has not been built.

Definition at line 82 of file progress_indicator.cpp.

◆ getTrackLength()

float guillaume::components::ProgressIndicator::getTrackLength ( void ) const
noexcept

Get the length of the track of the linear variants.

Returns
The length, in dp.

Definition at line 54 of file progress_indicator.cpp.

◆ getValueFrom()

float guillaume::components::ProgressIndicator::getValueFrom ( void ) const
noexcept

Get the value that was drawn when the running transition began.

Returns
The starting value, 0 to 1.

Definition at line 140 of file progress_indicator.cpp.

◆ getVariant()

ProgressIndicator::Variant guillaume::components::ProgressIndicator::getVariant ( void ) const
noexcept

Get the shape of the indicator and whether it shows a value.

Returns
The variant, Variant::LinearDeterminate by default.

Definition at line 28 of file progress_indicator.cpp.

◆ isBuilt()

bool guillaume::components::ProgressIndicator::isBuilt ( void ) const
noexcept

Tell whether the track and fill children match the current variant.

Returns
True once the widget has built them; false for a new component and after the widget changes the variant.

Definition at line 112 of file progress_indicator.cpp.

◆ isCircular()

bool guillaume::components::ProgressIndicator::isCircular ( void ) const
noexcept

Tell whether the indicator is a ring.

Returns
True for the two circular variants.

Definition at line 42 of file progress_indicator.cpp.

◆ isIndeterminate()

bool guillaume::components::ProgressIndicator::isIndeterminate ( void ) const
noexcept

Tell whether the indicator loops instead of showing a value.

Returns
True for the two indeterminate variants.

Definition at line 48 of file progress_indicator.cpp.

◆ isVisible()

bool guillaume::components::ProgressIndicator::isVisible ( void ) const
noexcept

Tell whether the indicator is meant to be visible.

Returns
True when visible, which is the default. The indicator may still be fading; see getOpacity().

Definition at line 154 of file progress_indicator.cpp.

◆ setBuilt()

ProgressIndicator & guillaume::components::ProgressIndicator::setBuilt ( bool built)

Record whether the track and fill children match the current variant.

The widget lowers the flag when it changes the variant and raises it once it has rebuilt the children. Marks the component changed only when the flag differs.

Parameters
builtTrue when the children are up to date.
Returns
This component, for chaining.

Definition at line 117 of file progress_indicator.cpp.

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

◆ setCycle()

ProgressIndicator & guillaume::components::ProgressIndicator::setCycle ( float cycle)

Store how far the loop of an indeterminate variant has advanced.

Running state written by the looping animation of the fill child. It sets the position of the sliding segment or the start angle of the turning arc. Marks the component changed only when the value differs.

Parameters
cycleThe eased progress of the current loop, 0 to 1.
Returns
This component, for chaining.

Definition at line 201 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setDiameter()

ProgressIndicator & guillaume::components::ProgressIndicator::setDiameter ( float diameter)

Set the diameter of the circular variants.

The linear variants ignore it. Marks the component changed only when the value differs.

Parameters
diameterThe new diameter, in dp.
Returns
This component, for chaining.

Definition at line 73 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setDisplayed()

ProgressIndicator & guillaume::components::ProgressIndicator::setDisplayed ( float displayed)

Store the value currently drawn.

Running state written by systems::ProgressIndicator on every sample of the value transition. Marks the component changed only when the value differs.

Parameters
displayedThe drawn value, 0 to 1.
Returns
This component, for chaining.

Definition at line 131 of file progress_indicator.cpp.

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

◆ setFill()

ProgressIndicator & guillaume::components::ProgressIndicator::setFill ( ecs::Entity::Identifier identifier)

Record the child that draws the fill.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 103 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setIndicatorColor()

ProgressIndicator & guillaume::components::ProgressIndicator::setIndicatorColor ( const std::optional< utility::graphic::Color32Bit > & color)

Choose the color of the fill.

Marks the component changed only when the value differs.

Parameters
colorThe color, or std::nullopt to use the theme's Primary color.
Returns
This component, for chaining.

Definition at line 216 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setOpacity()

ProgressIndicator & guillaume::components::ProgressIndicator::setOpacity ( float opacity)

Store the opacity the indicator is drawn with.

Running state written by systems::ProgressIndicator on every sample of the fade. Marks the component changed only when the value differs.

Parameters
opacityThe opacity, 0 to 1.
Returns
This component, for chaining.

Definition at line 173 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setOpacityFrom()

ProgressIndicator & guillaume::components::ProgressIndicator::setOpacityFrom ( float opacity)

Store the opacity at the start of a fade.

The opacity is interpolated from this one to 1 (visible) or 0 (hidden). Marks the component changed only when the value differs.

Parameters
opacityThe starting opacity, 0 to 1.
Returns
This component, for chaining.

Definition at line 187 of file progress_indicator.cpp.

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

◆ setTrack()

ProgressIndicator & guillaume::components::ProgressIndicator::setTrack ( ecs::Entity::Identifier identifier)

Record the child that draws the track.

Marks the component changed only when the identifier differs.

Parameters
identifierThe child's identifier.
Returns
This component, for chaining.

Definition at line 88 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setTrackLength()

ProgressIndicator & guillaume::components::ProgressIndicator::setTrackLength ( float length)

Set the length of the track of the linear variants.

The circular variants ignore it. Marks the component changed only when the value differs.

Parameters
lengthThe new length, in dp.
Returns
This component, for chaining.

Definition at line 59 of file progress_indicator.cpp.

Here is the call graph for this function:

◆ setValueFrom()

ProgressIndicator & guillaume::components::ProgressIndicator::setValueFrom ( float value)

Store the value drawn at the start of a transition.

The drawn value is interpolated from this one to the target. Marks the component changed only when the value differs.

Parameters
valueThe starting value, 0 to 1.
Returns
This component, for chaining.

Definition at line 145 of file progress_indicator.cpp.

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

◆ setVariant()

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

Set the shape of the indicator and whether it shows a value.

The children depend on the variant; this setter does not rebuild them, the widget does. Marks the component changed only when the variant differs.

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

Definition at line 33 of file progress_indicator.cpp.

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

◆ setVisible()

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

Record whether the indicator is meant to be visible.

This only stores the flag. Use systems::ProgressIndicator::setVisible instead: it also starts the fade. Marks the component changed only when the flag differs.

Parameters
visibleTrue to show the indicator.
Returns
This component, for chaining.

Definition at line 159 of file progress_indicator.cpp.

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

Member Data Documentation

◆ DefaultDiameter

float guillaume::components::ProgressIndicator::DefaultDiameter = 48.0f
staticconstexpr

Default diameter of the circular variants, in dp.

Definition at line 77 of file progress_indicator.hpp.

◆ DefaultTrackLength

float guillaume::components::ProgressIndicator::DefaultTrackLength = 200.0f
staticconstexpr

Default length of the linear track, in dp.

Definition at line 71 of file progress_indicator.hpp.

◆ IndeterminateSegment

float guillaume::components::ProgressIndicator::IndeterminateSegment = 0.6f
staticconstexpr

Length of the sliding segment of the linear indeterminate variant, as a fraction of the track (0 to 1).

Definition at line 84 of file progress_indicator.hpp.

◆ IndeterminateSweep

float guillaume::components::ProgressIndicator::IndeterminateSweep = 0.25f
staticconstexpr

Length of the turning arc of the circular indeterminate variant, as a fraction of the ring (0 to 1).

Definition at line 88 of file progress_indicator.hpp.

◆ LinearHeight

float guillaume::components::ProgressIndicator::LinearHeight = 4.0f
staticconstexpr

Thickness of the linear track, in dp.

Definition at line 74 of file progress_indicator.hpp.

◆ RingThickness

float guillaume::components::ProgressIndicator::RingThickness = 4.0f
staticconstexpr

Stroke width of the circular track and fill, in dp.

Definition at line 80 of file progress_indicator.hpp.


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