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

State of a list: a column of rows, each with a headline and optional supporting text, icons or image, plus subheaders, dividers and accordions. More...

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

Inheritance diagram for guillaume::components::List:
Collaboration diagram for guillaume::components::List:

Classes

struct  Item
 Description of one list entry, as given by the user. More...
struct  Row
 Identifiers of the entities built for one entry. More...

Public Types

enum class  Variant { SingleLine , TwoLine , ThreeLine }
 Number of text lines a row is meant for. More...
enum class  ItemKind { Item , Subheader , Divider }
 What a list entry is. More...
using Path = std::vector<std::size_t>

Public Member Functions

 List (void)=default
 Create the configuration of an empty single-line list.
 ~List (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get the number of text lines a row is meant for.
List & setVariant (Variant variant)
 Set the number of text lines a row is meant for.
const std::vector< Item > & getItems (void) const noexcept
 Get the description of every top-level entry.
List & setItems (std::vector< Item > items)
 Replace the entries.
const Item * findItem (const Path &path) const noexcept
 Find an entry from its position in the tree.
const Row * findRow (const Path &path) const noexcept
 Find the entities built for an entry from its position in the tree.
List & setItemDisabled (std::size_t index, bool disabled)
 Change the disabled flag recorded for one top-level entry.
List & setItemExpanded (std::size_t index, bool expanded)
 Record whether one top-level accordion shows its children.
const std::vector< Row > & getRows (void) const noexcept
 Get the entities built for the entries.
List & setRows (const std::vector< Row > &rows)
 Record the entities built for the entries.
bool isRowsDirty (void) const noexcept
 Tell whether the rows must be rebuilt from the entries.
List & setRowsDirty (bool dirty)
 Mark the rows as out of date or as up to date.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Static Public Attributes

static constexpr float DefaultWidth = 360.0f
 Default width of a list, in dp.
static constexpr float IconSize = 24.0f
 Size of the leading and trailing icons, in dp.
static constexpr const char * CollapsedGlyph = "expand_more"
 Glyph name of the trailing icon of a collapsed accordion.
static constexpr const char * ExpandedGlyph = "expand_less"
 Glyph name of the trailing icon of an expanded accordion.

Detailed Description

State of a list: a column of rows, each with a headline and optional supporting text, icons or image, plus subheaders, dividers and accordions.

The entities::List widget writes it: the entries, and one Row of entity identifiers per entry it builds. systems::List reads it every frame in the Layout phase and turns it into the list's Layout, Color and Borders, and into the Layout, Color, enabled state and accessibility state of every row and of its content.

Entries and rows are two trees that must stay in step: the Row at a given Path holds the entities built for the Item at the same Path. Replacing the entries does not rebuild the rows; the widget raises the rows-dirty flag and rebuilds them.

An entry with children is an accordion: pressing it shows or hides its children. Only top-level entries can be accordions.

See also
systems::List, entities::List

Definition at line 57 of file list.hpp.

Member Typedef Documentation

◆ Path

using guillaume::components::List::Path = std::vector<std::size_t>

Position of an entry in the tree: the top-level index, then one child index per nesting level. {2} is the third entry; {2, 0} is its first child.

Definition at line 159 of file list.hpp.

Member Enumeration Documentation

◆ ItemKind

What a list entry is.

Enumerator
Item 

Pressable row (or accordion when it has children).

Subheader 

Section header (titleSmall text).

Divider 

Horizontal divider line.

Definition at line 71 of file list.hpp.

◆ Variant

Number of text lines a row is meant for.

SingleLine hides the supporting text; TwoLine and ThreeLine both show it.

Definition at line 66 of file list.hpp.

Member Function Documentation

◆ findItem()

const List::Item * guillaume::components::List::findItem ( const Path & path) const
noexcept

Find an entry from its position in the tree.

Parameters
pathThe index path of the entry.
Returns
The entry, or nullptr when the path is empty or names no entry. The pointer is valid until the entries are replaced.

Definition at line 94 of file list.cpp.

Here is the caller graph for this function:

◆ findRow()

const List::Row * guillaume::components::List::findRow ( const Path & path) const
noexcept

Find the entities built for an entry from its position in the tree.

Parameters
pathThe index path of the entry.
Returns
The row, or nullptr when the path is empty or names no built row. The pointer is valid until the rows are replaced.

Definition at line 110 of file list.cpp.

Here is the caller graph for this function:

◆ getItems()

const std::vector< List::Item > & guillaume::components::List::getItems ( void ) const
noexcept

Get the description of every top-level entry.

Returns
The entries, from top to bottom; accordion children are in Item::children.

Definition at line 77 of file list.cpp.

◆ getRows()

const std::vector< List::Row > & guillaume::components::List::getRows ( void ) const
noexcept

Get the entities built for the entries.

Returns
One row per built top-level entry, in entry order. Empty until the widget has built them.

Definition at line 145 of file list.cpp.

Here is the caller graph for this function:

◆ getVariant()

List::Variant guillaume::components::List::getVariant ( void ) const
noexcept

Get the number of text lines a row is meant for.

Returns
The variant, Variant::SingleLine by default.

Definition at line 63 of file list.cpp.

Here is the caller graph for this function:

◆ isRowsDirty()

bool guillaume::components::List::isRowsDirty ( void ) const
noexcept

Tell whether the rows must be rebuilt from the entries.

Returns
True when the entries changed since the rows were built. True for a new component.

Definition at line 159 of file list.cpp.

◆ setItemDisabled()

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

Change the disabled flag recorded for one top-level entry.

To update the row on screen too, call systems::List::setItemDisabled. Marks the component changed only when the flag differs.

Parameters
indexThe top-level entry index, starting at 0. An index out of range is ignored.
disabledTrue to disable the entry.
Returns
This component, for chaining.

Definition at line 126 of file list.cpp.

Here is the call graph for this function:

◆ setItemExpanded()

List & guillaume::components::List::setItemExpanded ( std::size_t index,
bool expanded )

Record whether one top-level accordion shows its children.

To update the rows on screen too, call systems::List::setExpanded. Marks the component changed only when the flag differs.

Parameters
indexThe top-level entry index, starting at 0. An index out of range, or an entry without children, is ignored.
expandedTrue to show the children.
Returns
This component, for chaining.

Definition at line 135 of file list.cpp.

Here is the call graph for this function:

◆ setItems()

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

Replace the entries.

The press handlers are always replaced. The component is marked changed only when the texts, icons, kinds or flags differ (children included), because handlers cannot be compared. The rows are left as they are: whoever owns the row entities rebuilds them.

Parameters
itemsThe new entries, from top to bottom.
Returns
This component, for chaining.

Definition at line 82 of file list.cpp.

Here is the call graph for this function:

◆ setRows()

List & guillaume::components::List::setRows ( const std::vector< Row > & rows)

Record the entities built for the entries.

Marks the component changed only when the rows differ.

Parameters
rowsOne row per top-level entry, in entry order.
Returns
This component, for chaining.

Definition at line 150 of file list.cpp.

Here is the call graph for this function:

◆ setRowsDirty()

List & guillaume::components::List::setRowsDirty ( bool dirty)

Mark the rows as out of date or as up to date.

The widget raises the flag when it replaces the entries and lowers it once it has rebuilt the row entities. Marks the component changed only when the flag differs.

Parameters
dirtyTrue when the rows must be rebuilt.
Returns
This component, for chaining.

Definition at line 164 of file list.cpp.

Here is the call graph for this function:

◆ setVariant()

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

Set the number of text lines a row is meant for.

Marks the component changed only when the variant differs.

Parameters
variantThe new variant.
Returns
This component, for chaining.

Definition at line 68 of file list.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ CollapsedGlyph

const char* guillaume::components::List::CollapsedGlyph = "expand_more"
staticconstexpr

Glyph name of the trailing icon of a collapsed accordion.

Definition at line 168 of file list.hpp.

◆ DefaultWidth

float guillaume::components::List::DefaultWidth = 360.0f
staticconstexpr

Default width of a list, in dp.

Definition at line 162 of file list.hpp.

◆ ExpandedGlyph

const char* guillaume::components::List::ExpandedGlyph = "expand_less"
staticconstexpr

Glyph name of the trailing icon of an expanded accordion.

Definition at line 171 of file list.hpp.

◆ IconSize

float guillaume::components::List::IconSize = 24.0f
staticconstexpr

Size of the leading and trailing icons, in dp.

Definition at line 165 of file list.hpp.


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