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

State of a checkbox: checked state, variant, label, color overrides and the identifiers of its check glyph and label children. More...

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

Inheritance diagram for guillaume::components::Checkbox:
Collaboration diagram for guillaume::components::Checkbox:

Public Types

enum class  State { Unchecked , Checked , Indeterminate }
 Checked state. More...
enum class  Variant { Enabled , Disabled , Error }
 Visual variant. More...
using ValueChangeHandler = std::function<void(State)>
 Called with the new state when the user toggles the box.

Public Member Functions

 Checkbox (void)=default
 Create the state of an enabled, unchecked checkbox with no label.
 ~Checkbox (void)=default
 Default destructor.
State getState (void) const noexcept
 Get the checked state.
Checkbox & setState (State state)
 Store the checked state.
Variant getVariant (void) const noexcept
 Get the visual variant.
Checkbox & setVariant (Variant variant)
 Choose the visual variant.
const std::string & getLabel (void) const noexcept
 Get the label text.
Checkbox & setLabel (const std::string &label)
 Set the label text.
ecs::Entity::Identifier getCheckIcon (void) const noexcept
 Get the child entity that draws the check glyph.
Checkbox & setCheckIcon (ecs::Entity::Identifier identifier)
 Record which child entity draws the check glyph.
ecs::Entity::Identifier getLabelEntity (void) const noexcept
 Get the child entity that draws the label.
Checkbox & setLabelEntity (ecs::Entity::Identifier identifier)
 Record which child entity draws the label.
const std::optional< utility::graphic::Color32Bit > & getCheckedColor (void) const noexcept
 Get the color that replaces the themed fill of a checked box.
Checkbox & setCheckedColor (std::optional< utility::graphic::Color32Bit > color)
 Replace the themed fill of a checked or indeterminate box.
const std::optional< utility::graphic::Color32Bit > & getUncheckedColor (void) const noexcept
 Get the color that replaces the themed outline of an unchecked box.
Checkbox & setUncheckedColor (std::optional< utility::graphic::Color32Bit > color)
 Replace the themed outline of an unchecked box.
const ValueChangeHandler & getOnValueChange (void) const noexcept
 Get the callback run when the user toggles the box.
Checkbox & setOnValueChange (ValueChangeHandler handler)
 Set the callback run when the user toggles the box.
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 TouchTarget = 40.0f
 Edge of the square touch target centered on the box, in dp.
static constexpr float LabelGap = 4.0f
 Gap between the touch target and the label, in dp.

Detailed Description

State of a checkbox: checked state, variant, label, color overrides and the identifiers of its check glyph and label children.

Role in the frame:

The entity also has a components::Selectable that mirrors the state (selected unless Unchecked). setState() here does not update it: to change the state from code call systems::Checkbox::setState(), which writes both and restyles at once. A user press goes through systems::Checkbox::toggle(), which also runs the value-change callback.

systems::Checkbox::setState(registry, identifier,
components::Checkbox::State::Indeterminate);
static void setState(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, components::Checkbox::State state)
Set the state of a checkbox from code and show it at once.
Definition checkbox.cpp:156
See also
systems::Checkbox, components::Selectable

Definition at line 62 of file checkbox.hpp.

Member Typedef Documentation

◆ ValueChangeHandler

Called with the new state when the user toggles the box.

Definition at line 83 of file checkbox.hpp.

Member Enumeration Documentation

◆ State

Checked state.

Indeterminate draws a dash in a filled box. A user press on an Indeterminate or Unchecked box checks it.

Definition at line 71 of file checkbox.hpp.

◆ Variant

Visual variant.

Enabled is the regular look. Disabled greys the checkbox and makes it ignore presses. Error draws the box and the label in the error color and ignores the color overrides.

Definition at line 80 of file checkbox.hpp.

Member Function Documentation

◆ getCheckedColor()

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

Get the color that replaces the themed fill of a checked box.

Returns
The color, or std::nullopt when the theme decides.

Definition at line 100 of file checkbox.cpp.

◆ getCheckIcon()

ecs::Entity::Identifier guillaume::components::Checkbox::getCheckIcon ( void ) const
noexcept

Get the child entity that draws the check glyph.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the checkbox has no check glyph child.

Definition at line 71 of file checkbox.cpp.

◆ getLabel()

const std::string & guillaume::components::Checkbox::getLabel ( void ) const
noexcept

Get the label text.

Returns
The text, empty when the checkbox has no label.

Definition at line 57 of file checkbox.cpp.

◆ getLabelEntity()

ecs::Entity::Identifier guillaume::components::Checkbox::getLabelEntity ( void ) const
noexcept

