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

State of a card: a surface grouping an optional cover image, title, text and row of action buttons. More...

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

Inheritance diagram for guillaume::components::Card:
Collaboration diagram for guillaume::components::Card:

Classes

struct  Action
 One button of the actions row: its label and what it does. More...

Public Types

enum class  Variant { Elevated , Filled , Outlined }
 Look of the card surface. More...
using Handler = std::function<void(void)>
 Callback run when the card is pressed.
using Identifiers = std::vector<ecs::Entity::Identifier>
 List of child entity identifiers.

Public Member Functions

 Card (void)=default
 Create the state of an empty, elevated card that cannot be pressed.
 ~Card (void)=default
 Default destructor.
Variant getVariant (void) const noexcept
 Get the look of the card surface.
Card & setVariant (Variant variant)
 Choose the look of the card surface.
bool isInteractive (void) const noexcept
 Check whether the card reacts to hover and press.
Card & setInteractive (bool interactive)
 Record that the card reacts to hover and press.
bool isPressed (void) const noexcept
 Check whether the press motion is heading to the raised state.
Card & setPressed (bool pressed)
 Record the pressed state the press motion heads to.
float getPressProgress (void) const noexcept
 Get how far the card is raised by a press.
Card & setPressProgress (float pressProgress)
 Set how far the card is raised by a press.
float getPressFrom (void) const noexcept
 Get the press progress at which the running motion began.
Card & setPressFrom (float pressFrom)
 Record the press progress at which a motion begins.
const std::string & getCoverPath (void) const noexcept
 Get the path of the cover texture.
Card & setCoverPath (const std::string &coverPath)
 Set the path of the cover texture.
const std::string & getTitle (void) const noexcept
 Get the title text.
Card & setTitle (const std::string &title)
 Set the title text.
const std::string & getSubtitle (void) const noexcept
 Get the subtitle text.
Card & setSubtitle (const std::string &subtitle)
 Set the subtitle text.
const std::string & getContentText (void) const noexcept
 Get the content text.
Card & setContentText (const std::string &contentText)
 Set the content text.
ecs::Entity::Identifier getCover (void) const noexcept
 Get the child entity that draws the cover image.
Card & setCover (ecs::Entity::Identifier identifier)
 Record which child entity draws the cover image.
ecs::Entity::Identifier getTitleSection (void) const noexcept
 Get the child entity that contains the title and the subtitle.
Card & setTitleSection (ecs::Entity::Identifier identifier)
 Record which child entity contains the title and the subtitle.
ecs::Entity::Identifier getTitleText (void) const noexcept
 Get the entity that draws the title text.
Card & setTitleText (ecs::Entity::Identifier identifier)
 Record which entity draws the title text.
ecs::Entity::Identifier getSubtitleText (void) const noexcept
 Get the entity that draws the subtitle text.
Card & setSubtitleText (ecs::Entity::Identifier identifier)
 Record which entity draws the subtitle text.
ecs::Entity::Identifier getContentEntity (void) const noexcept
 Get the child entity that draws the content text.
Card & setContentEntity (ecs::Entity::Identifier identifier)
 Record which child entity draws the content text.
ecs::Entity::Identifier getActionsSection (void) const noexcept
 Get the child entity that contains the action buttons.
Card & setActionsSection (ecs::Entity::Identifier identifier)
 Record which child entity contains the action buttons.
const std::vector< Action > & getActions (void) const noexcept
 Get the actions the card was asked to show.
Card & addAction (Action action)
 Append an action to the actions row.
const Identifiers & getActionButtons (void) const noexcept
 Get the entities of the action buttons.
Card & setActionButtons (const Identifiers &identifiers)
 Record which entities are the action buttons.
const Handler & getOnPress (void) const noexcept
 Get the callback run when the card is pressed.
Card & setOnPress (Handler handler)
 Store the callback run when the card is pressed.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Static Public Attributes

static constexpr float CoverHeight = 195.0f
 Height of the cover image, in dp.
static constexpr float TitleMinHeight = 72.0f
 Minimum height of the title section, in dp.

Detailed Description

State of a card: a surface grouping an optional cover image, title, text and row of action buttons.

