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

The rules of a radio group: a list of radio buttons of which at most one is selected. More...

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

Inheritance diagram for guillaume::systems::RadioGroup:
Collaboration diagram for guillaume::systems::RadioGroup:

Public Member Functions

 RadioGroup (void)
 Create the system for the Layout phase, matching entities that have a components::RadioGroup.
 ~RadioGroup (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Frame entry point: call apply on one radio group.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::RadioGroup >
 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 radio group.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Make the radio buttons agree with the value of the group, then stack them.
static void select (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Select an option from code and show it at once.
static void press (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Select an option as a click on its radio button 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 radio group: a list of radio buttons of which at most one is selected.

The group entity is a layout container. Its options are radio button children built by entities::RadioGroup and recorded by identifier, in option order, in components::RadioGroup. The value of the group (the index of the selected option, or none) is the source of truth: each frame, the radio buttons are made to agree with it.

// Select the third option from code; no callback is called.
systems::RadioGroup::select(registry, identifier, 2);
static void select(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Select an option from code and show it at once.

Selecting a radio button of the group directly (through its own components::Selectable) does not change the value of the group: the next apply puts the button back. Go through select or press. The list of children in the group's components::Layout is overwritten each frame.

See also
guillaume::components::RadioGroup, guillaume::systems::RadioButton, guillaume::systems::Selection

Definition at line 67 of file radio_group.hpp.

Constructor & Destructor Documentation

◆ RadioGroup()

guillaume::systems::RadioGroup::RadioGroup ( void )

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

Definition at line 36 of file radio_group.cpp.

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

Member Function Documentation

◆ apply()

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

Make the radio buttons agree with the value of the group, then stack them.

The button at the index of the value is selected and every other one deselected; with no value, all are deselected. Only buttons whose selection differs are touched. When the group has a components::Layout, the buttons become its children and systems::Layout::apply places them at once.

The frame calls it through update; select and press call it too. Call it yourself after writing components::RadioGroup::setValue directly.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe radio group entity.

Definition at line 108 of file radio_group.cpp.

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

◆ install()

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

Make an entity behave as a radio group.

Gives the entity a components::Accessibility (added when missing) with the RadioGroup role, not focusable itself, and replaces the press callback of every radio button recorded in the component with one that calls press with the index of that button.

Call it once the radio buttons exist and are recorded in the component, and again whenever they change. A button identifier without a components::RadioButton is skipped. It does not select or place anything: apply does.

Parameters
componentRegistryThe registry holding the components. The press callbacks keep its address, so it must outlive the group.
entityIdentifierThe radio group entity. It must have a components::RadioGroup.

Definition at line 41 of file radio_group.cpp.

Here is the call graph for this function:

◆ press()

void guillaume::systems::RadioGroup::press ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Select an option as a click on its radio button does.

Writes the value of the group, calls apply, then calls the value-change callback of the component with the index, but only when the value really changed: pressing the selected option again calls nothing.

The press callbacks set by install call it; call it directly to simulate a click in a test.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe radio group entity.
indexThe zero-based index of the pressed option. The call does nothing, and does not throw, when it is not smaller than the number of radio buttons of the component.

Definition at line 86 of file radio_group.cpp.

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

◆ select()

void guillaume::systems::RadioGroup::select ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Select an option from code and show it at once.

Writes the value of the group and calls apply. The value-change callback is not called.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe radio group entity.
indexThe zero-based index of the option to select.
Exceptions
std::out_of_rangeIf index is not smaller than the number of option labels of the component. Nothing is changed in that case.

Definition at line 72 of file radio_group.cpp.

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

◆ update()

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

Frame entry point: call apply on one radio group.

Parameters
entityIdentifierThe radio group entity. An entity without a components::RadioGroup is logged and skipped.

Implements guillaume::ecs::System.

Definition at line 148 of file radio_group.cpp.

Here is the call graph for this function:

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