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

A box the user checks, unchecks or leaves indeterminate, with an optional label next to it. More...

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

Inheritance diagram for guillaume::entities::Checkbox:
Collaboration diagram for guillaume::entities::Checkbox:

Classes

class  Builder
 Configures, creates and registers Checkbox widgets. More...

Public Types

using State = components::Checkbox::State
 Checked state: Unchecked, Checked or Indeterminate.
using Variant = components::Checkbox::Variant
Public Types inherited from guillaume::entities::SurfaceBase< components::Selectable, components::Line, components::Checkbox >
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

 ~Checkbox (void) override=default
 Default destructor.
Checkbox & setState (State state)
 Set the state. Restyles at once.
State getState (void) const
 Get the state.
Checkbox & setVariant (Variant variant)
 Set the visual variant. Restyles at once.
Variant getVariant (void) const
 Get the visual variant.
Checkbox & setLabel (const std::string &label)
 Set the label text and the accessibility label. Restyles at once.
bool isChecked (void) const
 Check whether the checkbox's components::Selectable is selected.
Checkbox & toggle (void)
 Toggle as a user activation would: a checked box becomes unchecked, an unchecked or indeterminate box becomes checked. Restyles at once.
bool isDisabled (void) const
 Check whether the checkbox ignores input.
Checkbox & setOnValueChange (std::function< void(State)> onValueChange)
 Set the handler called when the user toggles the box, or when toggle() is called.
Checkbox & setCheckedColor (std::optional< utility::graphic::Color32Bit > color)
 Override the fill color of the checked and indeterminate box (Paper color). Restyles at once.
Checkbox & setUncheckedColor (std::optional< utility::graphic::Color32Bit > color)
 Override the outline color of the unchecked box (Paper uncheckedColor). Restyles at once.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Selectable, components::Line, components::Checkbox >
 ~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< Checkbox > create (Arguments &&...arguments)
 Create a checkbox and its check glyph and label 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 TouchTarget = components::Checkbox::TouchTarget
 Side of the square that answers input, centered on the box, in dp.
static constexpr float LabelGap = components::Checkbox::LabelGap
 Gap between the touch target and the label, in dp.
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::Selectable, components::Line, components::Checkbox >
 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 box the user checks, unchecks or leaves indeterminate, with an optional label next to it.

Its state lives in components::Checkbox (state, variant, label, colors, callback, child identifiers); systems::Checkbox styles the box and places the label each frame, in the Layout phase. The class itself holds no field: its setters write the component and restyle at once.

The three states are drawn as follows:

  • Unchecked: transparent box with an outline.
  • Checked: filled box with a check glyph.
  • Indeterminate: filled box with a horizontal stroke (components::Line).
Checkbox::Builder builder(getComponentRegistry(), getEntityRegistry());
auto checkbox = builder.makeCheckbox(parent, Checkbox::State::Unchecked,
Checkbox::Variant::Enabled, "Accept the terms");
checkbox->setOnValueChange([](Checkbox::State state) {
// called when the user toggles the box
});
Configures, creates and registers Checkbox widgets.
Definition checkbox.hpp:108
components::Checkbox::State State
Checked state: Unchecked, Checked or Indeterminate.
Definition checkbox.hpp:95

Checkbox::create(registry, config, state, variant, label) builds the same widget without registering it in an entity registry; config is the SurfaceConfig of the box (pose, size).

The checkbox owns its check glyph and label children: it is the entity registry they are registered in. The label child is built only when the label given at creation is not empty. The box is 18 dp wide and answers input on a TouchTarget square centered on it. Its Color, Borders and enabled state are written each frame from the state and the variant, so values set by hand on them are overwritten. setState() does not call the value-change handler; a user activation and toggle() do.

See also
components::Checkbox, systems::Checkbox, RadioButton

Definition at line 89 of file checkbox.hpp.

Member Typedef Documentation

◆ State

Checked state: Unchecked, Checked or Indeterminate.

Definition at line 95 of file checkbox.hpp.

◆ Variant

Visual variant: Enabled, Disabled (ignores input) or Error (error colors).

Definition at line 99 of file checkbox.hpp.

Member Function Documentation

◆ create()

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