It holds the variant, the content (cover path, title, subtitle, text, actions), the identifiers of the children that draw that content, the press callback and the progress of the press motion. Whether the card is enabled lives in the components::StyleState of the same entity.

Role in the frame:

  • entities::Card writes the content, creates the children and records their identifiers here.
  • systems::Card (Layout phase) reads it and writes the card's Color, Borders and Elevation, copies the texts and the cover path to the children, and stacks the sections top to bottom: cover, title, content, actions. On input it writes the pressed flag and, through the entity's components::Animation, the press progress.

Watch out:

  • To make a card pressable call systems::Card::setOnPress(), not the setter here: only the system wires the input.
  • The press fields (pressed, press progress, press from) belong to systems::Card and are overwritten while the motion runs.

Unless a member says otherwise, a setter compares before writing and marks the component changed only when the value differs.

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

Definition at line 64 of file card.hpp.

Member Typedef Documentation

◆ Handler

using guillaume::components::Card::Handler = std::function<void(void)>

Callback run when the card is pressed.

Definition at line 88 of file card.hpp.

◆ Identifiers

List of child entity identifiers.

Definition at line 91 of file card.hpp.

Member Enumeration Documentation

◆ Variant

Look of the card surface.

Enumerator
Elevated 

Tonal level-1 surface with a shadow; rises to level 2 while pressed.

Filled 

Surface-variant fill, no shadow, no outline.

Outlined 

Surface fill with a 1 dp outline-variant stroke.

Definition at line 70 of file card.hpp.

Member Function Documentation

◆ addAction()

Card & guillaume::components::Card::addAction ( Action action)

Append an action to the actions row.

Always marks the component changed. The widget class creates the button of each action from this list.

Parameters
actionThe label and the click handler of the new button.
Returns
This component, for chaining.

Definition at line 244 of file card.cpp.

Here is the call graph for this function:

◆ getActionButtons()

const Card::Identifiers & guillaume::components::Card::getActionButtons ( void ) const
noexcept

Get the entities of the action buttons.

Returns
Their identifiers, in action order.

Definition at line 251 of file card.cpp.

◆ getActions()

const std::vector< Card::Action > & guillaume::components::Card::getActions ( void ) const
noexcept

Get the actions the card was asked to show.

Returns
The actions, in the order they were added.

Definition at line 239 of file card.cpp.

◆ getActionsSection()

ecs::Entity::Identifier guillaume::components::Card::getActionsSection ( void ) const
noexcept

Get the child entity that contains the action buttons.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the card has no actions row.

Definition at line 225 of file card.cpp.

◆ getContentEntity()

ecs::Entity::Identifier guillaume::components::Card::getContentEntity ( void ) const
noexcept

Get the child entity that draws the content text.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the card has no content text.

Definition at line 211 of file card.cpp.

◆ getContentText()

const std::string & guillaume::components::Card::getContentText ( void ) const
noexcept

Get the content text.

Returns
The text, empty when the card has no content text.

Definition at line 141 of file card.cpp.

◆ getCover()

ecs::Entity::Identifier guillaume::components::Card::getCover ( void ) const
noexcept

Get the child entity that draws the cover image.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the card has no cover.

Definition at line 155 of file card.cpp.

◆ getCoverPath()

const std::string & guillaume::components::Card::getCoverPath ( void ) const
noexcept

Get the path of the cover texture.

Returns
The path, empty when the card has no cover.

Definition at line 99 of file card.cpp.

◆ getOnPress()

const Card::Handler & guillaume::components::Card::getOnPress ( void ) const
noexcept

Get the callback run when the card is pressed.

Returns
The callback, empty when none is set.

Definition at line 265 of file card.cpp.

◆ getPressFrom()

float guillaume::components::Card::getPressFrom ( void ) const
noexcept

Get the press progress at which the running motion began.

Returns
The starting progress, 0 to 1.

Definition at line 85 of file card.cpp.

◆ getPressProgress()

float guillaume::components::Card::getPressProgress ( void ) const
noexcept

Get how far the card is raised by a press.

Returns
The progress, 0 at rest to 1 fully pressed.

Definition at line 71 of file card.cpp.

◆ getSubtitle()

