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 <cstddef>
26#include <functional>
27#include <string>
28#include <vector>
29
30#include "guillaume/ecs/component.hpp"
31#include "guillaume/ecs/entity.hpp"
32
34{
35
57 class List: public ecs::Component
58 {
59 public:
66 enum class Variant { SingleLine, TwoLine, ThreeLine };
67
77
84 struct Item {
85 std::string headline;
86 std::string supporting;
88 std::string leadingIcon;
90 std::string trailingIcon;
92 std::string leadingImage {};
94 std::function<void(void)> onPress {};
95 bool disabled { false };
98 std::vector<Item> children {};
100 bool expanded { false };
102 };
103
155
159 using Path = std::vector<std::size_t>;
160
162 static constexpr float DefaultWidth = 360.0f;
163
165 static constexpr float IconSize = 24.0f;
166
168 static constexpr const char *CollapsedGlyph = "expand_more";
169
171 static constexpr const char *ExpandedGlyph = "expand_less";
172
173 private:
174 Variant _variant { Variant::SingleLine };
175 std::vector<Item> _items {};
176 std::vector<Row> _rows {};
177 bool _rowsDirty { true };
178
179 public:
183 List(void) = default;
184
188 ~List(void) = default;
189
194 Variant getVariant(void) const noexcept;
195
203 List &setVariant(Variant variant);
204
210 const std::vector<Item> &getItems(void) const noexcept;
211
223 List &setItems(std::vector<Item> items);
224
231 const Item *findItem(const Path &path) const noexcept;
232
240 const Row *findRow(const Path &path) const noexcept;
241
253 List &setItemDisabled(std::size_t index, bool disabled);
254
266 List &setItemExpanded(std::size_t index, bool expanded);
267
273 const std::vector<Row> &getRows(void) const noexcept;
274
282 List &setRows(const std::vector<Row> &rows);
283
289 bool isRowsDirty(void) const noexcept;
290
300 List &setRowsDirty(bool dirty);
301 };
302
303} // namespace guillaume::components
State of a divider: a thin horizontal line separating content.
Definition divider.hpp:59
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
List & setRows(const std::vector< Row > &rows)
Record the entities built for the entries.
Definition list.cpp:150
Variant getVariant(void) const noexcept
Get the number of text lines a row is meant for.
Definition list.cpp:63
List & setRowsDirty(bool dirty)
Mark the rows as out of date or as up to date.
Definition list.cpp:164
ItemKind
What a list entry is.
Definition list.hpp:71
@ Subheader
Section header (titleSmall text).
Definition list.hpp:74
List & setVariant(Variant variant)
Set the number of text lines a row is meant for.
Definition list.cpp:68
List & setItems(std::vector< Item > items)
Replace the entries.
Definition list.cpp:82
~List(void)=default
Default destructor.
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
List & setItemDisabled(std::size_t index, bool disabled)
Change the disabled flag recorded for one top-level entry.
Definition list.cpp:126
bool isRowsDirty(void) const noexcept
Tell whether the rows must be rebuilt from the entries.
Definition list.cpp:159
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 std::vector< Item > & getItems(void) const noexcept
Get the description of every top-level entry.
Definition list.cpp:77
List(void)=default
Create the configuration of an empty single-line list.
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
static constexpr float IconSize
Size of the leading and trailing icons, in dp.
Definition list.hpp:165
List & setItemExpanded(std::size_t index, bool expanded)
Record whether one top-level accordion shows its children.
Definition list.cpp:135
Base class of every component: a piece of state attached to an entity, plus a "changed" flag.
Definition component.hpp:72
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
State. Every class here is plain data attached to an entity.
Description of one list entry, as given by the user.
Definition list.hpp:84
ItemKind kind
What the entry is.
Definition list.hpp:97
std::function< void(void)> onPress
Called on press.
Definition list.hpp:94
std::string headline
Main text of the row.
Definition list.hpp:85
std::vector< Item > children
Definition list.hpp:98
Identifiers of the entities built for one entry.
Definition list.hpp:113
ecs::Entity::Identifier headline
Headline text child.
Definition list.hpp:135
std::vector< Row > children
Definition list.hpp:144
ecs::Entity::Identifier leadingImage
Leading image child.
Definition list.hpp:126
ecs::Entity::Identifier content
Column holding the headline and supporting text.
Definition list.hpp:132
ecs::Entity::Identifier entity
Row root (container, subheader text or divider).
Definition list.hpp:114
ecs::Entity::Identifier view
Pressable row container.
Definition list.hpp:117
ecs::Entity::Identifier supporting
Supporting text child.
Definition list.hpp:138
ecs::Entity::Identifier trailingIcon
Trailing icon child (the chevron of an accordion).
Definition list.hpp:141
bool operator==(const Row &other) const noexcept
Compare two rows.
Definition list.cpp:53
ecs::Entity::Identifier lead
Leading group.
Definition list.hpp:120
ecs::Entity::Identifier leadingIcon
Leading icon child.
Definition list.hpp:129
ecs::Entity::Identifier spacer
Nesting inset of an accordion child.
Definition list.hpp:123