Get the child entity that draws the label.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the checkbox has no label child.

Definition at line 85 of file checkbox.cpp.

◆ getOnValueChange()

const Checkbox::ValueChangeHandler & guillaume::components::Checkbox::getOnValueChange ( void ) const
noexcept

Get the callback run when the user toggles the box.

Returns
The callback, empty when none is set.

Definition at line 132 of file checkbox.cpp.

◆ getState()

Checkbox::State guillaume::components::Checkbox::getState ( void ) const
noexcept

Get the checked state.

Returns
Unchecked (the default), Checked or Indeterminate.

Definition at line 29 of file checkbox.cpp.

Here is the caller graph for this function:

◆ getUncheckedColor()

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

Get the color that replaces the themed outline of an unchecked box.

Returns
The color, or std::nullopt when the theme decides.

Definition at line 116 of file checkbox.cpp.

◆ getVariant()

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

Get the visual variant.

Returns
The variant (Enabled by default).

Definition at line 43 of file checkbox.cpp.

◆ setCheckedColor()

Checkbox & guillaume::components::Checkbox::setCheckedColor ( std::optional< utility::graphic::Color32Bit > color)

Replace the themed fill of a checked or indeterminate box.

Marks the component changed when the color differs. Ignored by the Disabled and Error variants.

Parameters
colorThe fill color, or std::nullopt to follow the theme (the primary color).
Returns
This component, for chaining.

Definition at line 105 of file checkbox.cpp.

Here is the call graph for this function:

◆ setCheckIcon()

Checkbox & guillaume::components::Checkbox::setCheckIcon ( ecs::Entity::Identifier identifier)

Record which child entity draws the check glyph.

Marks the component changed when the identifier differs. The system makes the glyph transparent unless the state is Checked.

Parameters
identifierThe check glyph child.
Returns
This component, for chaining.

Definition at line 76 of file checkbox.cpp.

Here is the call graph for this function:

◆ setLabel()

Checkbox & guillaume::components::Checkbox::setLabel ( const std::string & label)

Set the label text.

Marks the component changed when the text differs. The system copies it to the checkbox's Accessibility label; the text drawn on screen is the one of the label child.

Parameters
labelThe label text.
Returns
This component, for chaining.

Definition at line 62 of file checkbox.cpp.

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

◆ setLabelEntity()

Checkbox & guillaume::components::Checkbox::setLabelEntity ( ecs::Entity::Identifier identifier)

Record which child entity draws the label.

Marks the component changed when the identifier differs.

Parameters
identifierThe label child.
Returns
This component, for chaining.

Definition at line 90 of file checkbox.cpp.

Here is the call graph for this function:

◆ setOnValueChange()

Checkbox & guillaume::components::Checkbox::setOnValueChange ( ValueChangeHandler handler)

Set the callback run when the user toggles the box.

It is not run when the state is set from code. Does not mark the component changed.

Parameters
handlerThe callback; it receives the new state.
Returns
This component, for chaining.

Definition at line 137 of file checkbox.cpp.

Here is the call graph for this function:

◆ setState()

Checkbox & guillaume::components::Checkbox::setState ( State state)

Store the checked state.

Marks the component changed when the state differs. It does not update the entity's Selectable nor run the callback; prefer systems::Checkbox::setState().

Parameters
stateThe new state.
Returns
This component, for chaining.

Definition at line 34 of file checkbox.cpp.

Here is the call graph for this function:

◆ setUncheckedColor()

Checkbox & guillaume::components::Checkbox::setUncheckedColor ( std::optional< utility::graphic::Color32Bit > color)

Replace the themed outline of an unchecked box.

Marks the component changed when the color differs. Ignored by the Disabled and Error variants.

Parameters
colorThe outline color, or std::nullopt to follow the theme.
Returns
This component, for chaining.

Definition at line 121 of file checkbox.cpp.

Here is the call graph for this function:

◆ setVariant()

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

Choose the visual variant.

Marks the component changed when the variant differs. The system enables or disables the entity's interaction to match.

Parameters
variantEnabled, Disabled or Error.
Returns
This component, for chaining.

Definition at line 48 of file checkbox.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ LabelGap

float guillaume::components::Checkbox::LabelGap = 4.0f
staticconstexpr

Gap between the touch target and the label, in dp.

Definition at line 89 of file checkbox.hpp.

◆ TouchTarget

float guillaume::components::Checkbox::TouchTarget = 40.0f
staticconstexpr

Edge of the square touch target centered on the box, in dp.

Definition at line 86 of file checkbox.hpp.


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