const std::string & guillaume::components::Card::getSubtitle ( void ) const
noexcept

Get the subtitle text.

Returns
The text, empty when the card has no subtitle.

Definition at line 127 of file card.cpp.

◆ getSubtitleText()

ecs::Entity::Identifier guillaume::components::Card::getSubtitleText ( void ) const
noexcept

Get the entity that draws the subtitle text.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the card has no subtitle.

Definition at line 197 of file card.cpp.

◆ getTitle()

const std::string & guillaume::components::Card::getTitle ( void ) const
noexcept

Get the title text.

Returns
The text, empty when the card has no title.

Definition at line 113 of file card.cpp.

◆ getTitleSection()

ecs::Entity::Identifier guillaume::components::Card::getTitleSection ( void ) const
noexcept

Get the child entity that contains the title and the subtitle.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the card has no title section.

Definition at line 169 of file card.cpp.

◆ getTitleText()

ecs::Entity::Identifier guillaume::components::Card::getTitleText ( void ) const
noexcept

Get the entity that draws the title text.

Returns
Its identifier, or ecs::Entity::InvalidIdentifier when the card has no title.

Definition at line 183 of file card.cpp.

◆ getVariant()

Card::Variant guillaume::components::Card::getVariant ( void ) const
noexcept

Get the look of the card surface.

Returns
The variant (Elevated by default).

Definition at line 29 of file card.cpp.

Here is the caller graph for this function:

◆ isInteractive()

bool guillaume::components::Card::isInteractive ( void ) const
noexcept

Check whether the card reacts to hover and press.

Returns
True once systems::Card::setOnPress() wired the input.

Definition at line 43 of file card.cpp.

◆ isPressed()

bool guillaume::components::Card::isPressed ( void ) const
noexcept

Check whether the press motion is heading to the raised state.

Returns
True while an elevated card is held down.

Definition at line 57 of file card.cpp.

Here is the caller graph for this function:

◆ setActionButtons()

Card & guillaume::components::Card::setActionButtons ( const Identifiers & identifiers)

Record which entities are the action buttons.

The system arranges them inside the actions row.

Parameters
identifiersTheir identifiers, in action order.
Returns
This component, for chaining.

Definition at line 256 of file card.cpp.

Here is the call graph for this function:

◆ setActionsSection()

Card & guillaume::components::Card::setActionsSection ( ecs::Entity::Identifier identifier)

Record which child entity contains the action buttons.

Parameters
identifierThe actions row child, or ecs::Entity::InvalidIdentifier for none.
Returns
This component, for chaining.

Definition at line 230 of file card.cpp.

Here is the call graph for this function:

◆ setContentEntity()

Card & guillaume::components::Card::setContentEntity ( ecs::Entity::Identifier identifier)

Record which child entity draws the content text.

Parameters
identifierThe content text child, or ecs::Entity::InvalidIdentifier for none.
Returns
This component, for chaining.

Definition at line 216 of file card.cpp.

Here is the call graph for this function:

◆ setContentText()

Card & guillaume::components::Card::setContentText ( const std::string & contentText)

Set the content text.

The system copies it to the content text child.

Parameters
contentTextThe body text of the card.
Returns
This component, for chaining.

Definition at line 146 of file card.cpp.

Here is the call graph for this function:

◆ setCover()

Card & guillaume::components::Card::setCover ( ecs::Entity::Identifier identifier)

Record which child entity draws the cover image.

Parameters
identifierThe cover child, or ecs::Entity::InvalidIdentifier for none.
Returns
This component, for chaining.

Definition at line 160 of file card.cpp.

Here is the call graph for this function:

◆ setCoverPath()

Card & guillaume::components::Card::setCoverPath ( const std::string & coverPath)

Set the path of the cover texture.

The system copies it to the Image of the cover child.

Parameters
coverPathThe path of the image file.
Returns
This component, for chaining.

Definition at line 104 of file card.cpp.

Here is the call graph for this function:

◆ setInteractive()

Card & guillaume::components::Card::setInteractive ( bool interactive)

Record that the card reacts to hover and press.

An interactive card blends the hover and press state layers over its container color. Written by systems::Card::setOnPress(); the flag alone does not wire any input.

