guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
card.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 <algorithm>
24#include <memory>
25#include <utility>
26#include <vector>
27
28#include "guillaume/entities/card.hpp"
29
30#include "guillaume/components/accessibility.hpp"
31#include "guillaume/entities/builder_base.hpp"
32#include "guillaume/entities/button.hpp"
33#include "guillaume/entities/content_helpers.hpp"
34#include "guillaume/entities/image.hpp"
36#include "guillaume/entities/text.hpp"
37#include "guillaume/systems/card.hpp"
38#include "guillaume/theme.hpp"
39
40namespace guillaume::entities
41{
42 namespace
43 {
47 class CardSection: public SurfaceBase<>
48 {
49 public:
55 CardSection(ecs::ComponentRegistry &registry,
56 const SurfaceConfig &config)
57 : SurfaceBase<>(registry, config)
58 {
59 }
60
64 ~CardSection(void) override = default;
65 };
66
67 constexpr float DefaultWidth = 240.0f;
68 } // namespace
69
71 ecs::EntityRegistry &entityRegistry)
72 : EntityBuilderBase<Card>(componentRegistry, entityRegistry)
73 {
74 reset();
75 }
76
77 std::shared_ptr<Card> Card::Builder::buildEntity(void)
78 {
79 auto entity =
80 Card::create(this->getComponentRegistry(), _config, _variant);
81 if (_onPress) {
82 entity->setOnPress(_onPress);
83 }
84 entity->setDisabled(_disabled);
85 return entity;
86 }
87
89 {
90 _config = SurfaceConfig();
91 _variant = Variant::Elevated;
92 _onPress = {};
93 _disabled = false;
94 _config.borderRadius = getShapeRadius(theme::ShapeRole::Medium);
95 _config.padding = 16.0f;
96 _config.spacing = 8.0f;
98 _config.setFixedWidth(DefaultWidth);
99 }
100
101 Card::Builder &Card::Builder::withPose(const utility::graphic::PoseF &pose)
102 {
103 _config.pose = pose;
104 return *this;
105 }
106
108 {
109 _variant = variant;
110 return *this;
111 }
112
114 {
115 _config.hasFixedWidth = true;
116 _config.fixedWidth = width;
117 return *this;
118 }
119
121 {
122 _config.hasFixedHeight = true;
123 _config.fixedHeight = height;
124 return *this;
125 }
126
128 {
129 _config.borderRadius = radius;
130 return *this;
131 }
132
133 Card::Builder &Card::Builder::withOnPress(std::function<void(void)> onPress)
134 {
135 _onPress = std::move(onPress);
136 return *this;
137 }
138
140 {
141 _disabled = disabled;
142 return *this;
143 }
144
145 std::shared_ptr<Card>
146 Card::Builder::makeCard(std::shared_ptr<ecs::Entity> parent,
147 Variant variant)
148 {
149 return withVariant(variant).registerEntity(parent);
150 }
151
152 Card::Card(ecs::ComponentRegistry &registry, const SurfaceConfig &config,
153 Variant variant)
154 : SurfaceBase<components::Elevation, components::Animation,
155 components::Card>(registry, config)
156 {
159 .setVariant(variant);
162 }
163
165 {
166 }
167
176
183
184 Card &Card::setOnPress(std::function<void(void)> onPress)
185 {
187 std::move(onPress));
188 return *this;
189 }
190
191 bool Card::isInteractive(void) const
192 {
193 return getComponentRegistry()
195 .isInteractive();
196 }
197
198 Card &Card::setDisabled(bool disabled)
199 {
201 disabled);
202 return *this;
203 }
204
205 bool Card::isDisabled(void) const
206 {
208 getIdentifier());
209 }
210
211 Card &Card::setCover(const std::string &texturePath)
212 {
215 .setCoverPath(texturePath);
216 // A first cover needs its image child.
217 buildComposition();
219 return *this;
220 }
221
222 Card &Card::setTitle(const std::string &title, const std::string &subtitle)
223 {
226 .setTitle(title)
227 .setSubtitle(subtitle);
228 // A first title needs its section and text children.
229 buildComposition();
231 return *this;
232 }
233
234 Card &Card::setContent(const std::string &content)
235 {
238 .setContentText(content);
239 // A first content needs its text child.
240 buildComposition();
242 return *this;
243 }
244
245 Card &Card::addAction(const std::string &label,
246 std::function<void(void)> onPress)
247 {
250 .addAction(components::Card::Action { label, std::move(onPress) });
251 // Every action needs its button child.
252 buildComposition();
254 return *this;
255 }
256
257 std::shared_ptr<Image> Card::getCover(void) const
258 {
259 // The lookup returns a pointer to const because this getter is
260 // const; the child is shared and callers may modify it, hence the
261 // cast.
262 return std::const_pointer_cast<Image>(getEntity<Image>(
264 .getComponent<components::Card>(getIdentifier())
265 .getCover()));
266 }
267
268 std::shared_ptr<ecs::Entity> Card::getTitleSection(void) const
269 {
270 return std::const_pointer_cast<ecs::Entity>(getEntity<ecs::Entity>(
272 .getComponent<components::Card>(getIdentifier())
273 .getTitleSection()));
274 }
275
276 std::shared_ptr<Text> Card::getContent(void) const
277 {
278 return std::const_pointer_cast<Text>(
280 .getComponent<components::Card>(getIdentifier())
281 .getContentEntity()));
282 }
283
284 std::shared_ptr<ecs::Entity> Card::getActionsSection(void) const
285 {
286 return std::const_pointer_cast<ecs::Entity>(getEntity<ecs::Entity>(
288 .getComponent<components::Card>(getIdentifier())
290 }
291
292 std::vector<std::shared_ptr<Button>> Card::getActions(void) const
293 {
294 const auto &card =
296 getIdentifier());
297 const auto row = getEntity<CardSection>(card.getActionsSection());
298 std::vector<std::shared_ptr<Button>> actions;
299
300 if (row == nullptr) {
301 return actions;
302 }
303 // The buttons are owned by the actions row.
304 for (const auto identifier: card.getActionButtons()) {
305 if (auto button = std::const_pointer_cast<Button>(
306 row->getEntity<Button>(identifier))) {
307 actions.push_back(std::move(button));
308 }
309 }
310 return actions;
311 }
312
319
320 void Card::buildComposition(void)
321 {
322 // Children need the owning handle as their parent.
323 if (weak_from_this().expired()) {
324 return;
325 }
326
327 auto &registry = getComponentRegistry();
328 const auto self = shared_from_this();
329 const float inner =
331 auto &card = registry.getComponent<components::Card>(getIdentifier());
332
333 if (card.getCover() == ecs::Entity::InvalidIdentifier
334 && !card.getCoverPath().empty()) {
335 Image::Builder builder(registry, *this);
336 builder.withTexturePath(card.getCoverPath());
337 if (inner > 0.0f) {
338 builder.withSize(inner, CoverHeight);
339 }
340 const auto cover = builder.registerEntity(self);
341 if (cover != nullptr) {
342 card.setCover(cover->getIdentifier());
343 }
344 }
345
346 if (card.getTitleSection() == ecs::Entity::InvalidIdentifier
347 && !card.getTitle().empty()) {
348 SurfaceConfig sectionConfig;
349 sectionConfig.axis = components::Layout::Axis::Vertical;
350 sectionConfig.mainAxisAlignment =
352 sectionConfig.crossAxisAlignment =
354 sectionConfig.setFixedHeight(TitleMinHeight);
355 if (inner > 0.0f) {
356 sectionConfig.setFixedWidth(inner);
357 }
358 auto section =
359 std::make_shared<CardSection>(registry, sectionConfig);
360 section->setParent(self);
361 this->addEntity(section);
362 card.setTitleSection(section->getIdentifier());
363
364 const auto titleText =
365 buildText(registry, *section, section, card.getTitle(),
367 schemeColor(SchemeColorRole::OnSurface));
368 const auto subtitleText =
369 buildText(registry, *section, section, card.getSubtitle(),
371 schemeColor(SchemeColorRole::OnSurfaceVariant));
372
373 std::vector<std::shared_ptr<ecs::Entity>> texts;
374 if (titleText != nullptr) {
375 card.setTitleText(titleText->getIdentifier());
376 texts.push_back(titleText);
377 }
378 if (subtitleText != nullptr) {
379 card.setSubtitleText(subtitleText->getIdentifier());
380 texts.push_back(subtitleText);
381 }
382 section->setChildren(texts);
383 registry.addComponent<components::Accessibility>(
384 section->getIdentifier());
385 registry
386 .getComponent<components::Accessibility>(
387 section->getIdentifier())
389 .setLabel(card.getTitle());
390 }
391
392 if (card.getContentEntity() == ecs::Entity::InvalidIdentifier
393 && !card.getContentText().empty()) {
394 const auto content =
395 buildText(registry, *this, self, card.getContentText(),
397 schemeColor(SchemeColorRole::OnSurfaceVariant));
398 if (content != nullptr) {
399 card.setContentEntity(content->getIdentifier());
400 }
401 }
402
403 if (!card.getActions().empty()) {
404 if (card.getActionsSection() == ecs::Entity::InvalidIdentifier) {
405 SurfaceConfig rowConfig;
407 rowConfig.mainAxisAlignment =
409 rowConfig.crossAxisAlignment =
411 rowConfig.spacing = 8.0f;
412 if (inner > 0.0f) {
413 rowConfig.setFixedWidth(inner);
414 }
415 auto section =
416 std::make_shared<CardSection>(registry, rowConfig);
417 section->setParent(self);
418 this->addEntity(section);
419 card.setActionsSection(section->getIdentifier());
420 }
421
422 const auto row = getEntity<CardSection>(card.getActionsSection());
423 auto identifiers = card.getActionButtons();
424 while (row != nullptr
425 && identifiers.size() < card.getActions().size()) {
426 const auto &action = card.getActions()[identifiers.size()];
427 Button::Builder builder(registry, *row);
428 const auto button = builder.withLabel(action.label)
429 .withOnClick(action.onPress)
430 .withColorStyle(Button::Color::Text)
431 .registerEntity(row);
432 identifiers.push_back(button != nullptr
433 ? button->getIdentifier()
435 }
436 card.setActionButtons(identifiers);
437
438 if (row != nullptr) {
439 std::vector<std::shared_ptr<ecs::Entity>> buttons;
440 for (const auto identifier: identifiers) {
441 if (auto button = row->getEntity<Button>(identifier)) {
442 buttons.push_back(std::move(button));
443 }
444 }
445 row->setChildren(buttons);
446 }
447 }
448
449 // Hand the layout children to the surface.
450 std::vector<std::shared_ptr<ecs::Entity>> children;
451 for (const auto identifier:
452 { card.getCover(), card.getTitleSection(), card.getContentEntity(),
453 card.getActionsSection() }) {
454 if (auto child = getEntity<ecs::Entity>(identifier)) {
455 children.push_back(std::move(child));
456 }
457 }
458 setChildren(children);
459 }
460
461 void Card::build(void)
462 {
463 buildComposition();
465 }
466
467} // namespace guillaume::entities
State of a card: a surface grouping an optional cover image, title, text and row of action buttons.
Definition card.hpp:65
@ Start
At the top (row) or left (column).
Definition layout.hpp:100
@ End
Packed at the right (row) or bottom (column).
Definition layout.hpp:89
@ Vertical
Column: children placed top to bottom.
Definition layout.hpp:76
@ Horizontal
Row: children placed left to right.
Definition layout.hpp:75
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.
ComponentType & addComponent(const Entity::Identifier &entityIdentifier, Args &&...args)
Construct a component for an entity, replacing the one it already has, if any.
ComponentRegistry & getComponentRegistry(void)
Get the registry in which the builder creates components.
Owns entities and gives the systems the list of entities to visit.
void addEntity(std::shared_ptr< Entity > entity)
Make this registry own an entity, so that it stays alive and systems visit it.
std::shared_ptr< EntityType > getEntity(Entity::Identifier identifier)
Find an entity owned directly by this registry, by identifier.
Entity::Identifier getIdentifier(void) const noexcept
Get the identifier of the entity.
Definition entity.cpp:94
static constexpr Identifier InvalidIdentifier
"No entity": never the identifier of a real entity
Definition entity.hpp:93
A Material 3 common button: a clickable container with a text label and an optional icon (elevated,...
Definition button.hpp:76
Configures Card widgets and registers them in the scene's entity registry.
Definition card.hpp:128
Builder & withWidth(float width)
Set the width of the card.
Definition card.cpp:113
void reset(void) override
Restore the defaults: default pose, the Elevated variant, no press handler, enabled,...
Definition card.cpp:88
std::shared_ptr< Card > makeCard(std::shared_ptr< ecs::Entity > parent, Variant variant)
Build an empty card, register it under parent and reset the builder.
Definition card.cpp:146
Builder & withDisabled(bool disabled)
Build the card disabled or enabled.
Definition card.cpp:139
Builder & withOnPress(std::function< void(void)> onPress)
Make the built card pressable.
Definition card.cpp:133
Builder & withBorderRadius(float radius)
Set the corner radius.
Definition card.cpp:127
std::shared_ptr< Card > buildEntity(void) override
Build an empty card from the current configuration, without registering it or giving it a parent.
Definition card.cpp:77
Builder & withHeight(float height)
Force the height of the card.
Definition card.cpp:120
Builder(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Construct a builder holding the defaults of reset().
Definition card.cpp:70
Builder & withVariant(Variant variant)
Choose the look of the card.
Definition card.cpp:107
Builder & withPose(const utility::graphic::PoseF &pose)
Set where the card is.
Definition card.cpp:101
static constexpr float CoverHeight
Height given to the cover image, in dp (Paper Card.Cover: 195).
Definition card.hpp:114
Card & setOnPress(std::function< void(void)> onPress)
Make the card pressable and set what a press does (Paper onPress).
Definition card.cpp:184
static std::shared_ptr< Card > create(Arguments &&...arguments)
Build a card without registering it in an entity registry.
Definition card.hpp:250
Card & addAction(const std::string &label, std::function< void(void)> onPress)
Append a text button to the row at the bottom of the card (Paper Card.Actions).
Definition card.cpp:245
Card & setContent(const std::string &content)
Show a text under the title (Paper Card.Content).
Definition card.cpp:234
Card & setDisabled(bool disabled)
Disable or enable the card (Paper disabled). Restyles at once.
Definition card.cpp:198
Card & setCover(const std::string &texturePath)
Show an image at the top of the card (Paper Card.Cover).
Definition card.cpp:211
bool isInteractive(void) const
Check whether the card reacts to input.
Definition card.cpp:191
std::shared_ptr< ecs::Entity > getActionsSection(void) const
Get the row holding the action buttons.
Definition card.cpp:284
Variant getVariant(void) const
Get the look of the card.
Definition card.cpp:177
Card & setVariant(Variant variant)
Change the look of the card. Restyles at once.
Definition card.cpp:168
static constexpr float TitleMinHeight
Height given to the title section, in dp (the minimum height of Paper Card.Title: 72).
Definition card.hpp:120
float getPressProgress(void) const
Get how far the press elevation has progressed.
Definition card.cpp:313
std::shared_ptr< Image > getCover(void) const
Get the cover image.
Definition card.cpp:257
bool isDisabled(void) const
Check whether the card ignores presses.
Definition card.cpp:205
std::shared_ptr< Text > getContent(void) const
Get the content text.
Definition card.cpp:276
components::Card::Variant Variant
Look of the card: Elevated, Filled or Outlined.
Definition card.hpp:108
std::vector< std::shared_ptr< Button > > getActions(void) const
Get the action buttons.
Definition card.cpp:292
~Card(void) override
Destructor.
Definition card.cpp:164
Card & setTitle(const std::string &title, const std::string &subtitle="")
Show a title, and optionally a subtitle under it (Paper Card.Title).
Definition card.cpp:222
std::shared_ptr< ecs::Entity > getTitleSection(void) const
Get the section holding the title and subtitle texts.
Definition card.cpp:268
EntityBuilderBase(ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry)
Base of the widgets that are a rectangle containing other widgets (Card, Dialog, Checkbox,...
Definition surface.hpp:243
SurfaceBase(ecs::ComponentRegistry &registry, const SurfaceConfig &config)
static void install(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Prepare the press-elevation motion of a card.
Definition card.cpp:231
static void setDisabled(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool disabled)
Enable or disable the card and restyle it.
Definition card.cpp:310
static float contentWidth(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Get the width a section of the card can use, in dp.
Definition card.cpp:330
static bool isDisabled(const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Whether the card ignores input.
Definition card.cpp:324
static void apply(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Style one card and arrange its sections.
Definition card.cpp:341
static void setOnPress(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, components::Card::Handler handler)
Set the press handler and make the card pressable.
Definition card.cpp:251
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
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.
@ BodyLarge
16 / 24, regular.
Definition typescale.hpp:60
@ BodyMedium
14 / 20, regular.
Definition typescale.hpp:61
@ Medium
12 dp (cards).
Definition tokens.hpp:46
float getShapeRadius(theme::ShapeRole role)
Get the corner radius the active theme gives to a shape role.
One button of the actions row: its label and what it does.
Definition card.hpp:81
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