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 <memory>
24#include <string>
25#include <utility>
26#include <vector>
27
28#include "guillaume/entities/list.hpp"
29
30#include "guillaume/components/accessibility.hpp"
31#include "guillaume/components/layout.hpp"
32#include "guillaume/entities/builder_base.hpp"
33#include "guillaume/entities/content_helpers.hpp"
34#include "guillaume/entities/divider.hpp"
35#include "guillaume/entities/image.hpp"
37#include "guillaume/systems/list.hpp"
38#include "guillaume/theme.hpp"
39
40namespace guillaume::entities
41{
42 namespace
43 {
44 using Row = components::List::Row;
45 using Children = std::vector<std::shared_ptr<ecs::Entity>>;
46
57 std::shared_ptr<View> makeView(ecs::ComponentRegistry &registry,
58 ecs::EntityRegistry &entityRegistry,
59 std::shared_ptr<ecs::Entity> parent)
60 {
61 View::Builder builder(registry, entityRegistry);
62 auto view =
63 builder.makeDefaultView(parent, utility::graphic::PoseF(), {});
64 view->setColor(transparentColor());
65 view->setPadding(0.0f);
66 view->setSpacing(0.0f);
67 return view;
68 }
69
77 std::shared_ptr<ecs::Entity>
78 buildSubheader(ecs::ComponentRegistry &registry,
79 const std::shared_ptr<List> &list,
80 const List::Item &item)
81 {
82 auto header =
83 buildText(registry, *list, list, item.headline,
85 schemeColor(SchemeColorRole::OnSurfaceVariant));
86 if (header != nullptr) {
87 registry.addComponent<components::Accessibility>(
88 header->getIdentifier());
89 registry
90 .getComponent<components::Accessibility>(
91 header->getIdentifier())
93 .setLabel(item.headline)
94 .setFocusable(false);
95 }
96 return header;
97 }
98
108 void buildRowLead(ecs::ComponentRegistry &registry,
109 const std::shared_ptr<View> &view, Row &row,
110 const List::Item &item, bool nested)
111 {
112 const auto lead = makeView(registry, *view, view);
113 row.lead = lead->getIdentifier();
114
115 if (nested) {
116 row.spacer = makeView(registry, *lead, lead)->getIdentifier();
117 }
118
119 if (!item.leadingImage.empty()) {
120 Image::Builder builder(registry, *lead);
121 if (const auto image =
122 builder.makeImage(lead, item.leadingImage)) {
123 row.leadingImage = image->getIdentifier();
124 }
125 } else if (const auto icon = buildIcon(
126 registry, *lead, lead, item.leadingIcon,
128 schemeColor(SchemeColorRole::OnSurfaceVariant))) {
129 row.leadingIcon = icon->getIdentifier();
130 }
131
132 const auto content = makeView(registry, *lead, lead);
133 row.content = content->getIdentifier();
134
135 if (const auto headline =
136 buildText(registry, *content, content, item.headline,
138 schemeColor(SchemeColorRole::OnSurface))) {
139 row.headline = headline->getIdentifier();
140 }
141 // Built whatever the variant: systems::List decides whether the
142 // description shows.
143 if (const auto supporting =
144 buildText(registry, *content, content, item.supporting,
146 schemeColor(SchemeColorRole::OnSurfaceVariant))) {
147 row.supporting = supporting->getIdentifier();
148 }
149 }
150
161 Row buildRow(ecs::ComponentRegistry &registry,
162 const std::shared_ptr<List> &list, const List::Item &item,
163 float width, bool nested, Children &roots)
164 {
165 Row row;
166
167 if (item.kind == List::ItemKind::Subheader) {
168 if (const auto header = buildSubheader(registry, list, item)) {
169 row.entity = header->getIdentifier();
170 roots.push_back(header);
171 }
172 return row;
173 }
174
175 if (item.kind == List::ItemKind::Divider) {
176 Divider::Builder builder(registry, *list);
177 if (const auto divider = builder.makeDivider(
178 list, width, Divider::Variant::FullWidth)) {
179 row.entity = divider->getIdentifier();
180 roots.push_back(divider);
181 }
182 return row;
183 }
184
185 const auto view = makeView(registry, *list, list);
186 row.view = view->getIdentifier();
187 row.entity = row.view;
188 roots.push_back(view);
189
190 buildRowLead(registry, view, row, item, nested);
191
192 // An accordion shows a chevron; systems::List keeps its glyph in
193 // step with the expanded state.
194 const std::string trailing = item.children.empty()
195 ? item.trailingIcon
196 : std::string(item.expanded ? components::List::ExpandedGlyph
198 if (const auto icon = buildIcon(
199 registry, *view, view, trailing, components::List::IconSize,
200 schemeColor(SchemeColorRole::OnSurfaceVariant))) {
201 row.trailingIcon = icon->getIdentifier();
202 }
203
204 for (const auto &child: item.children) {
205 row.children.push_back(
206 buildRow(registry, list, child, width, true, roots));
207 }
208
209 return row;
210 }
211 } // namespace
212
214 ecs::EntityRegistry &entityRegistry)
215 : EntityBuilderBase<List>(componentRegistry, entityRegistry)
216 {
217 reset();
218 }
219
220 std::shared_ptr<List> List::Builder::buildEntity(void)
221 {
222 auto entity = List::create(this->getComponentRegistry(), _config,
223 _variant, _items);
224 return entity;
225 }
226
228 {
229 _config = SurfaceConfig();
230 _variant = Variant::SingleLine;
231 _items.clear();
232
234 _config.mainAxisAlignment =
236 _config.crossAxisAlignment =
238 _config.padding = 0.0f;
239 _config.spacing = 0.0f;
240 _config.setFixedWidth(components::List::DefaultWidth);
241 }
242
243 List::Builder &List::Builder::withPose(const utility::graphic::PoseF &pose)
244 {
245 _config.pose = pose;
246 return *this;
247 }
248
250 {
251 _variant = variant;
252 return *this;
253 }
254
255 List::Builder &List::Builder::withItems(const std::vector<Item> &items)
256 {
257 _items = items;
258 return *this;
259 }
260
262 {
263 _config.hasFixedWidth = true;
264 _config.fixedWidth = width;
265 return *this;
266 }
267
268 std::shared_ptr<List>
269 List::Builder::makeList(std::shared_ptr<ecs::Entity> parent,
270 Variant variant, const std::vector<Item> &items)
271 {
272 return withVariant(variant).withItems(items).registerEntity(parent);
273 }
274
275 List::Item List::subheader(const std::string &title)
276 {
277 Item item;
278 item.kind = ItemKind::Subheader;
279 item.headline = title;
280 return item;
281 }
282
284 {
285 Item item;
286 item.kind = ItemKind::Divider;
287 return item;
288 }
289
290 List::List(ecs::ComponentRegistry &registry, const SurfaceConfig &config,
291 Variant variant, const std::vector<Item> &items)
292 : SurfaceBase<components::List>(registry, config)
293 {
296 .setVariant(variant)
297 .setItems(items);
299 }
300
302 {
303 }
304
313
320
321 List &List::setItems(const std::vector<Item> &items)
322 {
325 .setItems(items)
326 .setRowsDirty(true);
327 buildItems();
329 return *this;
330 }
331
332 std::size_t List::getItemCount(void) const
333 {
334 return getComponentRegistry()
336 .getItems()
337 .size();
338 }
339
341 {
342 const auto *row = getComponentRegistry()
344 .findRow({ index });
345
346 return row != nullptr ? row->entity : ecs::Entity::InvalidIdentifier;
347 }
348
350 List::getChildIdentifier(std::size_t index,
351 std::size_t childIndex) const
352 {
353 const auto *row = getComponentRegistry()
355 .findRow({ index, childIndex });
356
357 return row != nullptr ? row->entity : ecs::Entity::InvalidIdentifier;
358 }
359
361 {
362 const auto *row = getComponentRegistry()
364 .findRow({ index });
365
366 return row != nullptr ? row->content : ecs::Entity::InvalidIdentifier;
367 }
368
369 List &List::setItemDisabled(std::size_t index, bool disabled)
370 {
372 index, disabled);
373 return *this;
374 }
375
376 List &List::setExpanded(std::size_t index, bool expanded)
377 {
379 index, expanded);
380 return *this;
381 }
382
383 bool List::isExpanded(std::size_t index) const
384 {
386 getIdentifier(), index);
387 }
388
389 void List::build(void)
390 {
391 buildItems();
393 }
394
395 void List::buildItems(void)
396 {
397 // Children need the owning handle as their parent.
398 if (weak_from_this().expired()) {
399 return;
400 }
401
402 auto &registry = getComponentRegistry();
403
404 if (!registry.getComponent<components::List>(getIdentifier())
405 .isRowsDirty()) {
406 return;
407 }
408
409 const auto self = std::static_pointer_cast<List>(shared_from_this());
410 const auto &layout =
411 registry.getComponent<components::Layout>(getIdentifier());
412 const float width = layout.hasFixedWidth()
413 ? layout.getFixedWidth()
415
416 // Copy: the entries are read while the row entities are created.
417 const auto items =
418 registry.getComponent<components::List>(getIdentifier()).getItems();
419 // The rows are rebuilt from scratch: remove the previous generation
420 // with its components. Everything the list owns is a row.
422
423 std::vector<Row> rows;
424 Children roots;
425
426 for (const auto &item: items) {
427 rows.push_back(buildRow(registry, self, item, width, false, roots));
428 }
429
430 registry.getComponent<components::List>(getIdentifier())
431 .setRows(rows)
432 .setRowsDirty(false);
434
435 // Hand every row to the surface; systems::List then narrows the
436 // layout children to the rows currently shown.
437 setChildren(roots);
438 }
439
440} // namespace guillaume::entities
@ Start
At the top (row) or left (column).
Definition layout.hpp:100
@ Start
Packed at the left (row) or top (column).
Definition layout.hpp:87
@ Vertical
Column: children placed top to bottom.
Definition layout.hpp:76
State of a list: a column of rows, each with a headline and optional supporting text,...
Definition list.hpp:58
static constexpr float DefaultWidth
Default width of a list, in dp.
Definition list.hpp:162
static constexpr const char * CollapsedGlyph
Glyph name of the trailing icon of a collapsed accordion.
Definition list.hpp:168
static constexpr const char * ExpandedGlyph
Glyph name of the trailing icon of an expanded accordion.
Definition list.hpp:171
static constexpr float IconSize
Size of the leading and trailing icons, in dp.
Definition list.hpp:165
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.
Owns entities and gives the systems the list of entities to visit.
void clearEntities(void)
Remove every entity owned by this registry, with everything they own and all their components.
Entity::Identifier getIdentifier(void) const noexcept
Get the identifier of the entity.
Definition entity.cpp:94
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
Configures Divider widgets and registers them in the scene's entity registry.
Definition divider.hpp:114
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Configures Image widgets and registers them in the scene's entity registry.
Definition image.hpp:84
Configures a List, creates it and registers it in an entity registry.
Definition list.hpp:113
std::shared_ptr< List > buildEntity(void) override
Build a list and its rows from the current configuration, without registering it or setting its paren...
Definition list.cpp:220
std::shared_ptr< List > makeList(std::shared_ptr< ecs::Entity > parent, Variant variant, const std::vector< Item > &items)
Build a list, register it under parent and reset the builder.
Definition list.cpp:269
Builder & withPose(const utility::graphic::PoseF &pose)
Set where the list is placed.
Definition list.cpp:243
Builder & withItems(const std::vector< Item > &items)
Set the entries, replacing the ones set before.
Definition list.cpp:255
Builder & withFixedWidth(float width)
Set the width of the list and of its rows.
Definition list.cpp:261
void reset(void) override
Restore the defaults.
Definition list.cpp:227
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Create a builder set to the defaults of reset().
Definition list.cpp:213
Builder & withVariant(Variant variant)
Set the variant.
Definition list.cpp:249
A vertical list of pressable rows, with optional subheaders, dividers and accordions that fold nested...
Definition list.hpp:102
List & setItems(const std::vector< Item > &items)
Replace the entries.
Definition list.cpp:321
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.
Definition list.cpp:360
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::Variant Variant
List variant.
Definition list.hpp:104
~List(void) override
Default destructor.
Definition list.cpp:301
List & setVariant(Variant variant)
Change the variant. Restyles at once; the rows are kept.
Definition list.cpp:305
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.
Definition list.cpp:340
static std::shared_ptr< List > create(Arguments &&...arguments)
Create a list and its rows, without registering it in an entity registry.
Definition list.hpp:221
bool isExpanded(std::size_t index) const
Whether a top-level accordion shows its nested rows.
Definition list.cpp:383
Variant getVariant(void) const
Get the variant.
Definition list.cpp:314
List & setItemDisabled(std::size_t index, bool disabled)
Enable or disable a top-level entry. Restyles at once.
Definition list.cpp:369
ecs::Entity::Identifier getChildIdentifier(std::size_t index, std::size_t childIndex) const
Get the root entity of a row nested in an accordion.
Definition list.cpp:350
std::size_t getItemCount(void) const
Get the number of top-level entries.
Definition list.cpp:332
components::List::Item Item
List entry.
Definition list.hpp:106
List & setExpanded(std::size_t index, bool expanded)
Expand or collapse a top-level accordion.
Definition list.cpp:376
Base of the widgets that are a rectangle containing other widgets (Card, Dialog, Checkbox,...
Definition surface.hpp:243
std::vector< std::shared_ptr< ecs::Entity > > Children
Definition surface.hpp:245
SurfaceBase & setChildren(const Children &children)
Configures View widgets and registers them in the scene's entity registry.
Definition view.hpp:118
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 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
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
Makes the color helpers callable from guillaume::entities without qualification.
State. Every class here is plain data attached to an entity.
@ Header
Heading (app bar title, list subheader).
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
std::shared_ptr< Text > buildText(ecs::ComponentRegistry &registry, ecs::EntityRegistry &entityRegistry, std::shared_ptr< ecs::Entity > parent, const std::string &content, float fontSize, const utility::graphic::Color32Bit &color)
Create a Text of a given font size as a child of a widget, or nothing when there is no content.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
std::shared_ptr< Icon > buildIcon(ecs::ComponentRegistry &registry, ecs::EntityRegistry &entityRegistry, std::shared_ptr< ecs::Entity > parent, const std::string &glyphName, float fontSize, const utility::graphic::Color32Bit &color, components::Glyph::Style style=components::Glyph::Style::Outlined)
Create an Icon as a child of a widget, or nothing when there is no glyph to show.
@ BodyLarge
16 / 24, regular.
Definition typescale.hpp:60
@ TitleSmall
14 / 20, medium weight.
Definition typescale.hpp:56
@ BodyMedium
14 / 20, regular.
Definition typescale.hpp:61
ItemKind kind
What the entry is.
Definition list.hpp:97
std::string headline
Main text of the row.
Definition list.hpp:85
Everything needed to set up a surface in one value: where it is, how it looks and how it arranges its...
Definition surface.hpp:71