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

A number kept inside a range, with a callback run when it changes. More...

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

Inheritance diagram for guillaume::components::Value:
Collaboration diagram for guillaume::components::Value:

Public Types

using Handler = std::function<void(float)>
 Callback receiving the new value, already clamped and snapped.

Public Member Functions

 Value (void)=default
 Create a value of 0 in the range 0 to 1, without snapping.
 ~Value (void)=default
 Default destructor for the Value component.
float getMin (void) const
 Get the lower bound of the range.
Value & setMin (float min)
 Set the lower bound of the range.
float getMax (void) const
 Get the upper bound of the range.
Value & setMax (float max)
 Set the upper bound of the range.
float getValue (void) const
 Get the current value.
Value & setValue (float value)
 Set the current value.
float getStep (void) const
 Get the snapping step.
Value & setStep (float step)
 Set the snapping step.
float getNormalizedValue (void) const
 Get where the value sits in its range.
Value & setNormalizedValue (float normalized)
 Set the value from its position in the range.
Value & setOnChangedHandler (const Handler &handler)
 Set the callback run when the value changes.
Handler getOnChangedHandler (void) const
 Get the callback run when the value changes.
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.

Detailed Description

A number kept inside a range, with a callback run when it changes.

The value always lies within [min, max] (0 to 1 by default) and is snapped to a multiple of step above min when step is strictly positive. The widget systems use it as the value of their widget: the fraction of a progress indicator (systems::ProgressIndicator), the on/off state of a switch (systems::Switch, 0 or 1 with a step of 1).

auto &value = registry.getComponent<components::Value>(identifier);
value.setMax(100.0f).setStep(5.0f);
value.setValue(42.0f); // stores 40
A number kept inside a range, with a callback run when it changes.
Definition value.hpp:56
Value & setValue(float value)
Set the current value.
Definition value.cpp:67
Value & setMax(float max)
Set the upper bound of the range.
Definition value.cpp:51
Value & setStep(float step)
Set the snapping step.
Definition value.cpp:86

Watch out:

  • The handler runs inside the setter, synchronously, each time the stored value really changes, including when a new bound clamps it.
  • Keep min <= max: when raising both bounds, set the maximum first.
See also
components::Range, systems::Switch, systems::ProgressIndicator

Definition at line 55 of file value.hpp.

Member Typedef Documentation

◆ Handler

using guillaume::components::Value::Handler = std::function<void(float)>

Callback receiving the new value, already clamped and snapped.

Definition at line 59 of file value.hpp.

Member Function Documentation

◆ getMax()

float guillaume::components::Value::getMax ( void ) const

Get the upper bound of the range.

Returns
The maximum (1 by default).

Definition at line 46 of file value.cpp.

◆ getMin()

float guillaume::components::Value::getMin ( void ) const

Get the lower bound of the range.

Returns
The minimum (0 by default).

Definition at line 30 of file value.cpp.

◆ getNormalizedValue()

float guillaume::components::Value::getNormalizedValue ( void ) const

Get where the value sits in its range.

Returns
0 at the minimum to 1 at the maximum, or 0 when the range is empty (max <= min).

Definition at line 96 of file value.cpp.

◆ getOnChangedHandler()

Value::Handler guillaume::components::Value::getOnChangedHandler ( void ) const

Get the callback run when the value changes.

Returns
A copy of the callback, empty when none is set.

Definition at line 117 of file value.cpp.

◆ getStep()

float guillaume::components::Value::getStep ( void ) const

Get the snapping step.

Returns
The step; 0 (the default) or less disables snapping.

Definition at line 81 of file value.cpp.

◆ getValue()

float guillaume::components::Value::getValue ( void ) const

Get the current value.

Returns
The value, within [min, max].

Definition at line 62 of file value.cpp.

◆ setMax()

Value & guillaume::components::Value::setMax ( float max)

Set the upper bound of the range.

When the bound differs, marks the component changed, then clamps and snaps the current value again, which runs the handler if the value moves.

Parameters
maxThe new maximum; it must not be below the minimum.
Returns
This component, for chaining.

Definition at line 51 of file value.cpp.

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

◆ setMin()

Value & guillaume::components::Value::setMin ( float min)

Set the lower bound of the range.

When the bound differs, marks the component changed, then clamps and snaps the current value again, which runs the handler if the value moves.

Parameters
minThe new minimum; it must not exceed the maximum.
Returns
This component, for chaining.

Definition at line 35 of file value.cpp.

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

◆ setNormalizedValue()

Value & guillaume::components::Value::setNormalizedValue ( float normalized)

Set the value from its position in the range.

Same as setValue() with min + normalized * (max - min).

Parameters
normalizedThe position, 0 to 1; values outside are clamped.
Returns
This component, for chaining.

Definition at line 105 of file value.cpp.

Here is the call graph for this function:

◆ setOnChangedHandler()

Value & guillaume::components::Value::setOnChangedHandler ( const Handler & handler)

Set the callback run when the value changes.

Replaces the previous handler. Does not mark the component changed. The widget systems install their own handler here to restyle the widget.

Parameters
handlerThe callback, or an empty one to remove it.
Returns
This component, for chaining.

Definition at line 111 of file value.cpp.

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

◆ setStep()

Value & guillaume::components::Value::setStep ( float step)

Set the snapping step.

Marks the component changed when the step differs. The current value is not snapped again until the next setValue() or bound change.

Parameters
stepThe distance between two allowed values, counted from the minimum; 0 or less disables snapping.
Returns
This component, for chaining.

Definition at line 86 of file value.cpp.

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

◆ setValue()

Value & guillaume::components::Value::setValue ( float value)

Set the current value.

The value is clamped to [min, max] and snapped to the step first. When the result differs from the stored value, stores it, marks the component changed and calls the handler with it.

Parameters
valueThe requested value, in the unit of the range.
Returns
This component, for chaining.

Definition at line 67 of file value.cpp.

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

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