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

Base of the widgets that are a rectangle containing other widgets (Card, Dialog, Checkbox, ...). More...

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

Inheritance diagram for guillaume::entities::SurfaceBase< ExtraComponents >:
Collaboration diagram for guillaume::entities::SurfaceBase< ExtraComponents >:

Public Types

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

 ~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.

Protected Member Functions

 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.

Additional Inherited Members

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 inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity

Detailed Description

template<ecs::InheritFromComponent... ExtraComponents>
class guillaume::entities::SurfaceBase< ExtraComponents >

Base of the widgets that are a rectangle containing other widgets (Card, Dialog, Checkbox, ...).

It has no component of its own. Its state is the five components it always carries: Transform (pose), Bound (size), Color (fill), Borders (corner radius) and Layout (axis, alignment, spacing, padding, fixed size and the list of children to arrange). systems::Layout holds the rules: in the Layout phase of every frame it positions the children listed in the Layout component and writes the size of the surface in its Bound. The setters of this class write the components and run the same arrangement at once, so the result is visible while a scene is being built.

A widget derives from it and lists its own components in the template pack:

class Checkbox:
public SurfaceBase<components::Selectable, components::Line,
components::Checkbox>
A box the user checks, unchecks or leaves indeterminate, with an optional label next to it.
Definition checkbox.hpp:92
SurfaceBase(ecs::ComponentRegistry &registry, const SurfaceConfig &config)
Create the entity with its components and apply a configuration.

Watch out for:

  • Only the children given to setChildren() are arranged. A child attached with ecs::Entity::setParent() alone keeps the position its own code gives it.
  • The size of the surface (Bound) is overwritten every frame from its children, its padding and its fixed size.
  • setChildren() needs the surface to be owned by a std::shared_ptr, which is the case for every widget built with create() or a Builder.
Template Parameters
ExtraComponentsThe components the derived widget adds to the five common ones.
See also
SurfaceConfig, components::Layout, systems::Layout

Definition at line 238 of file surface.hpp.

Member Typedef Documentation

◆ Children

template<ecs::InheritFromComponent... ExtraComponents>
using guillaume::entities::SurfaceBase< ExtraComponents >::Children
Initial value:
std::vector<std::shared_ptr<ecs::Entity>>

List of child entities.

Definition at line 245 of file surface.hpp.

Constructor & Destructor Documentation

◆ SurfaceBase()

template<ecs::InheritFromComponent... ExtraComponents>
guillaume::entities::SurfaceBase< ExtraComponents >::SurfaceBase ( ecs::ComponentRegistry & registry,
const SurfaceConfig & config )
protected

Create the entity with its components and apply a configuration.

Parameters
registryThe registry that stores the components.
configThe initial configuration, applied with setSurfaceConfig().
Here is the caller graph for this function:

Member Function Documentation

◆ applyGeometry()

template<ecs::InheritFromComponent... ExtraComponents>
void guillaume::entities::SurfaceBase< ExtraComponents >::applyGeometry ( void )
protected

Arrange the layout children now with systems::Layout::apply.

The Layout system does the same every frame. Calling it from a setter makes the new positions and the new size of the surface available immediately, before the first frame.

◆ getChildren()

template<ecs::InheritFromComponent... ExtraComponents>
std::vector< ecs::Entity::Identifier > guillaume::entities::SurfaceBase< ExtraComponents >::getChildren ( void ) const

Get the children this surface arranges.

Returns
The identifiers recorded in the Layout component, in layout order. Empty when setChildren() was never called. Children attached without setChildren() are not listed.

◆ getSurfaceConfig()

template<ecs::InheritFromComponent... ExtraComponents>
SurfaceConfig guillaume::entities::SurfaceBase< ExtraComponents >::getSurfaceConfig ( void ) const

Read the current configuration back from the components.

The surface keeps no copy of the configuration it was given: the value is rebuilt from the Transform, Color, Borders and Layout components, so it reflects changes made through them. The corner radius reported is the top-left one.

Returns
The configuration matching the current components.

◆ setBorderRadius()

template<ecs::InheritFromComponent... ExtraComponents>
SurfaceBase & guillaume::entities::SurfaceBase< ExtraComponents >::setBorderRadius ( float radius)

Set the radius of the four corners (Borders component).

Parameters
radiusThe radius, in dp.
Returns
This surface, for chaining.
Here is the call graph for this function:

◆ setChildren()

template<ecs::InheritFromComponent... ExtraComponents>
SurfaceBase & guillaume::entities::SurfaceBase< ExtraComponents >::setChildren ( const Children & children)

Choose the children this surface arranges, in order.

Each child becomes a child entity of the surface and its identifier is recorded in the Layout component, replacing the previous list. The children are arranged at once. Null pointers and entities without a valid identifier are skipped. The surface does not keep the children alive: each one must be owned by an entity registry, which is the case when it was created by a Builder.

Parameters
childrenThe children, in layout order (left to right or top to bottom).
Returns
This surface, for chaining.
Here is the call graph for this function:

◆ setColor()

template<ecs::InheritFromComponent... ExtraComponents>
SurfaceBase & guillaume::entities::SurfaceBase< ExtraComponents >::setColor ( const utility::graphic::Color32Bit & color)

Set the fill color (Color component).

Widgets whose system computes the color from the theme (Surface, Checkbox, ...) overwrite it on their next restyle.

Parameters
colorThe new fill color.
Returns
This surface, for chaining.
Here is the call graph for this function:

◆ setPose()

template<ecs::InheritFromComponent... ExtraComponents>
SurfaceBase & guillaume::entities::SurfaceBase< ExtraComponents >::setPose ( const utility::graphic::PoseF & pose)

Move the surface.

Writes the Transform component, then arranges the layout children again so they follow.

Parameters
poseThe new position and orientation.
Returns
This surface, for chaining.
Here is the call graph for this function:

◆ setSurfaceConfig()

template<ecs::InheritFromComponent... ExtraComponents>
SurfaceBase & guillaume::entities::SurfaceBase< ExtraComponents >::setSurfaceConfig ( const SurfaceConfig & config)

Apply every field of a configuration at once.

Writes the Transform, Color, Borders and Layout components. A fixed width or height that the configuration does not have is cleared. The list of layout children is kept, and the children are arranged again at once.

Parameters
configThe configuration to copy into the components.
Returns
This surface, for chaining.
Here is the call graph for this function:

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