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

An on/off toggle: a rounded track with a thumb that slides to the right when on, an optional icon on the thumb and an optional label next to the track. More...

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

Inheritance diagram for guillaume::entities::Switch:
Collaboration diagram for guillaume::entities::Switch:

Classes

class  Builder
 Configures Switch widgets and registers them in the scene's entity registry. More...

Public Types

using Variant = components::Switch::Variant
Public Types inherited from guillaume::entities::SurfaceBase< components::Value, components::MouseButtonInteraction, components::HandButtonInteraction, components::Switch >
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

 ~Switch (void) override=default
 Destructor.
Switch & setVariant (Variant variant)
 Enable or disable the switch. Restyles at once.
Variant getVariant (void) const
 Get the variant of the switch.
Switch & setChecked (bool checked)
 Turn the switch on or off from code.
bool isChecked (void) const
 Whether the switch is on.
Switch & toggle (void)
 Flip the checked state, as a user activation would.
Switch & setOnValueChange (std::function< void(bool)> onValueChange)
 Set the handler called when the user toggles the switch (Paper onValueChange).
bool isDisabled (void) const
 Check whether the switch ignores input.
Switch & setLabel (const std::string &label)
 Change the text of the label. Restyles at once.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Value, components::MouseButtonInteraction, components::HandButtonInteraction, components::Switch >
 ~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< Switch > create (Arguments &&...arguments)
 Build a switch 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 LabelGap = components::Switch::LabelGap
 Gap between the track 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::Value, components::MouseButtonInteraction, components::HandButtonInteraction, components::Switch >
 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

An on/off toggle: a rounded track with a thumb that slides to the right when on, an optional icon on the thumb and an optional label next to the track.

Its state lives in components::Switch (variant, icon glyph, label, value-change handler, identifiers of its children) and in components::Value, which holds 0 when off and 1 when on. systems::Switch colors the track, places the thumb, icon and label and turns input into toggles; it runs each frame in the Layout phase. The class itself holds no field: its setters write the components and restyle at once.

Switch::Builder builder(getComponentRegistry(), getEntityRegistry());
auto wifi = builder.makeSwitch(parent, Switch::Variant::Enabled, false,
"", "Wi-Fi");
wifi->setOnValueChange([](bool checked) {
// called when the user toggles the switch
});
Configures Switch widgets and registers them in the scene's entity registry.
Definition switch.hpp:109

Switch::create(registry, config, variant, checked, iconGlyph, label) builds the same widget and its children without registering it in an entity registry.

Watch out:

  • setChecked() does not call the value-change handler; only a user activation and toggle() do.
  • The icon and the label are created only at construction, when their text is not empty. setLabel() changes the text of an existing label but does not create one.
  • The icon is shown whenever a glyph name is given, whatever the variant: WithIcon is styled like Enabled.
  • The Bound of the switch is its track (52 x 32 dp with the builder defaults). The label is drawn LabelGap dp to the right of it, outside the Bound, so a parent layout does not reserve room for it.
  • systems::Switch overwrites the track and stroke colors and the colors of the children every frame; SurfaceBase::setColor() does not last.
  • The switch owns its thumb, icon and label.
See also
components::Switch, systems::Switch, Checkbox

Definition at line 94 of file switch.hpp.

Member Typedef Documentation

◆ Variant

Whether the switch reacts to input: Enabled, Disabled (dimmed, ignores input) or WithIcon (styled like Enabled).

Definition at line 102 of file switch.hpp.

Member Function Documentation

◆ create()

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

Build a switch without registering it in an entity registry.

The arguments are forwarded to the private constructor: (registry, config, variant, checked, iconGlyph, label). It then calls build(), which creates the thumb and, when their text is not empty, the icon and the label.

Template Parameters
ArgumentsThe constructor argument types.
Parameters
argumentsThe constructor arguments, as listed above.
Returns
The new switch. The caller owns it; the switch owns its children.

Definition at line 216 of file switch.hpp.

Here is the caller graph for this function:

◆ getVariant()

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

Get the variant of the switch.

Returns
The variant stored in components::Switch.

Definition at line 195 of file switch.cpp.

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

◆ isChecked()

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

Whether the switch is on.

Returns
True when on, that is when its Value is at least 0.5.

Definition at line 209 of file switch.cpp.

Here is the call graph for this function:

◆ isDisabled()

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

Check whether the switch ignores input.

Returns
True for Variant::Disabled.

Definition at line 229 of file switch.cpp.

Here is the call graph for this function:

◆ setChecked()

Switch & guillaume::entities::Switch::setChecked ( bool checked)

Turn the switch on or off from code.

Writes components::Value; when the state changes, the thumb moves and the switch is restyled at once. It works on a disabled switch too. The value-change handler is not called.

Parameters
checkedTrue for on, false for off.
Returns
Reference to this switch for chaining.

Definition at line 202 of file switch.cpp.

Here is the call graph for this function:

◆ setLabel()

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

Change the text of the label. Restyles at once.

The new text is also the accessibility label. It is drawn only when the switch was built with a non-empty label: this function does not create the label child.

Parameters
labelThe new label.
Returns
Reference to this switch for chaining.

Definition at line 235 of file switch.cpp.

Here is the call graph for this function:

◆ setOnValueChange()

Switch & guillaume::entities::Switch::setOnValueChange ( std::function< void(bool)> onValueChange)

Set the handler called when the user toggles the switch (Paper onValueChange).

It is called after the state changed, on a user activation or toggle(), never on setChecked().

Parameters
onValueChangeThe function to call, receiving the new state (true for on). An empty function removes the handler.
Returns
Reference to this switch for chaining.

Definition at line 221 of file switch.cpp.

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

◆ setVariant()

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

Enable or disable the switch. Restyles at once.

Parameters
variantEnabled or WithIcon for a switch that reacts to input, Disabled for a dimmed switch that ignores it.
Returns
Reference to this switch for chaining.

Definition at line 186 of file switch.cpp.

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

◆ toggle()

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

Flip the checked state, as a user activation would.

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

Returns
Reference to this switch for chaining.

Definition at line 215 of file switch.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ LabelGap

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

Gap between the track and the label, in dp.

Definition at line 291 of file switch.hpp.


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