guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
list.cpp
1/*
2 Copyright (c) 2026 ETIB Corporation
3
4 Permission is hereby granted, free of charge, to any person obtaining a copy of
5 this software and associated documentation files (the "Software"), to deal in
6 the Software without restriction, including without limitation the rights to
7 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
8 of the Software, and to permit persons to whom the Software is furnished to do
9 so, subject to the following conditions:
10
11 The above copyright notice and this permission notice shall be included in all
12 copies or substantial portions of the Software.
13
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20 SOFTWARE.
21 */
22
23#include "guillaume/systems/list.hpp"
24
25#include <vector>
26
27#include "guillaume/components/accessibility.hpp"
28#include "guillaume/components/borders.hpp"
29#include "guillaume/components/bound.hpp"
30#include "guillaume/components/color.hpp"
31#include "guillaume/components/glyph.hpp"
32#include "guillaume/components/layout.hpp"
33#include "guillaume/components/transform.hpp"
36#include "guillaume/systems/layout.hpp"
37#include "guillaume/theme.hpp"
38
39namespace guillaume::systems
40{
41 namespace
42 {
43 using Item = components::List::Item;
44 using Row = components::List::Row;
45 using Variant = components::List::Variant;
46 using Ids = std::vector<ecs::Entity::Identifier>;
50
52 constexpr float RowPadding = theme::SpacingScale::get(4);
53
55 constexpr float RowSpacing = theme::SpacingScale::get(4);
56
59 constexpr float AccordionInset = 40.0f;
60
67 void pushValid(Ids &children, ecs::Entity::Identifier identifier)
68 {
69 if (identifier != ecs::Entity::InvalidIdentifier) {
70 children.push_back(identifier);
71 }
72 }
73
80 void colorChild(ecs::ComponentRegistry &registry,
82 const utility::graphic::Color32Bit &color)
83 {
85 && registry.hasComponent<components::Color>(child)) {
86 registry.getComponent<components::Color>(child).setColor(color);
87 }
88 }
89
96 bool isContainer(const ecs::ComponentRegistry &registry,
97 ecs::Entity::Identifier identifier)
98 {
99 return identifier != ecs::Entity::InvalidIdentifier
100 && registry.hasComponent<components::Layout>(identifier)
101 && registry.hasComponent<components::Transform>(identifier)
102 && registry.hasComponent<components::Bound>(identifier);
103 }
104
110 void arrange(ecs::ComponentRegistry &registry,
111 ecs::Entity::Identifier identifier)
112 {
113 if (!isContainer(registry, identifier)) {
114 return;
115 }
116 Layout::apply(registry, identifier,
117 registry.getComponent<components::Layout>(identifier)
118 .getChildren(),
119 Layout::layerOf(registry, identifier));
120 }
121
130 void configureGroup(ecs::ComponentRegistry &registry,
131 ecs::Entity::Identifier identifier,
132 components::Layout::Axis axis, float spacing,
133 const Ids &children)
134 {
135 if (!isContainer(registry, identifier)) {
136 return;
137 }
138 registry.getComponent<components::Layout>(identifier)
139 .setAxis(axis)
140 .setMainAxisAlignment(
142 .setCrossAxisAlignment(
146 .setPadding(0.0f)
147 .setSpacing(spacing)
148 .setChildren(children);
149 }
150
160 bool isHidden(const components::List &list,
161 const components::List::Path &path)
162 {
163 if (path.size() <= 1) {
164 return false;
165 }
166 return path.size() > 2 || path[0] >= list.getItems().size()
167 || !list.getItems()[path[0]].expanded;
168 }
169
177 void paintRow(ecs::ComponentRegistry &registry, const Row &row,
178 bool hidden, bool showSupporting)
179 {
180 if (row.view == ecs::Entity::InvalidIdentifier) {
181 return;
182 }
183
184 const bool enabled = interaction::isEnabled(registry, row.view);
185 auto headlineColor = enabled
186 ? schemeColor(SchemeColorRole::OnSurface)
188 auto supportingColor = enabled
189 ? schemeColor(SchemeColorRole::OnSurfaceVariant)
191 auto iconColor = supportingColor;
192 auto rowColor = interaction::stateLayerColor(
193 registry, row.view, transparentColor(),
194 schemeColor(SchemeColorRole::OnSurface));
195
196 if (hidden) {
197 headlineColor = transparentColor();
198 supportingColor = transparentColor();
199 iconColor = transparentColor();
200 rowColor = transparentColor();
201 }
202 if (!showSupporting) {
203 supportingColor = transparentColor();
204 }
205
206 colorChild(registry, row.view, rowColor);
207 colorChild(registry, row.headline, headlineColor);
208 colorChild(registry, row.supporting, supportingColor);
209 colorChild(registry, row.leadingIcon, iconColor);
210 colorChild(registry, row.trailingIcon, iconColor);
211 }
212
224 void configureRow(ecs::ComponentRegistry &registry, const Row &row,
225 const Item *item, float width, std::size_t depth,
226 bool hidden, bool showSupporting)
227 {
228 const bool accordion = item != nullptr && !item->children.empty();
229
230 if (isContainer(registry, row.view)) {
231 Ids rowChildren;
232 pushValid(rowChildren, row.lead);
233 pushValid(rowChildren, row.trailingIcon);
234
235 Ids leadChildren;
236 pushValid(leadChildren, row.spacer);
237 pushValid(leadChildren, row.leadingImage);
238 pushValid(leadChildren, row.leadingIcon);
239 pushValid(leadChildren, row.content);
240
241 Ids contentChildren;
242 pushValid(contentChildren, row.headline);
243 if (showSupporting) {
244 pushValid(contentChildren, row.supporting);
245 }
246
247 registry.getComponent<components::Layout>(row.view)
249 .setMainAxisAlignment(
250 row.trailingIcon != ecs::Entity::InvalidIdentifier
252 SpaceBetween
254 .setCrossAxisAlignment(
256 .setPadding(RowPadding)
257 .setSpacing(RowSpacing)
258 .setFixedWidth(width)
259 .setChildren(rowChildren);
260 configureGroup(registry, row.lead,
262 leadChildren);
263 configureGroup(registry, row.content,
265 contentChildren);
266 if (isContainer(registry, row.spacer)) {
267 registry.getComponent<components::Layout>(row.spacer)
268 .setFixedWidth(static_cast<float>(depth)
269 * AccordionInset)
270 .setFixedHeight(1.0f);
271 }
272 }
273
274 if (row.view != ecs::Entity::InvalidIdentifier && item != nullptr) {
275 if (registry.hasComponent<components::Accessibility>(
276 row.view)) {
277 auto &accessibility =
278 registry.getComponent<components::Accessibility>(
279 row.view);
280 accessibility.setLabel(item->headline)
281 .setHint(item->supporting);
282 if (accordion) {
283 accessibility.setExpanded(item->expanded);
284 }
285 }
286 interaction::setEnabled(registry, row.view,
287 !hidden && !item->disabled);
288 if (accordion
289 && row.trailingIcon != ecs::Entity::InvalidIdentifier
290 && registry.hasComponent<components::Glyph>(
291 row.trailingIcon)) {
292 registry.getComponent<components::Glyph>(row.trailingIcon)
293 .setName(item->expanded
296 }
297 }
298
299 paintRow(registry, row, hidden, showSupporting);
300
301 // Only the children of an expanded top-level accordion show.
302 const bool childrenHidden =
303 hidden || depth > 0 || item == nullptr || !item->expanded;
304 for (std::size_t index = 0; index < row.children.size(); ++index) {
305 const Item *child =
306 item != nullptr && index < item->children.size()
307 ? &item->children[index]
308 : nullptr;
309 configureRow(registry, row.children[index], child, width,
310 depth + 1, childrenHidden, showSupporting);
311 }
312 }
313
319 void measureRow(ecs::ComponentRegistry &registry, const Row &row)
320 {
321 arrange(registry, row.spacer);
322 arrange(registry, row.content);
323 arrange(registry, row.lead);
324 arrange(registry, row.view);
325 }
326
333 void placeRow(ecs::ComponentRegistry &registry, const Row &row)
334 {
335 arrange(registry, row.view);
336 arrange(registry, row.lead);
337 arrange(registry, row.content);
338 }
339
347 void installRows(ecs::ComponentRegistry &registry,
348 const ecs::Entity::Identifier &identifier,
349 const Row &row, const components::List::Path &path)
350 {
351 List::installRow(registry, identifier, path);
352 for (std::size_t index = 0; index < row.children.size(); ++index) {
353 auto childPath = path;
354 childPath.push_back(index);
355 installRows(registry, identifier, row.children[index],
356 childPath);
357 }
358 }
359 } // namespace
360
363 {
364 }
365
366 void List::install(ecs::ComponentRegistry &componentRegistry,
367 const ecs::Entity::Identifier &entityIdentifier)
368 {
369 // Copy: installing a row adds components, never rows, but the
370 // component storage may move while it grows.
371 const auto rows =
372 componentRegistry.getComponent<components::List>(entityIdentifier)
373 .getRows();
374
375 for (std::size_t index = 0; index < rows.size(); ++index) {
376 installRows(componentRegistry, entityIdentifier, rows[index],
377 { index });
378 }
379 }
380
382 const ecs::Entity::Identifier &entityIdentifier,
383 const Path &path)
384 {
385 ecs::ComponentRegistry *registry = &componentRegistry;
386 const ecs::Entity::Identifier identifier = entityIdentifier;
387 const auto *row =
388 componentRegistry.getComponent<components::List>(identifier)
389 .findRow(path);
390
391 if (row == nullptr || row->view == ecs::Entity::InvalidIdentifier) {
392 return;
393 }
394
396 componentRegistry, row->view,
398 [registry, identifier, path]() {
399 pressItem(*registry, identifier, path);
400 },
401 [registry, identifier, path]() {
402 styleRow(*registry, identifier, path);
403 });
404 }
405
406 void List::styleRow(ecs::ComponentRegistry &componentRegistry,
407 const ecs::Entity::Identifier &entityIdentifier,
408 const Path &path)
409 {
410 const auto &list =
411 componentRegistry.getComponent<components::List>(entityIdentifier);
412 const auto *row = list.findRow(path);
413
414 if (row == nullptr) {
415 return;
416 }
417 paintRow(componentRegistry, *row, isHidden(list, path),
418 list.getVariant() != Variant::SingleLine);
419 }
420
422 const ecs::Entity::Identifier &entityIdentifier,
423 const Path &path)
424 {
425 const auto &list =
426 componentRegistry.getComponent<components::List>(entityIdentifier);
427 const auto *item = list.findItem(path);
428
429 if (item == nullptr || item->disabled || isHidden(list, path)) {
430 return;
431 }
432
433 // Copy: the handler may replace the entries.
434 const auto onPress = item->onPress;
435
436 if (!item->children.empty() && path.size() == 1) {
437 setExpanded(componentRegistry, entityIdentifier, path[0],
438 !item->expanded);
439 }
440 if (onPress) {
441 onPress();
442 }
443 }
444
446 const ecs::Entity::Identifier &entityIdentifier,
447 std::size_t index, bool disabled)
448 {
449 componentRegistry.getComponent<components::List>(entityIdentifier)
450 .setItemDisabled(index, disabled);
451 apply(componentRegistry, entityIdentifier);
452 }
453
455 const ecs::Entity::Identifier &entityIdentifier,
456 std::size_t index, bool expanded)
457 {
458 componentRegistry.getComponent<components::List>(entityIdentifier)
459 .setItemExpanded(index, expanded);
460 apply(componentRegistry, entityIdentifier);
461 }
462
463 bool List::isExpanded(const ecs::ComponentRegistry &componentRegistry,
464 const ecs::Entity::Identifier &entityIdentifier,
465 std::size_t index)
466 {
467 const auto &items =
468 componentRegistry.getComponent<components::List>(entityIdentifier)
469 .getItems();
470
471 return index < items.size() && items[index].expanded;
472 }
473
474 void List::apply(ecs::ComponentRegistry &componentRegistry,
475 const ecs::Entity::Identifier &entityIdentifier)
476 {
477 const auto &list =
478 componentRegistry.getComponent<components::List>(entityIdentifier);
479 const auto &rows = list.getRows();
480 const auto &items = list.getItems();
481 const bool showSupporting = list.getVariant() != Variant::SingleLine;
482
483 auto &layout = componentRegistry.getComponent<components::Layout>(
484 entityIdentifier);
489 .setPadding(0.0f)
490 .setSpacing(0.0f);
491 if (!layout.hasFixedWidth()) {
492 layout.setFixedWidth(components::List::DefaultWidth);
493 }
494 const float width = layout.getFixedWidth();
495
496 componentRegistry.getComponent<components::Borders>(entityIdentifier)
497 .setBorderRadius(getShapeRadius(theme::ShapeRole::None));
498 componentRegistry.getComponent<components::Color>(entityIdentifier)
499 .setColor(schemeColor(SchemeColorRole::Surface));
500
501 // The rows shown: every top-level row, each followed by its
502 // children while it is an expanded accordion.
503 std::vector<const Row *> shown;
504 Ids children;
505
506 for (std::size_t index = 0; index < rows.size(); ++index) {
507 const auto &row = rows[index];
508 const Item *item = index < items.size() ? &items[index] : nullptr;
509
510 configureRow(componentRegistry, row, item, width, 0, false,
511 showSupporting);
512
513 if (row.entity != ecs::Entity::InvalidIdentifier) {
514 shown.push_back(&row);
515 children.push_back(row.entity);
516 }
517 if (item == nullptr || !item->expanded) {
518 continue;
519 }
520 for (const auto &child: row.children) {
521 if (child.entity != ecs::Entity::InvalidIdentifier) {
522 shown.push_back(&child);
523 children.push_back(child.entity);
524 }
525 }
526 }
527
528 layout.setChildren(children);
529
530 // The rows are sized first, so the list can stack them; their
531 // content is then placed at the pose the list gave them.
532 for (const auto *row: shown) {
533 measureRow(componentRegistry, *row);
534 }
535 Layout::apply(componentRegistry, entityIdentifier, children,
536 Layout::layerOf(componentRegistry, entityIdentifier));
537 for (const auto *row: shown) {
538 placeRow(componentRegistry, *row);
539 }
540 }
541
542 void List::update(const ecs::Entity::Identifier &entityIdentifier)
543 {
544 if (!requireComponent<components::List>(entityIdentifier)) {
545 return;
546 }
547
548 apply(getComponentRegistry(), entityIdentifier);
549 }
550} // namespace guillaume::systems
Corner radii and outline stroke of a rectangular entity.
Definition borders.hpp:67
Main color of an entity: the fill of a shape, or the ink of a text or an icon.
Definition color.hpp:58
How a container arranges its children: in a row or a column, with which alignment,...
Definition layout.hpp:69
Layout & setAxis(Axis axis)
Choose between a row and a column.
Definition layout.cpp:32
Layout & setPadding(float padding)
Set the inset between the container's edges and its children.
Definition layout.cpp:92
Layout & setMainAxisAlignment(MainAxisAlignment alignment)
Set where the children go along the main axis.
Definition layout.cpp:47
float getFixedWidth(void) const
Get the forced container width.
Definition layout.cpp:107
@ Start
At the top (row) or left (column).
Definition layout.hpp:100
Layout & setCrossAxisAlignment(CrossAxisAlignment alignment)
Set where each child goes along the cross axis.
Definition layout.cpp:62
MainAxisAlignment
Where the children go along the main axis when the container is larger than them.
Definition layout.hpp:86
@ Start
Packed at the left (row) or top (column).
Definition layout.hpp:87
Axis
Direction along which children are arranged.
Definition layout.hpp:74
@ Vertical
Column: children placed top to bottom.
Definition layout.hpp:76
@ Horizontal
Row: children placed left to right.
Definition layout.hpp:75
Layout & setSpacing(float spacing)
Set the gap between two consecutive children.
Definition layout.cpp:77
State of a list: a column of rows, each with a headline and optional supporting text,...
Definition list.hpp:58
const Item * findItem(const Path &path) const noexcept
Find an entry from its position in the tree.
Definition list.cpp:94
static constexpr float DefaultWidth
Default width of a list, in dp.
Definition list.hpp:162
Variant getVariant(void) const noexcept
Get the number of text lines a row is meant for.
Definition list.cpp:63
static constexpr const char * CollapsedGlyph
Glyph name of the trailing icon of a collapsed accordion.
Definition list.hpp:168
Variant
Number of text lines a row is meant for.
Definition list.hpp:66
static constexpr const char * ExpandedGlyph
Glyph name of the trailing icon of an expanded accordion.
Definition list.hpp:171
const std::vector< Row > & getRows(void) const noexcept
Get the entities built for the entries.
Definition list.cpp:145
std::vector< std::size_t > Path
Definition list.hpp:159
const Row * findRow(const Path &path) const noexcept
Find the entities built for an entry from its position in the tree.
Definition list.cpp:110
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
ComponentType & getComponent(const Entity::Identifier &entityIdentifier)
Get a component of an entity, to read or modify it.
std::size_t Identifier
The key under which an entity's components are stored. Systems and components refer to entities by th...
Definition entity.hpp:86
static constexpr Identifier InvalidIdentifier
"No entity": never the identifier of a real entity
Definition entity.hpp:93
ecs::ComponentRegistry & getComponentRegistry(void)
Get the component registry of the scene being processed.
Definition system.cpp:53
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...
Arranges the children of a container in a row or a column and sizes the container around them.
Definition layout.hpp:84
static void apply(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, std::uint32_t layer=0)
Arrange children inside a container and size the container.
Definition layout.cpp:126
static std::uint32_t layerOf(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Get the layer of an entity: its depth in the entity tree.
Definition layout.cpp:90
components::List::Path Path
Index path of an entry: top-level index, then child indices.
Definition list.hpp:71
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.
Definition list.cpp:445
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
void update(const ecs::Entity::Identifier &entityIdentifier) override
Run apply() on one list; called by the frame loop.
Definition list.cpp:542
static bool isExpanded(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, std::size_t index)
Whether a top-level entry is expanded.
Definition list.cpp:463
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Make every row of a list pressable.
Definition list.cpp:366
List(void)
Create the system in the Layout phase.
Definition list.cpp:361
static void installRow(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, const Path &path)
Make one row pressable.
Definition list.cpp:381
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
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Style one list, then size and place its rows.
Definition list.cpp:474
static void styleRow(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, const Path &path)
Recolor one row without arranging the list again.
Definition list.cpp:406
static constexpr float get(unsigned int steps)
Get a spacing as a number of grid units.
Definition tokens.hpp:441
State. Every class here is plain data attached to an entity.
The entity-component-system core, independent of any widget.
Definition component.hpp:28
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit disabledContentColor(void)
Color of the icon, label or outline of a disabled widget.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
Rules. Every class here runs each frame on the entities that have the components it declares.
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit disabledContentColor(void)
Color of the icon, label or outline of a disabled widget.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
@ None
0 dp: square corners.
Definition tokens.hpp:43
float getShapeRadius(theme::ShapeRole role)
Get the corner radius the active theme gives to a shape role.
Helpers of the namespace systems::interaction: what "pressable" means for a widget,...
bool isEnabled(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier)
Whether an entity accepts input.
void makeInteractive(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, components::AccessibilityRole role, std::function< void(void)> onPress, std::function< void(void)> onStateChange={})
Make an entity hoverable, pressable and focusable.
void setEnabled(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, bool enabled)
Enable or disable an entity.
utility::graphic::Color32Bit stateLayerColor(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, const utility::graphic::Color32Bit &base, const utility::graphic::Color32Bit &content)
Container color of a widget in its current input state.
Color helpers shared by the widget systems: scheme lookup, state layers and the disabled colors.