guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
card.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 <functional>
27#include <memory>
28#include <string>
29#include <vector>
30
31#include <utility/graphic/color.hpp>
32#include <utility/graphic/pose.hpp>
33
34#include "guillaume/ecs/component_registry.hpp"
35#include "guillaume/ecs/entity_builder.hpp"
36
37#include "guillaume/components/animation.hpp"
38#include "guillaume/components/card.hpp"
39#include "guillaume/components/elevation.hpp"
40#include "guillaume/entities/builder_base.hpp"
41#include "guillaume/entities/surface.hpp"
42
43namespace guillaume::entities
44{
45 class Button;
46 class Image;
47 class Text;
48
102 class Card:
103 public SurfaceBase<components::Elevation, components::Animation,
104 components::Card>
105 {
106 public:
109
115
120 static constexpr float TitleMinHeight =
122
127 class Builder: public EntityBuilderBase<Card>
128 {
129 private:
130 SurfaceConfig _config;
131 Variant _variant { Variant::Elevated };
132 std::function<void(void)>
133 _onPress {};
134 bool _disabled { false };
135
136 public:
144 Builder(ecs::ComponentRegistry &componentRegistry,
145 ecs::EntityRegistry &entityRegistry);
146
152 std::shared_ptr<Card> buildEntity(void) override;
153
161 void reset(void) override;
162
169 Builder &withPose(const utility::graphic::PoseF &pose);
170
177 Builder &withVariant(Variant variant);
178
185 Builder &withWidth(float width);
186
193 Builder &withHeight(float height);
194
202 Builder &withBorderRadius(float radius);
203
210 Builder &withOnPress(std::function<void(void)> onPress);
211
218 Builder &withDisabled(bool disabled);
219
233 std::shared_ptr<Card> makeCard(std::shared_ptr<ecs::Entity> parent,
234 Variant variant);
235 };
236
249 template<typename... Arguments>
250 static std::shared_ptr<Card> create(Arguments &&...arguments)
251 {
252 std::shared_ptr<Card> entity(
253 new Card(std::forward<Arguments>(arguments)...));
254 entity->build();
255 return entity;
256 }
257
261 ~Card(void) override;
262
268 Card &setVariant(Variant variant);
269
274 Variant getVariant(void) const;
275
288 Card &setOnPress(std::function<void(void)> onPress);
289
295 bool isInteractive(void) const;
296
306 Card &setDisabled(bool disabled);
307
312 bool isDisabled(void) const;
313
323 Card &setCover(const std::string &texturePath);
324
339 Card &setTitle(const std::string &title,
340 const std::string &subtitle = "");
341
351 Card &setContent(const std::string &content);
352
365 Card &addAction(const std::string &label,
366 std::function<void(void)> onPress);
367
372 std::shared_ptr<Image> getCover(void) const;
373
379 std::shared_ptr<ecs::Entity> getTitleSection(void) const;
380
386 std::shared_ptr<Text> getContent(void) const;
387
392 std::shared_ptr<ecs::Entity> getActionsSection(void) const;
393
402 std::vector<std::shared_ptr<Button>> getActions(void) const;
403
411 float getPressProgress(void) const;
412
413 private:
420 void buildComposition(void);
421
422 private:
431 Card(ecs::ComponentRegistry &registry, const SurfaceConfig &config,
432 Variant variant);
433
441 void build(void);
442 };
443
444} // namespace guillaume::entities
static constexpr float CoverHeight
Height of the cover image, in dp.
Definition card.hpp:96
static constexpr float TitleMinHeight
Minimum height of the title section, in dp.
Definition card.hpp:101
Variant
Look of the card surface.
Definition card.hpp:70
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.
A Material 3 common button: a clickable container with a text label and an optional icon (elevated,...
Definition button.hpp:76
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
A rounded panel grouping a cover image, a title, a text and action buttons about one subject (react-n...
Definition card.hpp:105
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)
A picture loaded from a texture file and stretched over a rectangle.
Definition image.hpp:77
SurfaceBase(ecs::ComponentRegistry &registry, const SurfaceConfig &config)
A single run of text drawn with a typescale role, a color and an optional explicit font size.
Definition text.hpp:85
Widgets: the classes used to create entities with the right components and children.
Definition app_bar.hpp:46
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