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

A rounded panel grouping a cover image, a title, a text and action buttons about one subject (react-native-paper Card). More...

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

Inheritance diagram for guillaume::entities::Card:
Collaboration diagram for guillaume::entities::Card:

Classes

class  Builder
 Configures Card widgets and registers them in the scene's entity registry. More...

Public Types

using Variant = components::Card::Variant
 Look of the card: Elevated, Filled or Outlined.
Public Types inherited from guillaume::entities::SurfaceBase< components::Elevation, components::Animation, components::Card >
using Children
Public Types inherited from guillaume::ecs::Entity
using Identifier = std::size_t
 The key under which an entity's components are stored. Systems and components refer to entities by this value.
using Signature = std::bitset<128>
 A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits).

Public Member Functions

 ~Card (void) override
 Destructor.
Card & setVariant (Variant variant)
 Change the look of the card. Restyles at once.
Variant getVariant (void) const
 Get the look of the card.
Card & setOnPress (std::function< void(void)> onPress)
 Make the card pressable and set what a press does (Paper onPress).
bool isInteractive (void) const
 Check whether the card reacts to input.
Card & setDisabled (bool disabled)
 Disable or enable the card (Paper disabled). Restyles at once.
bool isDisabled (void) const
 Check whether the card ignores presses.
Card & setCover (const std::string &texturePath)
 Show an image at the top of the card (Paper Card.Cover).
Card & setTitle (const std::string &title, const std::string &subtitle="")
 Show a title, and optionally a subtitle under it (Paper Card.Title).
Card & setContent (const std::string &content)
 Show a text under the title (Paper Card.Content).
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).
std::shared_ptr< Image > getCover (void) const
 Get the cover image.
std::shared_ptr< ecs::Entity > getTitleSection (void) const
 Get the section holding the title and subtitle texts.
std::shared_ptr< Text > getContent (void) const
 Get the content text.
std::shared_ptr< ecs::Entity > getActionsSection (void) const
 Get the row holding the action buttons.
std::vector< std::shared_ptr< Button > > getActions (void) const
 Get the action buttons.
float getPressProgress (void) const
 Get how far the press elevation has progressed.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Elevation, components::Animation, components::Card >
 ~SurfaceBase (void) override=default
 Default destructor.
SurfaceBase & setPose (const utility::graphic::PoseF &pose)
 Move the surface.
SurfaceBase & setColor (const utility::graphic::Color32Bit &color)
 Set the fill color (Color component).
SurfaceBase & setBorderRadius (float radius)
 Set the radius of the four corners (Borders component).
SurfaceBase & setSurfaceConfig (const SurfaceConfig &config)
 Apply every field of a configuration at once.
SurfaceConfig getSurfaceConfig (void) const
 Read the current configuration back from the components.
SurfaceBase & setChildren (const Children &children)
 Choose the children this surface arranges, in order.
std::vector< ecs::Entity::Identifier > getChildren (void) const
 Get the children this surface arranges.
Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
 ParentEntityFiller (ComponentRegistry &componentRegistry)
 Create the entity, its listed components and its components::Hierarchy. It owns no child yet.
virtual ~ParentEntityFiller (void)=default
 Destroy the entity object and release the children it owns; components stay in the registry (see EntityRegistry::removeEntity).
Public Member Functions inherited from guillaume::ecs::Entity
 Entity (void)
 Create an entity with a fresh identifier, an empty signature, no parent and no component.
virtual ~Entity (void)=default
 Destroy the entity object.
Entity::Identifier getIdentifier (void) const noexcept
 Get the identifier of the entity.
Entity::Signature getSignature (void) const noexcept
 Get the set of component types the entity declares.
void setSignature (const Signature &signature)
 Replace the signature of the entity.
std::int32_t getLayer (void) const noexcept
 Get the depth of the entity in the tree.
Entity & setParent (std::shared_ptr< Entity > parent)
 Attach the entity under another one, or detach it.
