guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::systems::Card Class Reference

Styles a card, animates its elevation while pressed and arranges its cover, title, content and actions sections. More...

#include <headers/guillaume/systems/card.hpp>

Inheritance diagram for guillaume::systems::Card:
Collaboration diagram for guillaume::systems::Card:

Public Member Functions

 Card (void)
 Create the system in the Layout phase.
 ~Card (void) override=default
 Default destructor.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Run apply() on one card; called by the frame loop.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Card >
 SystemFiller (Phase phase)
 Create the system and set its signature from ComponentTypes.
virtual ~SystemFiller (void)=default
 Virtual destructor.
Public Member Functions inherited from guillaume::ecs::System
 System (Phase phase)
 Create a system that runs in a given phase, with an empty signature.
virtual ~System (void)=default
 Virtual destructor.
Phase getPhase (void) const noexcept
 Get the phase of the frame in which the system runs.
Entity::Signature getSignature (void) const noexcept
 Get the component types an entity must declare to be visited by this system.
void routine (ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry, const ecs::EntityTreeTraveler &traveler)
 Run the system once over a scene: prepare(), update() on each matching entity, cleanup().
void bindComponentRegistry (ecs::ComponentRegistry &componentRegistry)
 Bind a component registry so update() can be called directly, without routine().
void unbindComponentRegistry (void)
 Drop the binding made by bindComponentRegistry().
virtual void prepare (void)
 Called once per pass, before the first update().
virtual void cleanup (void)
 Called once per pass, after the last update().

Static Public Member Functions

