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

The rules of a switch: turning it on and off, coloring its track and placing its thumb, thumb icon and label. More...

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

Inheritance diagram for guillaume::systems::Switch:
Collaboration diagram for guillaume::systems::Switch:

Public Member Functions

 Switch (void)
 Create the system for the Layout phase, matching entities that have a components::Switch.
 ~Switch (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Frame entry point: call apply on one switch.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Switch >
 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 switch.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Draw one switch from its components: thumb position, colors and accessibility.
static bool isDisabled (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the switch ignores input and is drawn disabled.
static bool isChecked (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the switch is on.
static void setChecked (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool checked)
 Turn the switch on or off from code.
static void toggle (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Flip the switch as a click does.

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 switch: turning it on and off, coloring its track and placing its thumb, thumb icon and label.

The switch entity is the track itself. The thumb that slides in it, the optional icon on the thumb and the optional label are child entities, recorded by identifier in components::Switch. Whether the switch is on is not in that component: it is the components::Value of the entity, 0 for off and 1 for on.

// Turn a switch on from code; the value-change callback is not
// called.
systems::Switch::setChecked(registry, identifier, true);
static void setChecked(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool checked)
Turn the switch on or off from code.
Definition switch.cpp:109

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

See also
guillaume::components::Switch, guillaume::components::Value, guillaume::entities::Switch

Definition at line 65 of file switch.hpp.

Constructor & Destructor Documentation

◆ Switch()

guillaume::systems::Switch::Switch ( void )

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

Definition at line 61 of file switch.cpp.

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

Member Function Documentation

◆ apply()

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

Draw one switch from its components: thumb position, colors and accessibility.

  • Thumb: against the right end of the track when on, the left end when off, components::Switch::ThumbInset from the edge; OnPrimary when on, Outline when off. Its icon stays centered on it.
  • Track: Primary and no outline when on, SurfaceVariant with an Outline border when off.
  • Label: to the right of the track, after components::Switch::LabelGap, vertically centered on it.
  • Disabled variant: the track takes the disabled container color and the thumb, icon and label the disabled content color.

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

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe switch entity. It must have components::Switch, components::Value, components::Color, components::Borders and components::Accessibility. The thumb, its icon and the label are optional.

Definition at line 135 of file switch.cpp.

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

◆ install()

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

Make an entity behave as a switch.

Does two things:

Call it once when the entity is built; entities::Switch 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 switch entity. It must already have components::Switch and components::Value.

Definition at line 66 of file switch.cpp.

Here is the call graph for this function:

◆ isChecked()

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

Whether the switch is on.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe switch entity. It must have a components::Value.
Returns
True when the value of its components::Value is at least 0.5.

Definition at line 100 of file switch.cpp.

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

◆ isDisabled()

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

Whether the switch ignores input and is drawn disabled.

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

Definition at line 90 of file switch.cpp.

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

◆ setChecked()

void guillaume::systems::Switch::setChecked ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
bool checked )
static

Turn the switch on or off from code.

Writes 1 or 0 into components::Value. The value-change callback of components::Switch is not called, and the call works on a disabled switch. The switch is redrawn at once by the change handler install set on the value; on an entity that did not go through install, it is redrawn at the next Layout phase.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe switch entity.
checkedTrue to turn the switch on, false to turn it off.

Definition at line 109 of file switch.cpp.

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

◆ toggle()

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

Flip the switch as a click does.

Turns it on when off and off when on (through setChecked), then calls the value-change callback of the component with the new state. Nothing happens, and nothing is called, when the switch 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 switch entity.

Definition at line 117 of file switch.cpp.

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

◆ update()

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

Frame entry point: call apply on one switch.

Parameters
entityIdentifierThe switch entity. An entity without a components::Switch is logged and skipped.

Implements guillaume::ecs::System.

Definition at line 211 of file switch.cpp.

Here is the call graph for this function:

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