std::vector< Identifier > releaseComponents (void)
 Drop the entity's place in the tree and all its components.
std::shared_ptr< Entity > getParent (void) const noexcept
 Get the parent entity.
Public Member Functions inherited from guillaume::ecs::EntityRegistry
 EntityRegistry (void)=default
 Create a registry.
virtual ~EntityRegistry (void)=default
 Virtual destructor.
void addEntity (std::shared_ptr< Entity > entity)
 Make this registry own an entity, so that it stays alive and systems visit it.
bool removeEntity (Entity::Identifier identifier)
 Remove an entity, with its children and all their components.
void clearEntities (void)
 Remove every entity owned by this registry, with everything they own and all their components.
const std::vector< std::shared_ptr< Entity > > & getEntities (void) const
 Get the entities this registry owns directly.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void)
 List every entity of this registry and of the registries nested in it, level by level.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void) const
 List every entity of this registry and of the registries nested in it, level by level (const overload).
template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > getEntity (Entity::Identifier identifier)
 Find an entity owned directly by this registry, by identifier.
template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > getEntity (Entity::Identifier identifier) const
 Find an entity owned directly by this registry, by identifier (const overload).
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature) const
 List the entities that have every component type of a signature, from the root down.
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const
 List the entities that have every component type of a signature, in the order chosen by a traveler.

Static Public Member Functions

template<typename... Arguments>
static std::shared_ptr< Card > create (Arguments &&...arguments)
 Build a card without registering it in an entity registry.
Static Public Member Functions inherited from guillaume::ecs::Entity
template<InheritFromComponent... ComponentTypes>
static Signature getSignatureFromTypes (void)
 Build the signature that has exactly the bits of the given component types.

Static Public Attributes

static constexpr float CoverHeight = components::Card::CoverHeight
 Height given to the cover image, in dp (Paper Card.Cover: 195).
static constexpr float TitleMinHeight
 Height given to the title section, in dp (the minimum height of Paper Card.Title: 72).
Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity

Additional Inherited Members

Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::Elevation, components::Animation, components::Card >
 SurfaceBase (ecs::ComponentRegistry &registry, const SurfaceConfig &config)
 Create the entity with its components and apply a configuration.
void applyGeometry (void)
 Arrange the layout children now with systems::Layout::apply.
Protected Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders, ExtraComponents... >
ComponentRegistry & getComponentRegistry (void)
 Get the registry that stores this entity's components.
Protected Member Functions inherited from guillaume::ecs::ParentEntity
std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) override
 Give access to the list of entities this entity owns directly.
const std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) const override
 Give read access to the list of entities this entity owns directly.
Protected Member Functions inherited from guillaume::ecs::Entity
void attachHierarchy (ComponentRegistry &componentRegistry)
 Give the entity a components::Hierarchy in a registry and add that component to its signature.
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.

Detailed Description

A rounded panel grouping a cover image, a title, a text and action buttons about one subject (react-native-paper Card).

Its state lives in components::Card (variant, press handler, texts of the sections and identifiers of their entities); systems::Card styles the panel, runs its press elevation and arranges its sections each frame, in the Layout phase. The class itself holds no field: its setters write the component, create the child entities a section needs, and restyle at once.

The variant chooses the look:

  • Elevated (default): tinted surface with a level 1 shadow, raised to level 2 while pressed.
  • Filled: SurfaceVariant color, no shadow (Paper contained).
  • Outlined: Surface color with a 1 dp OutlineVariant stroke.
Card::Builder builder(getComponentRegistry(), getEntityRegistry());
auto card = builder.withWidth(320.0f).makeCard(parent,
Card::Variant::Elevated);
card->setCover("images/mountain.png");
card->setTitle("Mont Blanc", "4806 m");
card->setContent("The highest summit of the Alps.");
card->addAction("Share", [] {
// called when the user presses the button
});
Configures Card widgets and registers them in the scene's entity registry.
Definition card.hpp:128

