guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
list.hpp
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#pragma once
24
25#include <utility>
26#include <cstddef>
27#include <functional>
28#include <memory>
29#include <string>
30#include <vector>
31
32#include <utility/graphic/color.hpp>
33#include <utility/graphic/pose.hpp>
34
35#include "guillaume/ecs/component_registry.hpp"
36#include "guillaume/ecs/entity_builder.hpp"
37
38#include "guillaume/components/list.hpp"
39
40#include "guillaume/entities/builder_base.hpp"
41#include "guillaume/entities/icon.hpp"
42#include "guillaume/entities/surface.hpp"
43#include "guillaume/entities/text.hpp"
44#include "guillaume/entities/view.hpp"
45
46namespace guillaume::entities
47{
48
101 class List: public SurfaceBase<components::List>
102 {
103 public:
107
112 class Builder: public EntityBuilderBase<List>
113 {
114 private:
115 SurfaceConfig _config;
116 Variant _variant { Variant::SingleLine };
117 std::vector<Item> _items {};
118
119 public:
126 Builder(ecs::ComponentRegistry &componentRegistry,
127 ecs::EntityRegistry &entityRegistry);
128
134 std::shared_ptr<List> buildEntity(void) override;
135
142 void reset(void) override;
143
150 Builder &withPose(const utility::graphic::PoseF &pose);
151
159 Builder &withVariant(Variant variant);
160
166 Builder &withItems(const std::vector<Item> &items);
167
173 Builder &withFixedWidth(float width);
174
185 std::shared_ptr<List> makeList(std::shared_ptr<ecs::Entity> parent,
186 Variant variant,
187 const std::vector<Item> &items);
188 };
189
198 static Item subheader(const std::string &title);
199
206 static Item divider(void);
207
220 template<typename... Arguments>
221 static std::shared_ptr<List> create(Arguments &&...arguments)
222 {
223 std::shared_ptr<List> entity(
224 new List(std::forward<Arguments>(arguments)...));
225 entity->build();
226 return entity;
227 }
228
232 ~List(void) override;
233
240 List &setVariant(Variant variant);
241
246 Variant getVariant(void) const;
247
257 List &setItems(const std::vector<Item> &items);
258
264 std::size_t getItemCount(void) const;
265
274 ecs::Entity::Identifier getItemIdentifier(std::size_t index) const;
275
287 getChildIdentifier(std::size_t index, std::size_t childIndex) const;
288
297 ecs::Entity::Identifier getContentIdentifier(std::size_t index) const;
298
308 List &setItemDisabled(std::size_t index, bool disabled);
309
320 List &setExpanded(std::size_t index, bool expanded);
321
328 bool isExpanded(std::size_t index) const;
329
330 private:
339 void buildItems(void);
340
341 private:
352 List(ecs::ComponentRegistry &registry, const SurfaceConfig &config,
353 Variant variant, const std::vector<Item> &items);
354
361 void build(void);
362 };
363
364} // namespace guillaume::entities
ItemKind
What a list entry is.
Definition list.hpp:71
Variant
Number of text lines a row is meant for.
Definition list.hpp:66
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
Owns entities and gives the systems the list of entities to visit.
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
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
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
components::List::ItemKind ItemKind
Kind of an entry.
Definition list.hpp:105
List & setExpanded(std::size_t index, bool expanded)
Expand or collapse a top-level accordion.
Definition list.cpp:376
SurfaceBase(ecs::ComponentRegistry &registry, const SurfaceConfig &config)
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
Description of one list entry, as given by the user.
Definition list.hpp:84
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