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

Helpers that position a child relative to its parent by writing the child's components::Transform. More...

Functions

utility::graphic::PoseF poseOf (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier)
 Read the pose (position and orientation) of an entity.
void placeChild (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const ecs::Entity::Identifier &childIdentifier, const utility::graphic::PositionF &offset, std::uint32_t parentLayer)
 Place a child at an offset from the position of its parent.
void centerChild (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const ecs::Entity::Identifier &childIdentifier, std::uint32_t parentLayer)
 Center a child inside the bound of its parent, on both axes.
void placeNormalized (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const ecs::Entity::Identifier &childIdentifier, float normalized, float inset, std::uint32_t parentLayer)
 Place a child along the width of its parent from a 0 to 1 value, vertically centered.
void reserveTrailingWidth (ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &identifier, float width)
 Reserve layout room after an entity's Bound.

Detailed Description

Helpers that position a child relative to its parent by writing the child's components::Transform.

See also
guillaume::systems::Layout, guillaume::systems::style

Function Documentation

◆ centerChild()

void guillaume::systems::placement::centerChild ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & parentIdentifier,
const ecs::Entity::Identifier & childIdentifier,
std::uint32_t parentLayer )
inline

Center a child inside the bound of its parent, on both axes.

Does nothing when the parent or the child has no components::Bound. Both bounds must be up to date: call it after the child has been measured and the parent laid out.

Parameters
registryThe registry holding the components.
parentIdentifierThe entity the child is centered in.
childIdentifierThe entity whose components::Transform is written.
parentLayerThe tree depth of the parent, as returned by systems::Layout::layerOf.

Definition at line 154 of file placement_helpers.hpp.

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

◆ placeChild()

void guillaume::systems::placement::placeChild ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & parentIdentifier,
const ecs::Entity::Identifier & childIdentifier,
const utility::graphic::PositionF & offset,
std::uint32_t parentLayer )
inline

Place a child at an offset from the position of its parent.

Writes the pose of the child: the parent position plus the offset, with the parent orientation, moved toward the viewer by systems::Layout::contentLayerPose so the child never z-fights with the surface of the parent. Does nothing when the child has no components::Transform.

// Put a label 8 dp right of and 4 dp below the parent position.
placement::placeChild(registry, parent, label,
utility::graphic::PositionF(8.0f, 4.0f, 0.0f),
Layout::layerOf(registry, parent));
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
void placeChild(ecs::ComponentRegistry &registry, const ecs::Entity::Identifier &parentIdentifier, const ecs::Entity::Identifier &childIdentifier, const utility::graphic::PositionF &offset, std::uint32_t parentLayer)
Place a child at an offset from the position of its parent.
Parameters
registryThe registry holding the components.
parentIdentifierThe entity the child is placed against. Without a components::Transform it counts as a default pose.
childIdentifierThe entity whose components::Transform is written.
offsetThe offset from the parent position, in dp. Only x and y are used; the depth comes from parentLayer.
parentLayerThe tree depth of the parent, as returned by systems::Layout::layerOf.

Definition at line 117 of file placement_helpers.hpp.

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

◆ placeNormalized()

void guillaume::systems::placement::placeNormalized ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & parentIdentifier,
const ecs::Entity::Identifier & childIdentifier,
float normalized,
float inset,
std::uint32_t parentLayer )
inline

Place a child along the width of its parent from a 0 to 1 value, vertically centered.

0 puts the child against the left inset, 1 against the right inset. systems::Switch places its handle this way (0 when off, 1 when on). Does nothing when the parent or the child has no components::Bound.

Parameters
registryThe registry holding the components.
parentIdentifierThe entity the child travels in.
childIdentifierThe entity whose components::Transform is written.
normalizedThe position along the available travel, 0 to 1. The value is not clamped.
insetThe space kept free at the left and right edges of the parent, in dp. When the child is wider than what remains, it stays against the left inset.
parentLayerThe tree depth of the parent, as returned by systems::Layout::layerOf.

Definition at line 197 of file placement_helpers.hpp.

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

◆ poseOf()

utility::graphic::PoseF guillaume::systems::placement::poseOf ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & identifier )
inline

Read the pose (position and orientation) of an entity.

The other helpers use it to get the pose of the parent a child is placed against.

Parameters
registryThe registry holding the components.
identifierThe entity whose components::Transform is read.
Returns
The pose of the entity, or a default-constructed pose when the entity has no components::Transform.

Definition at line 81 of file placement_helpers.hpp.

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

◆ reserveTrailingWidth()

void guillaume::systems::placement::reserveTrailingWidth ( ecs::ComponentRegistry & registry,
const ecs::Entity::Identifier & identifier,
float width )
inline

Reserve layout room after an entity's Bound.

For a widget that draws a small shape and places a child beside it (a checkbox and its label): the parent layout then keeps that room free instead of putting the next widget over the child. Adds the components::LayoutExtent when needed.

Parameters
registryThe registry holding the components.
identifierThe widget entity.
widthThe room after the Bound, in dp; 0 or less releases it.

Definition at line 236 of file placement_helpers.hpp.

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