Create a checkbox and its check glyph and label children, without registering it in an entity registry.

The constructor is private because the children need a checkbox already held by a std::shared_ptr as parent: create() constructs the checkbox then calls build(), which creates them.

Template Parameters
ArgumentsThe types of the constructor arguments.
Parameters
argumentsThe arguments forwarded to the constructor: (registry, config, state, variant, label).
Returns
The new checkbox.

Definition at line 209 of file checkbox.hpp.

Here is the caller graph for this function:

◆ getState()

Checkbox::State guillaume::entities::Checkbox::getState ( void ) const

Get the state.

Returns
The state stored in components::Checkbox.

Definition at line 172 of file checkbox.cpp.

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

◆ getVariant()

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

Get the visual variant.

Returns
The variant stored in components::Checkbox.

Definition at line 188 of file checkbox.cpp.

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

◆ isChecked()

bool guillaume::entities::Checkbox::isChecked ( void ) const

Check whether the checkbox's components::Selectable is selected.

setState() and toggle() select it for every state but Unchecked, so an indeterminate checkbox also reports true. Use getState() to tell the three states apart.

Returns
True when selected.

Definition at line 211 of file checkbox.cpp.

Here is the call graph for this function:

◆ isDisabled()

bool guillaume::entities::Checkbox::isDisabled ( void ) const

Check whether the checkbox ignores input.

Returns
True for Variant::Disabled.

Definition at line 130 of file checkbox.cpp.

Here is the call graph for this function:

◆ setCheckedColor()

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

Override the fill color of the checked and indeterminate box (Paper color). Restyles at once.

The Error and Disabled variants keep their own colors.

Parameters
colorThe custom color, or std::nullopt for the theme color.
Returns
Reference to this checkbox for chaining.

Definition at line 145 of file checkbox.cpp.

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

◆ setLabel()

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

Set the label text and the accessibility label. Restyles at once.

The text on screen changes only when the checkbox was created with a label: no label child is built here.

Parameters
labelThe new label text.
Returns
Reference to this checkbox for chaining.

Definition at line 195 of file checkbox.cpp.

Here is the call graph for this function:

◆ setOnValueChange()

Checkbox & guillaume::entities::Checkbox::setOnValueChange ( std::function< void(State)> onValueChange)

Set the handler called when the user toggles the box, or when toggle() is called.

Parameters
onValueChangeThe function that receives the new state. Pass an empty function to remove the handler.
Returns
Reference to this checkbox for chaining.

Definition at line 137 of file checkbox.cpp.

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

◆ setState()

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

Set the state. Restyles at once.

The value-change handler is not called.

Parameters
stateThe new state: Unchecked, Checked or Indeterminate.
Returns
Reference to this checkbox for chaining.

Definition at line 165 of file checkbox.cpp.

Here is the call graph for this function:

◆ setUncheckedColor()

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

Override the outline color of the unchecked box (Paper uncheckedColor). Restyles at once.

The Error and Disabled variants keep their own colors.

Parameters
colorThe custom color, or std::nullopt for the theme color.
Returns
Reference to this checkbox for chaining.

Definition at line 155 of file checkbox.cpp.

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

◆ setVariant()

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

Set the visual variant. Restyles at once.

Parameters
variantEnabled, Disabled (ignores input) or Error (error colors).
Returns
Reference to this checkbox for chaining.

Definition at line 179 of file checkbox.cpp.

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

◆ toggle()

Checkbox & guillaume::entities::Checkbox::toggle ( void )

Toggle as a user activation would: a checked box becomes unchecked, an unchecked or indeterminate box becomes checked. Restyles at once.

Calls the value-change handler with the new state. Does nothing while the checkbox is disabled.

Returns
Reference to this checkbox for chaining.

Definition at line 124 of file checkbox.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ LabelGap

float guillaume::entities::Checkbox::LabelGap = components::Checkbox::LabelGap
staticconstexpr

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

Definition at line 332 of file checkbox.hpp.

◆ TouchTarget

float guillaume::entities::Checkbox::TouchTarget = components::Checkbox::TouchTarget
staticconstexpr

Side of the square that answers input, centered on the box, in dp.

Definition at line 327 of file checkbox.hpp.


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