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

Styles a list, stacks its rows and folds its accordions. More...

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

Inheritance diagram for guillaume::systems::List:
Collaboration diagram for guillaume::systems::List:

Public Types

using Path = components::List::Path
 Index path of an entry: top-level index, then child indices.

Public Member Functions

 List (void)
 Create the system in the Layout phase.
 ~List (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Run apply() on one list; called by the frame loop.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::List >
 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 every row of a list pressable.
static void installRow (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, const Path &path)
 Make one row pressable.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Style one list, then size and place its rows.
static void styleRow (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, const Path &path)
 Recolor one row without arranging the list again.
static void pressItem (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, const Path &path)
 Activate an entry as a press on its row would.
static void setItemDisabled (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, bool disabled)
 Enable or disable a top-level entry and restyle the list.
static void setExpanded (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, bool expanded)
 Expand or collapse a top-level accordion and arrange the list again.
static bool isExpanded (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
 Whether a top-level entry is expanded.

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

Styles a list, stacks its rows and folds its accordions.

Runs in the Layout phase on every entity that has a components::List. It is registered after systems::Layout, so the texts and icons of the rows are already measured when the rows are sized.

An entry is named by its components::List::Path: {2} is the third top-level entry, {2, 0} the first child of that entry. An entry with children is an accordion. Only the direct children of an expanded top-level accordion are shown. The other nested rows are not destroyed: they are left out of the layout, painted transparent and disabled.

systems::List::install(registry, list); // rows become pressable
systems::List::setExpanded(registry, list, 2, true);
systems::List::pressItem(registry, list, {2, 0});
static void pressItem(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, const Path &path)
Activate an entry as a press on its row would.
Definition list.cpp:421
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Make every row of a list pressable.
Definition list.cpp:366
static void setExpanded(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index, bool expanded)
Expand or collapse a top-level accordion and arrange the list again.
Definition list.cpp:454
See also
components::List, entities::List, systems::Layout

Definition at line 67 of file list.hpp.

Member Typedef Documentation

◆ Path

Index path of an entry: top-level index, then child indices.

Definition at line 71 of file list.hpp.

Constructor & Destructor Documentation

◆ List()

guillaume::systems::List::List ( void )

Create the system in the Layout phase.

Definition at line 361 of file list.cpp.

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

Member Function Documentation

◆ apply()

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

Style one list, then size and place its rows.

This is what update() runs each frame. Call it directly after changing components::List to see the result before the next frame, which is what the setters of entities::List do.

Every row is configured and colored, including the folded ones. The layout children of the list are its top-level rows, each followed by its children while it is an expanded accordion. The SingleLine variant hides the supporting text of every row.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe list entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::List, Layout, Color or Borders.

Definition at line 474 of file list.cpp.

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

◆ install()

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

Make every row of a list pressable.

Calls installRow() on each row recorded in components::List, nested rows included. Call it after the row entities have been created and recorded with components::List::setRows; rows recorded later need their own installRow(). The list entity needs its components::List, Layout, Transform, Bound, Color and Borders.

Parameters
componentRegistryThe registry holding the components. It is captured by the row handlers and must outlive the entity.
entityIdentifierThe list entity.

Definition at line 366 of file list.cpp.

Here is the call graph for this function:

◆ installRow()

void guillaume::systems::List::installRow ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
const Path & path )
static

Make one row pressable.

Adds the interaction components (hover and press state, focus, the ListItem accessibility role) to the pressable container of the row, and wires its activation to pressItem() and its hover and press changes to styleRow(). A subheader or a divider has no pressable container and is left alone.

Parameters
componentRegistryThe registry holding the components. It is captured by the row handlers and must outlive the entity.
entityIdentifierThe list entity.
pathIndex path of the row. A path that names no row is ignored.

Definition at line 381 of file list.cpp.

Here is the call graph for this function:

◆ isExpanded()

bool guillaume::systems::List::isExpanded ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index )
static

Whether a top-level entry is expanded.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe list entity.
indexPosition of the entry among the top-level entries, starting at 0.
Returns
True when the entry exists and its expanded flag is set; false for an index past the end.

Definition at line 463 of file list.cpp.

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

◆ pressItem()

void guillaume::systems::List::pressItem ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
const Path & path )
static

Activate an entry as a press on its row would.

A top-level accordion is expanded or collapsed first; then the press handler of the entry is called when it has one. Does nothing for a disabled entry or for a row that is folded away. Use it to trigger an entry from code or from a test.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe list entity.
pathIndex path of the entry. A path that names no entry is ignored.

Definition at line 421 of file list.cpp.

Here is the call graph for this function:

◆ setExpanded()

void guillaume::systems::List::setExpanded ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index,
bool expanded )
static

Expand or collapse a top-level accordion and arrange the list again.

The press handler of the entry is not called.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe list entity.
indexPosition of the entry among the top-level entries, starting at 0. An index past the end, or an entry without children, changes nothing.
expandedTrue to show the children of the entry, false to fold them away.

Definition at line 454 of file list.cpp.

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

◆ setItemDisabled()

void guillaume::systems::List::setItemDisabled ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
std::size_t index,
bool disabled )
static

Enable or disable a top-level entry and restyle the list.

A disabled entry is drawn with the disabled content color and ignores pressItem().

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe list entity.
indexPosition of the entry among the top-level entries, starting at 0. An index past the end changes nothing.
disabledTrue to disable the entry, false to enable it.

Definition at line 445 of file list.cpp.

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

◆ styleRow()

void guillaume::systems::List::styleRow ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
const Path & path )
static

Recolor one row without arranging the list again.

Writes the Color of the row, its headline, its supporting text and its icons from the enabled, hovered and pressed state of the row. A folded row is painted transparent. This is the cheap restyle run when the pointer enters, leaves or presses a row.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe list entity.
pathIndex path of the row. A path that names no row is ignored.

Definition at line 406 of file list.cpp.

Here is the call graph for this function:

◆ update()

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

Run apply() on one list; called by the frame loop.

Logs a warning and does nothing when the entity has no components::List.

Parameters
entityIdentifierThe list entity.

Implements guillaume::ecs::System.

Definition at line 542 of file list.cpp.

Here is the call graph for this function:

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