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

A vertical list of pressable rows, with optional subheaders, dividers and accordions that fold nested rows (Paper List.Section, List.Subheader, List.Item, List.Accordion, List.Icon and List.Image). More...

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

Inheritance diagram for guillaume::entities::List:
Collaboration diagram for guillaume::entities::List:

Classes

class  Builder
 Configures a List, creates it and registers it in an entity registry. More...

Public Types

using Variant = components::List::Variant
 List variant.
using ItemKind = components::List::ItemKind
 Kind of an entry.
using Item = components::List::Item
 List entry.
Public Types inherited from guillaume::entities::SurfaceBase< components::List >
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

 ~List (void) override
 Default destructor.
List & setVariant (Variant variant)
 Change the variant. Restyles at once; the rows are kept.
Variant getVariant (void) const
 Get the variant.
List & setItems (const std::vector< Item > &items)
 Replace the entries.
std::size_t getItemCount (void) const
 Get the number of top-level entries.
ecs::Entity::Identifier getItemIdentifier (std::size_t index) const
 Get the root entity of a top-level entry: the row container, the subheader text or the divider.
ecs::Entity::Identifier getChildIdentifier (std::size_t index, std::size_t childIndex) const
 Get the root entity of a row nested in an accordion.
ecs::Entity::Identifier getContentIdentifier (std::size_t index) const
 Get the content column of a top-level row: the container of its headline and supporting text.
List & setItemDisabled (std::size_t index, bool disabled)
 Enable or disable a top-level entry. Restyles at once.
List & setExpanded (std::size_t index, bool expanded)
 Expand or collapse a top-level accordion.
bool isExpanded (std::size_t index) const
 Whether a top-level accordion shows its nested rows.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::List >
 ~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

static Item subheader (const std::string &title)
 Make a subheader entry: a section title that is not pressable.
static Item divider (void)
 Make a divider entry: a horizontal line as wide as the list.
template<typename... Arguments>
static std::shared_ptr< List > create (Arguments &&...arguments)
 Create a list and its rows, 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.

Additional Inherited Members

Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity
Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::List >
 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

A vertical list of pressable rows, with optional subheaders, dividers and accordions that fold nested rows (Paper List.Section, List.Subheader, List.Item, List.Accordion, List.Icon and List.Image).

Its state lives in components::List (variant, entries, identifiers of the rows built for them); systems::List styles the list, sizes and stacks the rows and shows the children of expanded accordions only, each frame, in the Layout phase. The class itself holds no field: it builds the row entities, and its setters write the component and restyle at once.

List::Item inbox;
inbox.headline = "Inbox";
inbox.supporting = "3 unread messages";
inbox.leadingIcon = "inbox";
inbox.onPress = [] {
// called when the user presses the row
};
List::Builder builder(getComponentRegistry(), getEntityRegistry());
auto list = builder.makeList(parent, List::Variant::TwoLine,
{ List::subheader("Mail"), inbox, List::divider() });
Configures a List, creates it and registers it in an entity registry.
Definition list.hpp:113
static Item divider(void)
Make a divider entry: a horizontal line as wide as the list.
Definition list.cpp:283
static Item subheader(const std::string &title)
Make a subheader entry: a section title that is not pressable.
Definition list.cpp:275
components::List::Item Item
List entry.
Definition list.hpp:106
std::function< void(void)> onPress
Called on press.
Definition list.hpp:94
std::string headline
Main text of the row.
Definition list.hpp:85

List::create(registry, config, variant, items) builds the same widget without registering it in an entity registry.

Things to know:

  • A row is an entities::View holding an optional leading image or icon, a column with the headline over the supporting text, and an optional trailing icon. An entry with children is an accordion: its trailing icon is a chevron and a press toggles it before calling its press handler.
  • The variant only decides whether the supporting text shows: SingleLine hides it, TwoLine and ThreeLine show it.
  • Indexes are positions among the top-level entries, from 0; subheaders and dividers count.
  • The width is the fixed width of the surface configuration, in dp (components::List::DefaultWidth, 360 dp, with the Builder defaults); the row heights follow their content. The list's layout, color and corners are overwritten each frame.
  • The list is the entity registry that owns its rows. setItems() removes every row and builds new ones: identifiers returned before by getItemIdentifier(), getChildIdentifier() and getContentIdentifier() are then invalid.
  • setExpanded() does not call the press handler of the entry.
See also
components::List, systems::List, View

Definition at line 101 of file list.hpp.

Member Typedef Documentation

◆ Item

List entry.

Definition at line 106 of file list.hpp.

◆ ItemKind

Kind of an entry.

Definition at line 105 of file list.hpp.

◆ Variant

List variant.

Definition at line 104 of file list.hpp.

Constructor & Destructor Documentation

◆ ~List()

guillaume::entities::List::~List ( void )
override

Default destructor.