Card::create(registry, config, variant) builds the same widget without registering it in an entity registry.

Watch out:

  • The sections are always laid out in the order cover, title, content, actions, whatever the order of the calls. Once one exists, the sections replace any layout children given with setChildren().
  • A section takes the inner width of the card (fixed width minus padding) when it is first created. Set the width with the builder before composing; a card without a fixed width gives its cover no size.
  • The first call that gives a section a non-empty value creates its entities; later calls only change their text. A subtitle shows only if the first non-empty title came with one.
  • The card owns its cover, title section, content text and actions row; the actions row owns the buttons.
  • A card reacts to input only after setOnPress(), and cannot be made passive again.
  • systems::Card overwrites the fill color, the stroke and the elevation every frame; SurfaceBase::setColor() does not last. The corner radius is kept.
See also
components::Card, systems::Card, SurfaceBase

Definition at line 102 of file card.hpp.

Member Typedef Documentation

◆ Variant

Look of the card: Elevated, Filled or Outlined.

Definition at line 108 of file card.hpp.

Constructor & Destructor Documentation

◆ ~Card()

guillaume::entities::Card::~Card ( void )
override

Destructor.

Definition at line 164 of file card.cpp.

Member Function Documentation

◆ addAction()

Card & guillaume::entities::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).

The first call creates the row, which aligns its buttons to the end. Each call builds one Button with the Button::Color::Text style. An action cannot be removed.

Parameters
labelThe label of the button.
onPressThe function called when the user presses the button.
Returns
Reference to this card for chaining.

Definition at line 245 of file card.cpp.

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

◆ create()

template<typename... Arguments>
std::shared_ptr< Card > guillaume::entities::Card::create ( Arguments &&... arguments)
inlinestatic

Build a card without registering it in an entity registry.

The arguments are forwarded to the private constructor: (registry, config, variant). It then calls build(). A new card has no section yet, so no child is created at this point: the sections are built by setCover(), setTitle(), setContent() and addAction().

Template Parameters
ArgumentsThe constructor argument types.
Parameters
argumentsThe constructor arguments, as listed above.
Returns
The new card. The caller owns it.

Definition at line 250 of file card.hpp.

Here is the caller graph for this function:

◆ getActions()

std::vector< std::shared_ptr< Button > > guillaume::entities::Card::getActions ( void ) const

Get the action buttons.

The card keeps no list of them: the buttons are resolved from the identifiers recorded in components::Card on every call.

Returns
The buttons, in the order they were added. Empty when the card has no action.

Definition at line 292 of file card.cpp.

Here is the call graph for this function:

◆ getActionsSection()

std::shared_ptr< ecs::Entity > guillaume::entities::Card::getActionsSection ( void ) const

Get the row holding the action buttons.

Returns
The row entity, or nullptr before the first addAction().

Definition at line 284 of file card.cpp.

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

◆ getContent()

std::shared_ptr< Text > guillaume::entities::Card::getContent ( void ) const

Get the content text.

Returns
The Text child, or nullptr before setContent() created it.

Definition at line 276 of file card.cpp.

Here is the call graph for this function:

◆ getCover()

std::shared_ptr< Image > guillaume::entities::Card::getCover ( void ) const

Get the cover image.

Returns
The Image child, or nullptr before setCover() created it.

Definition at line 257 of file card.cpp.

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

◆ getPressProgress()

float guillaume::entities::Card::getPressProgress ( void ) const

Get how far the press elevation has progressed.

Only an Elevated card animates it, over 150 ms.

Returns
The progress, from 0 (at rest, level 1) to 1 (pressed, level 2).

Definition at line 313 of file card.cpp.

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

◆ getTitleSection()

std::shared_ptr< ecs::Entity > guillaume::entities::Card::getTitleSection ( void ) const

Get the section holding the title and subtitle texts.

Returns
The section entity, or nullptr before setTitle() created it.

