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 "guillaume/systems/card.hpp"
24
25#include <algorithm>
26#include <cstdint>
27#include <string>
28#include <utility>
29#include <vector>
30
31#include "guillaume/components/accessibility.hpp"
32#include "guillaume/components/animation.hpp"
33#include "guillaume/components/borders.hpp"
34#include "guillaume/components/color.hpp"
35#include "guillaume/components/elevation.hpp"
36#include "guillaume/components/image.hpp"
37#include "guillaume/components/layout.hpp"
38#include "guillaume/components/text.hpp"
41#include "guillaume/systems/layout.hpp"
42#include "guillaume/theme.hpp"
43
44namespace guillaume::systems
45{
46 namespace
47 {
48 using Variant = components::Card::Variant;
51
59 utility::graphic::Color32Bit
60 lerpColor(const utility::graphic::Color32Bit &from,
61 const utility::graphic::Color32Bit &to, float t)
62 {
63 const auto mix = [t](std::uint8_t a, std::uint8_t b) {
64 return static_cast<std::uint8_t>(
65 static_cast<float>(a)
66 + (static_cast<float>(b) - static_cast<float>(a)) * t
67 + 0.5f);
68 };
69 return utility::graphic::Color32Bit(
70 mix(from.getRed(), to.getRed()),
71 mix(from.getGreen(), to.getGreen()),
72 mix(from.getBlue(), to.getBlue()),
73 mix(from.getAlpha(), to.getAlpha()));
74 }
75
82 void writeText(ecs::ComponentRegistry &registry,
84 const std::string &content)
85 {
86 if (registry.hasComponent<components::Text>(child)) {
87 registry.getComponent<components::Text>(child).setContent(
88 content);
89 }
90 }
91
99 void
100 arrangeSection(ecs::ComponentRegistry &registry,
102 const std::vector<ecs::Entity::Identifier> &children)
103 {
104 if (!registry.hasComponent<components::Layout>(section)
105 || !registry.hasComponent<components::Transform>(section)
106 || !registry.hasComponent<components::Bound>(section)) {
107 return;
108 }
109 registry.getComponent<components::Layout>(section).setChildren(
110 children);
111 Layout::apply(registry, section, children,
112 Layout::layerOf(registry, section));
113 }
114
120 void arrangeSections(ecs::ComponentRegistry &registry,
121 const components::Card &card)
122 {
123 const auto invalid = ecs::Entity::InvalidIdentifier;
124 std::vector<ecs::Entity::Identifier> texts;
125 std::vector<ecs::Entity::Identifier> buttons;
126
127 if (card.getTitleText() != invalid) {
128 texts.push_back(card.getTitleText());
129 }
130 if (card.getSubtitleText() != invalid) {
131 texts.push_back(card.getSubtitleText());
132 }
133 for (const auto button: card.getActionButtons()) {
134 if (button != invalid) {
135 buttons.push_back(button);
136 }
137 }
138 arrangeSection(registry, card.getTitleSection(), texts);
139 arrangeSection(registry, card.getActionsSection(), buttons);
140 }
141
147 void applyStyle(ecs::ComponentRegistry &registry,
148 ecs::Entity::Identifier identifier)
149 {
150 const auto &card =
151 registry.getComponent<components::Card>(identifier);
152 auto &borders =
153 registry.getComponent<components::Borders>(identifier);
154 auto &elevation =
155 registry.getComponent<components::Elevation>(identifier);
156 utility::graphic::Color32Bit container;
157
158 switch (card.getVariant()) {
159 case Variant::Elevated: {
160 // Paper raises an elevated card from level 1 to level 2
161 // while pressed; the shadow and the tonal tint follow
162 // the motion.
163 const auto &rest =
165 const auto &raised =
167 const float t = card.getPressProgress();
168 container = lerpColor(
171 t);
172
173 const auto level = t >= 0.5f
176 const float spread = rest.shadowSpread
177 + (raised.shadowSpread - rest.shadowSpread) * t;
178 const utility::graphic::Color32Bit shadow(
179 0, 0, 0,
180 static_cast<std::uint8_t>(
181 static_cast<float>(rest.shadowAlpha)
182 + (static_cast<float>(raised.shadowAlpha)
183 - static_cast<float>(rest.shadowAlpha))
184 * t));
185
186 // Setting the level resets the spread and the shadow
187 // color to its token: only write on a real change.
188 if (elevation.getElevationLevel() != level
189 || elevation.getLevel() != 1.0f
190 || elevation.getSpread() != spread
191 || elevation.getColor() != shadow) {
192 elevation.setElevationLevel(level)
193 .setSpread(spread)
194 .setColor(shadow);
195 }
196 borders.setColor(transparentColor()).setWidth(0.0f);
197 break;
198 }
199 case Variant::Filled: {
200 container = schemeColor(SchemeColorRole::SurfaceVariant);
201 borders.setColor(transparentColor()).setWidth(0.0f);
202 elevation.setElevationLevel(theme::ElevationLevel::Level0);
203 break;
204 }
205 case Variant::Outlined:
206 default: {
207 container = schemeColor(SchemeColorRole::Surface);
208 borders
209 .setColor(schemeColor(SchemeColorRole::OutlineVariant))
210 .setWidth(1.0f);
211 elevation.setElevationLevel(theme::ElevationLevel::Level0);
212 break;
213 }
214 }
215
216 if (card.isInteractive()) {
218 registry, identifier, container,
219 schemeColor(SchemeColorRole::OnSurface));
220 }
221 registry.getComponent<components::Color>(identifier)
222 .setColor(container);
223 }
224 } // namespace
225
228 {
229 }
230
231 void Card::install(ecs::ComponentRegistry &componentRegistry,
232 const ecs::Entity::Identifier &entityIdentifier)
233 {
234 ecs::ComponentRegistry *registry = &componentRegistry;
235 const ecs::Entity::Identifier identifier = entityIdentifier;
236
237 componentRegistry.getComponent<components::Animation>(identifier)
240 .setOnSampleHandler([registry, identifier](float progress) {
241 auto &card =
242 registry->getComponent<components::Card>(identifier);
243 const float target = card.isPressed() ? 1.0f : 0.0f;
244 const float from = card.getPressFrom();
245
246 card.setPressProgress(from + (target - from) * progress);
247 apply(*registry, identifier);
248 });
249 }
250
252 const ecs::Entity::Identifier &entityIdentifier,
254 {
255 ecs::ComponentRegistry *registry = &componentRegistry;
256 const ecs::Entity::Identifier identifier = entityIdentifier;
257 auto &card =
258 componentRegistry.getComponent<components::Card>(identifier);
259
260 card.setOnPress(std::move(handler));
261 if (!card.isInteractive()) {
262 card.setInteractive(true);
264 componentRegistry, identifier,
266 [registry, identifier]() {
267 press(*registry, identifier);
268 },
269 [registry, identifier]() {
270 interactionChanged(*registry, identifier);
271 });
272 }
273 apply(componentRegistry, identifier);
274 }
275
276 void Card::press(ecs::ComponentRegistry &componentRegistry,
277 const ecs::Entity::Identifier &entityIdentifier)
278 {
279 if (isDisabled(componentRegistry, entityIdentifier)) {
280 return;
281 }
282
283 // Copy: the callback may replace itself.
284 const auto onPress =
285 componentRegistry.getComponent<components::Card>(entityIdentifier)
286 .getOnPress();
287 if (onPress) {
288 onPress();
289 }
290 }
291
293 ecs::ComponentRegistry &componentRegistry,
294 const ecs::Entity::Identifier &entityIdentifier)
295 {
296 auto &card =
297 componentRegistry.getComponent<components::Card>(entityIdentifier);
298 const bool pressed = card.getVariant() == Variant::Elevated
299 && interaction::isPressed(componentRegistry, entityIdentifier);
300
301 if (pressed != card.isPressed()) {
302 card.setPressed(pressed).setPressFrom(card.getPressProgress());
303 componentRegistry
304 .getComponent<components::Animation>(entityIdentifier)
305 .play();
306 }
307 apply(componentRegistry, entityIdentifier);
308 }
309
311 const ecs::Entity::Identifier &entityIdentifier,
312 bool disabled)
313 {
314 auto &card =
315 componentRegistry.getComponent<components::Card>(entityIdentifier);
316
317 interaction::setEnabled(componentRegistry, entityIdentifier, !disabled);
318 if (disabled && card.isPressed()) {
319 card.setPressed(false).setPressProgress(0.0f);
320 }
321 apply(componentRegistry, entityIdentifier);
322 }
323
324 bool Card::isDisabled(const ecs::ComponentRegistry &componentRegistry,
325 const ecs::Entity::Identifier &entityIdentifier)
326 {
327 return !interaction::isEnabled(componentRegistry, entityIdentifier);
328 }
329
330 float Card::contentWidth(const ecs::ComponentRegistry &componentRegistry,
331 const ecs::Entity::Identifier &entityIdentifier)
332 {
333 const auto &layout = componentRegistry.getComponent<components::Layout>(
334 entityIdentifier);
335 const float width =
336 layout.hasFixedWidth() ? layout.getFixedWidth() : 0.0f;
337
338 return std::max(0.0f, width - 2.0f * layout.getPadding());
339 }
340
341 void Card::apply(ecs::ComponentRegistry &componentRegistry,
342 const ecs::Entity::Identifier &entityIdentifier)
343 {
344 const auto &card =
345 componentRegistry.getComponent<components::Card>(entityIdentifier);
346 auto &layout = componentRegistry.getComponent<components::Layout>(
347 entityIdentifier);
348 const auto invalid = ecs::Entity::InvalidIdentifier;
349 const auto cover = card.getCover();
350 const auto titleSection = card.getTitleSection();
351 const auto content = card.getContentEntity();
352 const auto actionsSection = card.getActionsSection();
353
354 applyStyle(componentRegistry, entityIdentifier);
355
356 if (componentRegistry.hasComponent<components::Image>(cover)) {
357 componentRegistry.getComponent<components::Image>(cover)
358 .setTexturePath(card.getCoverPath());
359 }
360 writeText(componentRegistry, card.getTitleText(), card.getTitle());
361 writeText(componentRegistry, card.getSubtitleText(),
362 card.getSubtitle());
363 writeText(componentRegistry, content, card.getContentText());
364 if (componentRegistry.hasComponent<components::Accessibility>(
365 titleSection)) {
366 componentRegistry
368 .setLabel(card.getTitle());
369 }
370
371 // The sections are sized first, so the card arranges them with their
372 // final bounds.
373 arrangeSections(componentRegistry, card);
374
375 // A card without composed content keeps whatever children it was
376 // given; otherwise the sections are laid out cover, title, content,
377 // actions.
378 if (cover != invalid || titleSection != invalid || content != invalid
379 || actionsSection != invalid) {
380 std::vector<ecs::Entity::Identifier> children;
381 for (const auto child:
382 { cover, titleSection, content, actionsSection }) {
383 if (child != invalid) {
384 children.push_back(child);
385 }
386 }
387 layout.setChildren(children);
388 }
389 Layout::apply(componentRegistry, entityIdentifier, layout.getChildren(),
390 Layout::layerOf(componentRegistry, entityIdentifier));
391
392 // The card may have moved its sections: place their content again.
393 arrangeSections(componentRegistry, card);
394 }
395
396 void Card::update(const ecs::Entity::Identifier &entityIdentifier)
397 {
398 if (!requireComponent<components::Card>(entityIdentifier)) {
399 return;
400 }
401
402 apply(getComponentRegistry(), entityIdentifier);
403 }
404} // namespace guillaume::systems
What an entity means to a user who does not see it: its name, its role, its state and its place in th...
A timer that runs from 0 to a duration and reports its eased progress, from 0 to 1,...
Definition animation.hpp:61
Animation & setEasing(motion::Easing easing)
Set the curve that turns the linear progress into the value passed to the sample handler.
Animation & setOnSampleHandler(const SampleHandler &handler)
Store the callback that applies the animation.
State of a card: a surface grouping an optional cover image, title, text and row of action buttons.
Definition card.hpp:65
bool isPressed(void) const noexcept
Check whether the press motion is heading to the raised state.
Definition card.cpp:57
std::function< void(void)> Handler
Callback run when the card is pressed.
Definition card.hpp:88
Variant
Look of the card surface.
Definition card.hpp:70
Card & setOnPress(Handler handler)
Store the callback run when the card is pressed.
Definition card.cpp:270
Variant getVariant(void) const noexcept
Get the look of the card surface.
Definition card.cpp:29
A picture drawn in the entity's rectangle: the texture to show, a fallback texture,...
Definition image.hpp:56
How a container arranges its children: in a row or a column, with which alignment,...
Definition layout.hpp:69
bool hasFixedWidth(void) const
Check whether the container width is forced.
Definition layout.cpp:102
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.
bool hasComponent(const Entity::Identifier &entityIdentifier) const
Tell whether an entity has a component of a given type.
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
ecs::ComponentRegistry & getComponentRegistry(void)
Get the component registry of the scene being processed.
Definition system.cpp:53
bool requireComponent(const ecs::Entity::Identifier &entityIdentifier)
Tell whether an entity has a component, and log a warning naming the entity and the component when it...
void update(const ecs::Entity::Identifier &entityIdentifier) override
Run apply() on one card; called by the frame loop.
Definition card.cpp:396
static void press(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
Activate the card as a click or a key press would.
Definition card.cpp:276
Card(void)
Create the system in the Layout phase.
Definition card.cpp:226
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 void interactionChanged(ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
React to a change of the hover or press state of the card.
Definition card.cpp:292
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
Arranges the children of a container in a row or a column and sizes the container around them.
Definition layout.hpp:84
static void apply(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, std::uint32_t layer=0)
Arrange children inside a container and size the container.
Definition layout.cpp:126
static std::uint32_t layerOf(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Get the layer of an entity: its depth in the entity tree.
Definition layout.cpp:90
static constexpr motion::Easing standard(void)
Get the easing for elements that move or change while staying on screen.
Definition tokens.hpp:380
State. Every class here is plain data attached to an entity.
The entity-component-system core, independent of any widget.
Definition component.hpp:28
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
Rules. Every class here runs each frame on the entities that have the components it declares.
utility::graphic::Color32Bit transparentColor(void)
The color written to hide a fill or an outline without removing its component.
utility::graphic::Color32Bit schemeColor(SchemeColorRole role)
Look up a color role in the color scheme of the active theme.
@ Level2
Second raised level.
Definition tokens.hpp:133
@ Level1
Lowest raised level.
Definition tokens.hpp:132
@ Level0
Flat: no shadow, no tint.
Definition tokens.hpp:131
utility::graphic::Color32Bit getElevatedSurfaceColor(theme::ElevationLevel level)
Get the background color of a surface raised to an elevation level.
const theme::ElevationToken & getElevationToken(theme::ElevationLevel level)
Get the shadow and tint the active theme gives to an elevation level.
float getMotionDuration(theme::MotionDuration duration)
Get the length the active theme gives to a duration token.
Helpers of the namespace systems::interaction: what "pressable" means for a widget,...
bool isPressed(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier)
Whether an entity is being pressed.
bool isEnabled(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier)
Whether an entity accepts input.
void makeInteractive(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, components::AccessibilityRole role, std::function< void(void)> onPress, std::function< void(void)> onStateChange={})
Make an entity hoverable, pressable and focusable.
void setEnabled(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, bool enabled)
Enable or disable an entity.
utility::graphic::Color32Bit stateLayerColor(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &entityIdentifier, const utility::graphic::Color32Bit &base, const utility::graphic::Color32Bit &content)
Container color of a widget in its current input state.
Color helpers shared by the widget systems: scheme lookup, state layers and the disabled colors.