Parameters
interactiveTrue when the input is wired.
Returns
This component, for chaining.

Definition at line 48 of file card.cpp.

Here is the call graph for this function:

◆ setOnPress()

Card & guillaume::components::Card::setOnPress ( Handler handler)

Store the callback run when the card is pressed.

It only stores the callback and does not mark the component changed. Use systems::Card::setOnPress() so the card also starts reacting to input.

Parameters
handlerThe callback, or an empty one to remove it.
Returns
This component, for chaining.

Definition at line 270 of file card.cpp.

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

◆ setPressed()

Card & guillaume::components::Card::setPressed ( bool pressed)

Record the pressed state the press motion heads to.

Written by systems::Card when the input changes; only an Elevated card is ever recorded as pressed.

Parameters
pressedTrue when the card is held down.
Returns
This component, for chaining.

Definition at line 62 of file card.cpp.

Here is the call graph for this function:

◆ setPressFrom()

Card & guillaume::components::Card::setPressFrom ( float pressFrom)

Record the press progress at which a motion begins.

Written by systems::Card when the pressed state flips, so a press released half-way animates back from where it was.

Parameters
pressFromThe starting progress, 0 to 1.
Returns
This component, for chaining.

Definition at line 90 of file card.cpp.

Here is the call graph for this function:

◆ setPressProgress()

Card & guillaume::components::Card::setPressProgress ( float pressProgress)

Set how far the card is raised by a press.

Written by systems::Card on each sample of the press animation. An Elevated card blends its surface tone and shadow between elevation levels 1 and 2 by this amount.

Parameters
pressProgressThe progress, 0 at rest to 1 fully pressed.
Returns
This component, for chaining.

Definition at line 76 of file card.cpp.

Here is the call graph for this function:

◆ setSubtitle()

Card & guillaume::components::Card::setSubtitle ( const std::string & subtitle)

Set the subtitle text.

The system copies it to the subtitle text child.

Parameters
subtitleThe subtitle text, shown under the title.
Returns
This component, for chaining.

Definition at line 132 of file card.cpp.

Here is the call graph for this function:

◆ setSubtitleText()

Card & guillaume::components::Card::setSubtitleText ( ecs::Entity::Identifier identifier)

Record which entity draws the subtitle text.

Parameters
identifierThe subtitle text entity, a child of the title section, or ecs::Entity::InvalidIdentifier for none.
Returns
This component, for chaining.

Definition at line 202 of file card.cpp.

Here is the call graph for this function:

◆ setTitle()

Card & guillaume::components::Card::setTitle ( const std::string & title)

Set the title text.

The system copies it to the title text child and to the Accessibility label of the title section.

Parameters
titleThe title text.
Returns
This component, for chaining.

Definition at line 118 of file card.cpp.

Here is the call graph for this function:

◆ setTitleSection()

Card & guillaume::components::Card::setTitleSection ( ecs::Entity::Identifier identifier)

Record which child entity contains the title and the subtitle.

Parameters
identifierThe title section child, or ecs::Entity::InvalidIdentifier for none.
Returns
This component, for chaining.

Definition at line 174 of file card.cpp.

Here is the call graph for this function:

◆ setTitleText()

Card & guillaume::components::Card::setTitleText ( ecs::Entity::Identifier identifier)

Record which entity draws the title text.

Parameters
identifierThe title text entity, a child of the title section, or ecs::Entity::InvalidIdentifier for none.
Returns
This component, for chaining.

Definition at line 188 of file card.cpp.

Here is the call graph for this function:

◆ setVariant()

Card & guillaume::components::Card::setVariant ( Variant variant)

Choose the look of the card surface.

Parameters
variantElevated, Filled or Outlined.
Returns
This component, for chaining.

Definition at line 34 of file card.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ CoverHeight

float guillaume::components::Card::CoverHeight = 195.0f
staticconstexpr

Height of the cover image, in dp.

Definition at line 96 of file card.hpp.

◆ TitleMinHeight

float guillaume::components::Card::TitleMinHeight = 72.0f
staticconstexpr

Minimum height of the title section, in dp.

Definition at line 101 of file card.hpp.


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