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

A plain container whose background gets lighter or darker with its elevation, and which can cast a shadow. More...

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

Inheritance diagram for guillaume::entities::Surface:
Collaboration diagram for guillaume::entities::Surface:

Classes

class  Builder
 Configures and registers Surface widgets. More...

Public Types

enum class  Mode { Flat , Elevated }
 Whether the surface casts a shadow. More...
Public Types inherited from guillaume::entities::SurfaceBase< components::Elevation, components::SurfaceTone >
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

 ~Surface (void) override=default
 Destructor.
Surface & setElevation (theme::ElevationLevel elevation)
 Change the elevation level.
theme::ElevationLevel getElevation (void) const
 Get the elevation level.
Surface & setMode (Mode mode)
 Turn the shadow on or off, and restyle at once.
Mode getMode (void) const
 Tell whether the surface casts a shadow.
Public Member Functions inherited from guillaume::entities::SurfaceBase< components::Elevation, components::SurfaceTone >
 ~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< Surface > create (Arguments &&...arguments)
 Create a surface without registering it.
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.

Additional Inherited Members

Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity
Protected Member Functions inherited from guillaume::entities::SurfaceBase< components::Elevation, components::SurfaceTone >
 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 plain container whose background gets lighter or darker with its elevation, and which can cast a shadow.

Use it to group widgets on a visible panel. Its state lives in components::SurfaceTone (elevation level and whether a shadow is cast). systems::SurfaceTone holds the rule: in the Measure phase of every frame it writes the fill color (the Surface color of the active theme tinted for the level) and the shadow level. Children are arranged by systems::Layout, as for every SurfaceBase.

Surface::Builder builder(getComponentRegistry(), getEntityRegistry());
auto panel = builder.withShape(theme::ShapeRole::Medium)
.makeSurface(nullptr, theme::ElevationLevel::Level2);
panel->setChildren({ title, body });
Configures and registers Surface widgets.
Definition surface.hpp:403
@ Level2
Second raised level.
Definition tokens.hpp:133
@ Medium
12 dp (cards).
Definition tokens.hpp:46

Surface::create(registry, config, elevation, mode) builds the same widget without registering it in an entity registry.

A color set with setColor() does not last: the system recomputes the fill color from the elevation every frame.

See also
components::SurfaceTone, systems::SurfaceTone, SurfaceBase

Definition at line 387 of file surface.hpp.

Member Enumeration Documentation

◆ Mode

Whether the surface casts a shadow.

Enumerator
Flat 

Tinted background, no shadow.

Elevated 

Tinted background and the shadow of the level.

Definition at line 394 of file surface.hpp.

Member Function Documentation

◆ create()

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

Create a surface without registering it.

The constructor is private so that a surface is always owned by a std::shared_ptr, which setChildren() requires. The arguments are those of the constructor: (registry, config, elevation, mode). The caller keeps the surface alive, or hands it to an entity registry; Builder does both steps.

Template Parameters
ArgumentsThe types of the constructor arguments.
Parameters
argumentsThe constructor arguments.
Returns
The new surface, already styled for its elevation.

Definition at line 516 of file surface.hpp.

Here is the caller graph for this function:

◆ getElevation()

theme::ElevationLevel guillaume::entities::Surface::getElevation ( void ) const

Get the elevation level.

Returns
The level stored in components::SurfaceTone. It tints the background even in Mode::Flat.

Definition at line 204 of file surface.cpp.

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

◆ getMode()

Surface::Mode guillaume::entities::Surface::getMode ( void ) const

Tell whether the surface casts a shadow.

Returns
Mode::Elevated when it does, Mode::Flat otherwise.

Definition at line 220 of file surface.cpp.

Here is the call graph for this function:

◆ setElevation()

Surface & guillaume::entities::Surface::setElevation ( theme::ElevationLevel elevation)

Change the elevation level.

Writes components::SurfaceTone and restyles at once: the fill color and, in Mode::Elevated, the shadow follow.

Parameters
elevationThe level, from Level0 to Level5.
Returns
This surface, for chaining.

Definition at line 195 of file surface.cpp.

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

◆ setMode()

Surface & guillaume::entities::Surface::setMode ( Mode mode)

Turn the shadow on or off, and restyle at once.

Parameters
modeElevated for a shadow, Flat for none.
Returns
This surface, for chaining.

Definition at line 211 of file surface.cpp.

Here is the call graph for this function:

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