Definition at line 268 of file card.cpp.

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

◆ getVariant()

Card::Variant guillaume::entities::Card::getVariant ( void ) const

Get the look of the card.

Returns
The variant stored in components::Card.

Definition at line 177 of file card.cpp.

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

◆ isDisabled()

bool guillaume::entities::Card::isDisabled ( void ) const

Check whether the card ignores presses.

Returns
True after setDisabled(true). A new card is enabled.

Definition at line 205 of file card.cpp.

Here is the call graph for this function:

◆ isInteractive()

bool guillaume::entities::Card::isInteractive ( void ) const

Check whether the card reacts to input.

Returns
True once setOnPress() was called, even with an empty function, and whether or not the card is disabled.

Definition at line 191 of file card.cpp.

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

◆ setContent()

Card & guillaume::entities::Card::setContent ( const std::string & content)

Show a text under the title (Paper Card.Content).

The first call with a non-empty text creates the Text child. Later calls change its content.

Parameters
contentThe text, drawn on one line with the BodyMedium role.
Returns
Reference to this card for chaining.

Definition at line 234 of file card.cpp.

Here is the call graph for this function:

◆ setCover()

Card & guillaume::entities::Card::setCover ( const std::string & texturePath)

Show an image at the top of the card (Paper Card.Cover).

The first call with a non-empty path creates the Image child, CoverHeight high and as wide as the inside of the card. Later calls change its texture.

Parameters
texturePathThe path of the texture file to draw.
Returns
Reference to this card for chaining.

Definition at line 211 of file card.cpp.

Here is the call graph for this function:

◆ setDisabled()

Card & guillaume::entities::Card::setDisabled ( bool disabled)

Disable or enable the card (Paper disabled). Restyles at once.

A disabled card does not call its press handler. Disabling a pressed card drops its elevation back to rest.

Parameters
disabledTrue to disable the card, false to enable it.
Returns
Reference to this card for chaining.

Definition at line 198 of file card.cpp.

Here is the call graph for this function:

◆ setOnPress()

Card & guillaume::entities::Card::setOnPress ( std::function< void(void)> onPress)

Make the card pressable and set what a press does (Paper onPress).

The first call adds the interaction components to the card: hover and press state layers, focus and the Button accessibility role. Later calls only replace the handler.

Parameters
onPressThe function called when the user presses the card. An empty function keeps the card interactive but does nothing on press.
Returns
Reference to this card for chaining.

Definition at line 184 of file card.cpp.

Here is the call graph for this function:

◆ setTitle()

Card & guillaume::entities::Card::setTitle ( const std::string & title,
const std::string & subtitle = "" )

Show a title, and optionally a subtitle under it (Paper Card.Title).

The first call with a non-empty title creates the title section (TitleMinHeight high) and its Text children; the subtitle child is created only when subtitle is not empty in that call. Later calls change the text of the existing children.

Parameters
titleThe title, drawn with the BodyLarge role. It is also the accessibility label of the section.
subtitleThe subtitle, drawn with the BodyMedium role. Empty by default.
Returns
Reference to this card for chaining.

Definition at line 222 of file card.cpp.

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

◆ setVariant()

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

Change the look of the card. Restyles at once.

Parameters
variantElevated, Filled or Outlined.
Returns
Reference to this card for chaining.

Definition at line 168 of file card.cpp.

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

Member Data Documentation

◆ CoverHeight

float guillaume::entities::Card::CoverHeight = components::Card::CoverHeight
staticconstexpr

Height given to the cover image, in dp (Paper Card.Cover: 195).

Definition at line 114 of file card.hpp.

◆ TitleMinHeight

float guillaume::entities::Card::TitleMinHeight
staticconstexpr
Initial value:
=
static constexpr float TitleMinHeight
Minimum height of the title section, in dp.
Definition card.hpp:101

Height given to the title section, in dp (the minimum height of Paper Card.Title: 72).

Definition at line 120 of file card.hpp.


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