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

The rules of a checkbox: toggling it, coloring its box and placing its label. More...

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

Inheritance diagram for guillaume::systems::Checkbox:
Collaboration diagram for guillaume::systems::Checkbox:

Public Member Functions

 Checkbox (void)
 Create the system for the Layout phase, matching entities that have a components::Checkbox.
 ~Checkbox (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Frame entry point: call apply on one checkbox.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Checkbox >
 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)
 Make an entity behave as a checkbox.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Draw one checkbox from its component: colors, accessibility and label position.
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.
static void toggle (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Toggle the checkbox as a click does.
static bool isDisabled (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the checkbox ignores input and is drawn disabled.

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

The rules of a checkbox: toggling it, coloring its box and placing its label.

The checkbox entity is the 18 dp box itself. Its check glyph and its optional label are child entities, recorded by identifier in components::Checkbox.

// Check a box from code; the value-change callback is not called.
systems::Checkbox::setState(registry, identifier,
components::Checkbox::State::Checked);
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

The Disabled variant wins over systems::interaction::setEnabled: apply rewrites the enabled flag from the variant each frame.

See also
guillaume::components::Checkbox, guillaume::entities::Checkbox, guillaume::systems::interaction

Definition at line 65 of file checkbox.hpp.

Constructor & Destructor Documentation

◆ Checkbox()

guillaume::systems::Checkbox::Checkbox ( void )

Create the system for the Layout phase, matching entities that have a components::Checkbox.

Definition at line 99 of file checkbox.cpp.

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

Member Function Documentation

◆ apply()

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

Draw one checkbox from its component: colors, accessibility and label position.

  • Checked or Indeterminate: the box is filled with the checked color of the component, or Primary when none is set; no outline. Checked shows the check glyph, Indeterminate a 2 dp dash.
  • Unchecked: transparent fill and a 2 dp outline in the unchecked color of the component, or OnSurfaceVariant when none is set.
  • Error variant: Error replaces those colors, custom ones included, and tints the label.
  • Disabled: the disabled content color replaces the fill of a checked box, the outline of an unchecked one and the label color, and no hover or press tint is shown.

The label is placed to the right of the touch target, after components::Checkbox::LabelGap, vertically centered on the box.

The frame calls it through update. Call it yourself after writing components::Checkbox when the result must be visible before the next Layout phase; the setters of entities::Checkbox do.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe checkbox entity. It must have components::Checkbox, components::Color, components::Borders, components::Line and components::Accessibility. The check glyph and the label are optional.

Definition at line 187 of file checkbox.cpp.

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

◆ install()

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

Make an entity behave as a checkbox.

Does three things:

  • calls systems::interaction::makeInteractive with the Checkbox accessibility role, so a click or a hand press calls toggle and any hover or press change calls apply;
  • sets the accessibility margin of the hover components so the box can be hit on a square of components::Checkbox::TouchTarget (40 dp) without being drawn larger;
  • sets the selection handler of components::Selectable so a selection written from outside (a selection group, for example) becomes Checked or Unchecked and is drawn at once. An Indeterminate box keeps its state.

Call it once when the entity is built; entities::Checkbox does it for you. It does not style anything: call apply after it.

Parameters
componentRegistryThe registry holding the components. The handlers keep its address, so it must outlive the entity.
entityIdentifierThe checkbox entity. It must already have components::Checkbox, components::Selectable and a components::Layout whose fixed width is the width of the box.

Definition at line 104 of file checkbox.cpp.

Here is the call graph for this function:

◆ isDisabled()

bool guillaume::systems::Checkbox::isDisabled ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Whether the checkbox ignores input and is drawn disabled.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe checkbox entity.
Returns
True when the variant of components::Checkbox is Disabled or when the components::StyleState of the entity is not enabled.

Definition at line 146 of file checkbox.cpp.

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

◆ setState()

void guillaume::systems::Checkbox::setState ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
components::Checkbox::State state )
static

Set the state of a checkbox from code and show it at once.

Writes the state, marks components::Selectable selected for Checked and Indeterminate and unselected for Unchecked, then calls apply. The value-change callback is not called, and the call works on a disabled checkbox. It is also the only way to reach the Indeterminate state.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe checkbox entity. It must have a components::Selectable.
stateThe state to show.

Definition at line 156 of file checkbox.cpp.

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

◆ toggle()

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

Toggle the checkbox as a click does.

Checked becomes Unchecked; Unchecked and Indeterminate become Checked. The new state is drawn at once (through setState), then the value-change callback of the component is called with it. Nothing happens, and nothing is called, when the checkbox is disabled.

The handlers set by install call it; call it directly to simulate a click, for example in a test on a bare identifier.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe checkbox entity.

Definition at line 167 of file checkbox.cpp.

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

◆ update()

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

Frame entry point: call apply on one checkbox.

Parameters
entityIdentifierThe checkbox entity. An entity without a components::Checkbox is logged and skipped.

Implements guillaume::ecs::System.

Definition at line 273 of file checkbox.cpp.

Here is the call graph for this function:

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