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

Arranges the children of a container in a row or a column and sizes the container around them. More...

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

Inheritance diagram for guillaume::systems::Layout:
Collaboration diagram for guillaume::systems::Layout:

Public Member Functions

 Layout (void)
 Create the system in the Layout phase.
 ~Layout (void) override=default
 Destroy the system. It owns no resource.
void update (const ecs::Entity::Identifier &entityIdentifier) override
 Arrange the children listed in the components::Layout of one container, using the layer of its components::Hierarchy.
Public Member Functions inherited from guillaume::ecs::SystemFiller< components::Layout, components::Transform, components::Bound >
 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 apply (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, std::uint32_t layer=0)
 Arrange children inside a container and size the container.
static std::uint32_t layerOf (const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
 Get the layer of an entity: its depth in the entity tree.
static const utility::graphic::PoseF applyLayerToPosition (const utility::graphic::PositionF &position, const utility::graphic::OrientationF &orientation, const std::uint32_t &layer)
 Move a position in front of a container.
static const utility::graphic::PoseF contentLayerPose (const utility::graphic::PositionF &position, const utility::graphic::OrientationF &orientation, const std::uint32_t &containerLayer)
 Compute the pose of content placed by hand on a container.

Static Public Attributes

static constexpr float LayerDepthStep = 1.0f
 Depth of one layer: the distance a child is moved towards the viewer, against the forward axis of its container, for each layer.
static constexpr std::uint32_t ContentLayerOffset = 1
 Number of layers added between a container and what is placed on it.

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

Arranges the children of a container in a row or a column and sizes the container around them.

Runs in the Layout phase on every entity that has Layout, Transform and Bound.

The children arranged are the ones listed in components::Layout::getChildren, in that order. A child of the entity tree that is not in the list (a switch thumb, a label placed by its widget system) keeps the pose its owner gave it.

The rules live in the static apply(), so a widget system can arrange a container at once instead of waiting for the frame:

const auto &layout =
registry.getComponent<components::Layout>(container);
systems::Layout::apply(registry, container, layout.getChildren(),
systems::Layout::layerOf(registry, container));
How a container arranges its children: in a row or a column, with which alignment,...
Definition layout.hpp:69
static void apply(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const std::vector< ecs::Entity::Identifier > &childIdentifiers, std::uint32_t layer=0)
Arrange children inside a container and size the container.
Definition layout.cpp:126
static std::uint32_t layerOf(const ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
Get the layer of an entity: its depth in the entity tree.
Definition layout.cpp:90

Things to know:

  • Children are never resized. Their Bound comes from the Measure phase (text, icons) or from their own layout.
  • The Layout phase visits parents before children. A container therefore reads the Bound a nested container computed on the previous frame, and a change of size deep in the tree reaches the root one level per frame.
  • The container's Bound is overwritten every frame: set a fixed width or height on components::Layout to impose a size.
  • Children are offset along the world X and Y axes from the container's position; only the depth lift follows the container's orientation.
  • The widget systems are registered after this one because they place their own children from the bounds resolved here.
See also
components::Layout, components::Hierarchy
systems::registerCoreSystems

Definition at line 81 of file layout.hpp.

Constructor & Destructor Documentation

◆ Layout()

guillaume::systems::Layout::Layout ( void )

Create the system in the Layout phase.

Definition at line 69 of file layout.cpp.

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

Member Function Documentation

◆ apply()

void guillaume::systems::Layout::apply ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & parentIdentifier,
const std::vector< ecs::Entity::Identifier > & childIdentifiers,
std::uint32_t layer = 0 )
static

Arrange children inside a container and size the container.

Children are placed one after the other along the axis of the container's components::Layout, separated by its spacing and inset by its padding, then aligned along both axes. Each child is lifted layer + ContentLayerOffset layers in front of the container. The container's components::Bound receives the fixed size when one is set, otherwise the content size plus twice the padding.

Parameters
registryThe registry holding the components.
parentIdentifierThe container. It must have Layout, Transform and Bound.
childIdentifiersThe children to arrange, in order. ecs::Entity::InvalidIdentifier and children without Transform or Bound are skipped and take no room.
layerThe layer of the container, as returned by layerOf().
Exceptions
ecs::EntityComponentNotFoundExceptionWhen the container lacks one of the three components.

Definition at line 126 of file layout.cpp.

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

◆ applyLayerToPosition()

const utility::graphic::PoseF guillaume::systems::Layout::applyLayerToPosition ( const utility::graphic::PositionF & position,
const utility::graphic::OrientationF & orientation,
const std::uint32_t & layer )
static

Move a position in front of a container.

The position is moved by (layer + ContentLayerOffset) * LayerDepthStep towards the viewer, against the forward axis of orientation.

Parameters
positionThe position to lift, usually computed in the plane of the container.
orientationThe orientation of the container. It is copied into the returned pose.
layerThe layer of the container, as returned by layerOf().
Returns
The lifted position with orientation.

Definition at line 103 of file layout.cpp.

Here is the caller graph for this function:

◆ contentLayerPose()

const utility::graphic::PoseF guillaume::systems::Layout::contentLayerPose ( const utility::graphic::PositionF & position,
const utility::graphic::OrientationF & orientation,
const std::uint32_t & containerLayer )
static

Compute the pose of content placed by hand on a container.

Same result as applyLayerToPosition(). Widget systems that place a text or an icon themselves call it so that everything drawn on a container sits at the same distance in front of it.

Parameters
positionThe position of the content in the plane of the container.
orientationThe orientation of the container.
containerLayerThe layer of the container, as returned by layerOf().
Returns
The pose to give to the content.

Definition at line 118 of file layout.cpp.

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

◆ layerOf()

std::uint32_t guillaume::systems::Layout::layerOf ( const ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & identifier )
static

Get the layer of an entity: its depth in the entity tree.

Parameters
registryThe registry holding the components.
identifierThe entity to look up.
Returns
The layer stored in its components::Hierarchy, or 0 when the entity has no Hierarchy.

Definition at line 90 of file layout.cpp.

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

◆ update()

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

Arrange the children listed in the components::Layout of one container, using the layer of its components::Hierarchy.

Parameters
entityIdentifierThe container entity.

Implements guillaume::ecs::System.

Definition at line 75 of file layout.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ ContentLayerOffset

std::uint32_t guillaume::systems::Layout::ContentLayerOffset = 1
staticconstexpr

Number of layers added between a container and what is placed on it.

Text, icons and other children sit in front of the surface of their container; without this gap both would be at the same depth and flicker (z-fighting).

Definition at line 101 of file layout.hpp.

◆ LayerDepthStep

float guillaume::systems::Layout::LayerDepthStep = 1.0f
staticconstexpr

Depth of one layer: the distance a child is moved towards the viewer, against the forward axis of its container, for each layer.

Definition at line 91 of file layout.hpp.


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