Definition at line 301 of file list.cpp.

Member Function Documentation

◆ create()

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

Create a list and its rows, without registering it in an entity registry.

The constructor is private because the rows need the list to be owned by a shared pointer before they can take it as parent; create() constructs the list, then builds one row per entry.

Template Parameters
ArgumentsThe types of the constructor arguments.
Parameters
argumentsForwarded to the private constructor: (registry, config, variant, items).
Returns
The new list.

Definition at line 221 of file list.hpp.

Here is the caller graph for this function:

◆ divider()

List::Item guillaume::entities::List::divider ( void )
static

Make a divider entry: a horizontal line as wide as the list.

Returns
An entry of kind ItemKind::Divider, to put in the vector given to the Builder or to setItems().

Definition at line 283 of file list.cpp.

◆ getChildIdentifier()

ecs::Entity::Identifier guillaume::entities::List::getChildIdentifier ( std::size_t index,
std::size_t childIndex ) const

Get the root entity of a row nested in an accordion.

The row exists whether the accordion is expanded or not.

Parameters
indexThe index of the top-level accordion entry.
childIndexThe position of the row among the children of that entry, from 0.
Returns
The identifier of the entity, or ecs::Entity::InvalidIdentifier when either index is out of range.

Definition at line 350 of file list.cpp.

Here is the call graph for this function:

◆ getContentIdentifier()

ecs::Entity::Identifier guillaume::entities::List::getContentIdentifier ( std::size_t index) const

Get the content column of a top-level row: the container of its headline and supporting text.

Parameters
indexThe index of the top-level entry.
Returns
The identifier of the column, or ecs::Entity::InvalidIdentifier when index is out of range or the entry is a subheader or a divider.

Definition at line 360 of file list.cpp.

Here is the call graph for this function:

◆ getItemCount()

std::size_t guillaume::entities::List::getItemCount ( void ) const

Get the number of top-level entries.

Returns
How many entries the list has, subheaders and dividers included, accordion children excluded.

Definition at line 332 of file list.cpp.

Here is the call graph for this function:

◆ getItemIdentifier()

ecs::Entity::Identifier guillaume::entities::List::getItemIdentifier ( std::size_t index) const

Get the root entity of a top-level entry: the row container, the subheader text or the divider.

Parameters
indexThe index of the top-level entry.
Returns
The identifier of the entity, or ecs::Entity::InvalidIdentifier when index is out of range or the entry is a subheader without text.

Definition at line 340 of file list.cpp.

Here is the call graph for this function:

◆ getVariant()

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

Get the variant.

Returns
The variant stored in components::List.

Definition at line 314 of file list.cpp.

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

◆ isExpanded()

bool guillaume::entities::List::isExpanded ( std::size_t index) const

Whether a top-level accordion shows its nested rows.

Parameters
indexThe index of the top-level entry.
Returns
True when the entry exists and is expanded; false when index is out of range.

Definition at line 383 of file list.cpp.

Here is the call graph for this function:

◆ setExpanded()

List & guillaume::entities::List::setExpanded ( std::size_t index,
bool expanded )

Expand or collapse a top-level accordion.

Shows or hides its nested rows and arranges the list again at once. Does not call the press handler of the entry.

Parameters
indexThe index of the top-level entry; nothing happens when it is out of range or when the entry has no children.
expandedTrue to show the nested rows.
Returns
This list, for chaining.

Definition at line 376 of file list.cpp.

Here is the call graph for this function:

◆ setItemDisabled()

List & guillaume::entities::List::setItemDisabled ( std::size_t index,
bool disabled )

Enable or disable a top-level entry. Restyles at once.

A disabled row ignores presses.

Parameters
indexThe index of the top-level entry; nothing happens when it is out of range.
disabledTrue to disable, false to enable.
Returns
This list, for chaining.

Definition at line 369 of file list.cpp.

Here is the call graph for this function:

◆ setItems()

List & guillaume::entities::List::setItems ( const std::vector< Item > & items)

Replace the entries.

Removes every row entity of the list and builds new ones, then restyles at once. Row identifiers obtained before the call are invalid afterwards, even for entries that did not change.

Parameters
itemsThe new entries, in display order.
Returns
This list, for chaining.

Definition at line 321 of file list.cpp.

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

◆ setVariant()

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

Change the variant. Restyles at once; the rows are kept.

Parameters
variantSingleLine hides the supporting text of the rows; TwoLine and ThreeLine show it.
Returns
This list, for chaining.

Definition at line 305 of file list.cpp.

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

◆ subheader()

List::Item guillaume::entities::List::subheader ( const std::string & title)
static

Make a subheader entry: a section title that is not pressable.

Parameters
titleThe text of the subheader. An empty text builds no row.
Returns
An entry of kind ItemKind::Subheader, to put in the vector given to the Builder or to setItems().

Definition at line 275 of file list.cpp.


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