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

Keeps at most one child selected in each selection group. More...

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

Inheritance diagram for guillaume::systems::Selection:
Collaboration diagram for guillaume::systems::Selection:

Public Member Functions

 Selection (void)
 Create the system, in the Event phase.
 ~Selection (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Reconcile one group with the children listed in its components::Hierarchy.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::SelectionGroup, components::Transform, components::Bound >
 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 ecs::Entity::Identifier reconcile (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &groupIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers)
 Make a group and its children agree on which child is selected.
static ecs::Entity::Identifier select (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &groupIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, ecs::Entity::Identifier selectedIdentifier)
 Select one child of a group, at once.

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

Keeps at most one child selected in each selection group.

Runs in the Event phase on entities that have a components::SelectionGroup, a Transform and a Bound. The members of a group are its direct children in the tree, read from components::Hierarchy (a group without one is skipped); only the children with a components::Selectable take part. The system writes the selected flag of those children and the selected identifier of the group.

The rules are in the static functions, so a widget system can apply them at once instead of waiting for the frame:

// Select `second` among the children of `group`.
systems::Selection::select(registry, group, children, second);
static ecs::Entity::Identifier select(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &groupIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, ecs::Entity::Identifier selectedIdentifier)
Select one child of a group, at once.
See also
components::Selectable
components::SelectionGroup
systems::RadioGroup

Definition at line 58 of file selection.hpp.

Constructor & Destructor Documentation

◆ Selection()

guillaume::systems::Selection::Selection ( void )

Create the system, in the Event phase.

Definition at line 30 of file selection.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ reconcile()

ecs::Entity::Identifier guillaume::systems::Selection::reconcile ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & groupIdentifier,
const std::vector< ecs::Entity::Identifier > & childIdentifiers )
static

Make a group and its children agree on which child is selected.

  • When one or more children are selected, the first one in childIdentifiers wins: the others are deselected and the group records the winner.
  • When none is selected, the child the group last recorded is selected again if it still has a components::Selectable (it is not checked against childIdentifiers).
  • Otherwise, a group that does not allow an empty selection selects its first selectable child; a group that allows it has its selection cleared.

Because of the second rule, deselecting the selected child does not empty the group: the child is selected again on the next call. To empty a group, call components::SelectionGroup::clearSelection as well.

Parameters
registryThe registry holding the components.
groupIdentifierThe entity holding the components::SelectionGroup.
childIdentifiersThe children of the group, in order. Those without a components::Selectable are ignored.
Returns
The selected child, or ecs::Entity::InvalidIdentifier when the group ends up with no selection.

Definition at line 55 of file selection.cpp.

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

◆ select()

ecs::Entity::Identifier guillaume::systems::Selection::select ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & groupIdentifier,
const std::vector< ecs::Entity::Identifier > & childIdentifiers,
ecs::Entity::Identifier selectedIdentifier )
static

Select one child of a group, at once.

Selects selectedIdentifier, deselects every other selectable child, then calls reconcile() so the group records the result. systems::NavigationBar and systems::NavigationDrawer use it to change the active destination.

Parameters
registryThe registry holding the components.
groupIdentifierThe entity holding the components::SelectionGroup.
childIdentifiersThe children of the group, in order.
selectedIdentifierThe child to select. With ecs::Entity::InvalidIdentifier, or an identifier that is not a selectable child, every child is deselected and reconcile() then applies its "none selected" rules, which select the previously recorded child again when it still exists.
Returns
The child selected after reconciliation, or ecs::Entity::InvalidIdentifier when there is none.

Definition at line 118 of file selection.cpp.

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

◆ update()

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

Reconcile one group with the children listed in its components::Hierarchy.

Parameters
entityIdentifierThe entity holding the components::SelectionGroup.

Implements guillaume::ecs::System.

Definition at line 36 of file selection.cpp.

Here is the call graph for this function:

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