static void install (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Prepare the press-elevation motion of a card.
static void apply (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Style one card and arrange its sections.
static void setOnPress (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, components::Card::Handler handler)
 Set the press handler and make the card pressable.
static void press (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Activate the card as a click or a key press would.
static void interactionChanged (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 React to a change of the hover or press state of the card.
static void setDisabled (ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier, bool disabled)
 Enable or disable the card and restyle it.
static bool isDisabled (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Whether the card ignores input.
static float contentWidth (const ecs::ComponentRegistry &componentRegistry, const ecs::Entity::Identifier &entityIdentifier)
 Get the width a section of the card can use, in dp.

Additional Inherited Members

Protected Member Functions inherited from guillaume::ecs::System
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.
ecs::EntityRegistry & getEntityRegistry (void)
 Get the entity registry of the scene being processed.
const ecs::EntityRegistry & getEntityRegistry (void) const
 Get the entity registry of the scene being processed, read-only.
ecs::ComponentRegistry & getComponentRegistry (void)
 Get the component registry of the scene being processed.
const ecs::ComponentRegistry & getComponentRegistry (void) const
 Get the component registry of the scene being processed, read-only.
template<InheritFromComponent ComponentType>
bool hasComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Tell whether an entity has a component, in the bound registry.
template<InheritFromComponent ComponentType>
ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier)
 Get a component of an entity from the bound registry, to read or modify it.
template<InheritFromComponent ComponentType>
const ComponentType & getComponent (const ecs::Entity::Identifier &entityIdentifier) const
 Get a component of an entity from the bound registry, read-only.
template<InheritFromComponent ComponentType>
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 does not.

Detailed Description

Styles a card, animates its elevation while pressed and arranges its cover, title, content and actions sections.

Runs in the Layout phase on every entity that has a components::Card. It is registered after systems::Layout, so the children are already measured when it arranges them.

A card is static until setOnPress() is called, which makes it focusable and pressable. An elevated card then rises from elevation level 1 to level 2 while it is held down; the motion is driven by the card's components::Animation, wired by install().

A card whose components::Card records no section keeps the child list its components::Layout already has.

See also
components::Card, entities::Card, systems::Layout

Definition at line 60 of file card.hpp.

Constructor & Destructor Documentation

◆ Card()

guillaume::systems::Card::Card ( void )

Create the system in the Layout phase.

Definition at line 226 of file card.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

Member Function Documentation

◆ apply()

void guillaume::systems::Card::apply ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Style one card and arrange its sections.

This is what update() runs each frame. Call it directly after changing components::Card to see the result before the next frame, which is what the setters of entities::Card do.

The container color and stroke depend on the variant: elevated (tinted surface with a shadow), filled (surfaceVariant) or outlined (surface with a 1 dp outline). An interactive card also blends its hover or press state layer into the container color. The sections are laid out in the order cover, title, content, actions, skipping the ones that do not exist.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe card entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity lacks components::Card, Layout, Color, Borders or Elevation.

Definition at line 341 of file card.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ contentWidth()

float guillaume::systems::Card::contentWidth ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Get the width a section of the card can use, in dp.

entities::Card uses it to size the sections it creates.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe card entity.
Returns
The fixed width of the card's components::Layout minus its padding on both sides, never negative; 0 when the card has no fixed width.

Definition at line 330 of file card.cpp.

Here is the call graph for this function:

◆ install()

void guillaume::systems::Card::install ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Prepare the press-elevation motion of a card.

Sets the duration and easing of the entity's components::Animation from the theme and makes each of its samples move the press progress of components::Card towards its target (1 while pressed, 0 at rest) and call apply(). Call it once, after the entity has its components::Card, Animation, Elevation, Borders, Color, Layout, Transform and Bound.

Parameters
componentRegistryThe registry holding the components. It is captured by the sample handler and must outlive the entity.
entityIdentifierThe card entity.
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the entity has no components::Animation.

Definition at line 231 of file card.cpp.

Here is the call graph for this function:

◆ interactionChanged()

void guillaume::systems::Card::interactionChanged ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

React to a change of the hover or press state of the card.

Called by the interaction components once setOnPress() has made the card interactive. When the pressed state of an elevated card flips, it records the new state and plays the elevation motion from the current press progress. The card is then restyled, so the state layer follows the pointer. Filled and outlined cards have no elevation motion.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe card entity.

Definition at line 292 of file card.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ isDisabled()

bool guillaume::systems::Card::isDisabled ( const ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Whether the card ignores input.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe card entity.
Returns
True when the entity has been disabled, see setDisabled().

Definition at line 324 of file card.cpp.

Here is the caller graph for this function:

◆ press()

void guillaume::systems::Card::press ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier )
static

Activate the card as a click or a key press would.

Calls the press handler of components::Card when there is one. Does nothing when the card is disabled. Use it to trigger the card from code or from a test.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe card entity.

Definition at line 276 of file card.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setDisabled()

void guillaume::systems::Card::setDisabled ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
bool disabled )
static

Enable or disable the card and restyle it.

A disabled card ignores press(). Disabling a card that is held down drops it back to its resting elevation at once, without motion.

Parameters
componentRegistryThe registry holding the components.
entityIdentifierThe card entity.
disabledTrue to disable, false to enable.

Definition at line 310 of file card.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setOnPress()

void guillaume::systems::Card::setOnPress ( ecs::ComponentRegistry & componentRegistry,
const ecs::Entity::Identifier & entityIdentifier,
components::Card::Handler handler )
static

Set the press handler and make the card pressable.

The first call adds the interaction components (hover and press state, focus, the Button accessibility role) and wires an activation to press() and a hover or press change to interactionChanged(). Later calls only replace the handler. The card stays interactive even when the handler is empty. The card is restyled before returning.

Parameters
componentRegistryThe registry holding the components. It is captured by the interaction handlers and must outlive the entity.
entityIdentifierThe card entity.
handlerCalled each time the card is activated; may be empty.

Definition at line 251 of file card.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ update()

void guillaume::systems::Card::update ( const ecs::Entity::Identifier & entityIdentifier)
overridevirtual

Run apply() on one card; called by the frame loop.

Logs a warning and does nothing when the entity has no components::Card.

Parameters
entityIdentifierThe card entity.

Implements guillaume::ecs::System.

Definition at line 396 of file card.cpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files: