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

A rectangle, colored or transparent, that lays its children out in a row or a column. More...

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

Inheritance diagram for guillaume::entities::View:
Collaboration diagram for guillaume::entities::View:

Classes

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

Public Types

using Axis = components::Layout::Axis
using MainAxisAlignment = components::Layout::MainAxisAlignment
 How the children are distributed along the axis.
using CrossAxisAlignment = components::Layout::CrossAxisAlignment
 How each child is aligned across the axis.
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

 ~View (void)
 Destructor.
View & setPose (const utility::graphic::PoseF &pose)
 Move the view. Moves its layout children at once.
View & setColor (const utility::graphic::Color32Bit &color)
 Set the background color.
View & setBorderRadius (float borderRadius)
 Set the corner radius of the background.
View & setAxis (Axis axis)
 Choose between a row and a column. Arranges the children at once.
View & setMainAxisAlignment (MainAxisAlignment alignment)
 Set how the children are distributed along the axis. Arranges the children at once.
View & setCrossAxisAlignment (CrossAxisAlignment alignment)
 Set how each child is aligned across the axis. Arranges the children at once.
View & setSpacing (float spacing)
 Set the gap between two consecutive children. Arranges the children at once.
View & setPadding (float padding)
 Set the space between the edges of the view and its children. Arranges the children at once.
View & setFixedWidth (float width)
 Force the width of the view, whatever its children. Arranges the children at once.
View & clearFixedWidth (void)
 Let the width follow the children again: their extent plus the padding. Arranges the children at once.
View & setFixedHeight (float height)
 Force the height of the view, whatever its children. Arranges the children at once.
View & clearFixedHeight (void)
 Let the height follow the children again: their extent plus the padding. Arranges the children at once.
View & setEntities (const std::vector< std::shared_ptr< ecs::Entity > > &entities)
 Replace the entities the view arranges.
Public Member Functions inherited from guillaume::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders >
 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< View > create (Arguments &&...arguments)
 Build a view 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.

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::ecs::ParentEntityFiller< components::Layout, components::Transform, components::Bound, components::Color, components::Borders >
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 rectangle, colored or transparent, that lays its children out in a row or a column.

View has no component of its own. Its state lives in components::Transform (pose of its top-left corner), components::Color (background), components::Borders (corner radius) and components::Layout (axis, alignments, spacing, padding, fixed size and the ordered identifiers of the children to arrange). systems::Layout holds the rules: each frame, in the Layout phase, it places every layout child along the axis and writes the size of the view into components::Bound. The class itself holds no field: its layout setters write the components and arrange the children at once.

A view is also an entity registry (ecs::ParentEntityFiller), so it can own the widgets built inside it: pass *view as the entity registry of their builder.

View::Builder viewBuilder(getComponentRegistry(), getEntityRegistry());
auto row = viewBuilder.withAxis(View::Axis::Horizontal)
.withSpacing(8.0f)
.makeDefaultView(nullptr, utility::graphic::PoseF(), {});
Text::Builder textBuilder(getComponentRegistry(), *row);
auto name = textBuilder.makeText(row, "Name",
getActiveColor(SchemeColorRole::OnSurface));
row->setEntities({ name });
Configures Text widgets and registers them in the scene's entity registry.
Definition text.hpp:98
Configures View widgets and registers them in the scene's entity registry.
Definition view.hpp:118
@ BodyLarge
16 / 24, regular.
Definition typescale.hpp:60
utility::graphic::Color32Bit getActiveColor(SchemeColorRole role)
Get the color the active scheme gives to a role.

View::create(registry, pose, color, borderRadius, axis, mainAxisAlignment, crossAxisAlignment, spacing, padding, hasFixedWidth, fixedWidth, hasFixedHeight, fixedHeight, entities) builds the same widget without registering it in an entity registry.

Watch out:

  • Sizes, spacing, padding and radius are in dp.
  • Only the entities given to setEntities() (or to the builder) are arranged. Parenting an entity to the view is not enough.
  • Attaching an entity does not make the view own it. Each child must be owned by an entity registry (the view itself or another one), or it is destroyed when the last pointer to it goes away.
  • The position of each layout child and the Bound of the view are overwritten every frame. The size of a child is never changed.
  • Without a fixed width or height, the view takes the size of its children plus the padding.
See also
components::Layout, systems::Layout, SurfaceBase

Definition at line 98 of file view.hpp.

Member Typedef Documentation

◆ Axis

Direction the children are arranged in: Horizontal (a row) or Vertical (a column).

Definition at line 107 of file view.hpp.

◆ CrossAxisAlignment

How each child is aligned across the axis.

Definition at line 111 of file view.hpp.

◆ MainAxisAlignment

How the children are distributed along the axis.

Definition at line 109 of file view.hpp.

Constructor & Destructor Documentation

◆ ~View()

guillaume::entities::View::~View ( void )

Destructor.

Definition at line 209 of file view.cpp.

Member Function Documentation

◆ clearFixedHeight()

View & guillaume::entities::View::clearFixedHeight ( void )

Let the height follow the children again: their extent plus the padding. Arranges the children at once.

Returns
Reference to this view for chaining.

Definition at line 328 of file view.cpp.

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

◆ clearFixedWidth()

View & guillaume::entities::View::clearFixedWidth ( void )

Let the width follow the children again: their extent plus the padding. Arranges the children at once.

Returns
Reference to this view for chaining.

Definition at line 306 of file view.cpp.

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

◆ create()

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

Build a view without registering it in an entity registry.

The arguments are forwarded to the private constructor: (registry, pose, color, borderRadius, axis, mainAxisAlignment, crossAxisAlignment, spacing, padding, hasFixedWidth, fixedWidth, hasFixedHeight, fixedHeight, entities). It then calls build(), which parents the given entities to the view and arranges them. A view creates no child of its own.

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

Definition at line 310 of file view.hpp.

Here is the caller graph for this function:

◆ setAxis()

View & guillaume::entities::View::setAxis ( Axis axis)

Choose between a row and a column. Arranges the children at once.

Parameters
axisHorizontal to arrange the children left to right, Vertical for top to bottom.
Returns
Reference to this view for chaining.

Definition at line 240 of file view.cpp.

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

◆ setBorderRadius()

View & guillaume::entities::View::setBorderRadius ( float borderRadius)

Set the corner radius of the background.

Parameters
borderRadiusThe new radius of the four corners, in dp, written to components::Borders.
Returns
Reference to this view for chaining.

Definition at line 232 of file view.cpp.

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

◆ setColor()

View & guillaume::entities::View::setColor ( const utility::graphic::Color32Bit & color)

Set the background color.

Parameters
colorThe new color (RGBA), written to components::Color. A fully transparent color hides the background.
Returns
Reference to this view for chaining.

Definition at line 224 of file view.cpp.

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

◆ setCrossAxisAlignment()

View & guillaume::entities::View::setCrossAxisAlignment ( CrossAxisAlignment alignment)

Set how each child is aligned across the axis. Arranges the children at once.

Parameters
alignmentStart, Center or End.
Returns
Reference to this view for chaining.

Definition at line 262 of file view.cpp.

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

◆ setEntities()

View & guillaume::entities::View::setEntities ( const std::vector< std::shared_ptr< ecs::Entity > > & entities)

Replace the entities the view arranges.

Each entity is parented to the view and its identifier recorded, in order, as a layout child in components::Layout; the children are arranged at once. The view keeps no pointer to the entities: each must be owned by an entity registry. An entity of the previous list that is left out of the new one stays parented to the view but is not arranged.

Parameters
entitiesThe entities to arrange, in layout order. Null entries are skipped.
Returns
Reference to this view for chaining.

Definition at line 339 of file view.cpp.

Here is the call graph for this function:

◆ setFixedHeight()

View & guillaume::entities::View::setFixedHeight ( float height)

Force the height of the view, whatever its children. Arranges the children at once.

Parameters
heightThe new height, in dp.
Returns
Reference to this view for chaining.

Definition at line 317 of file view.cpp.

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

◆ setFixedWidth()

View & guillaume::entities::View::setFixedWidth ( float width)

Force the width of the view, whatever its children. Arranges the children at once.

Parameters
widthThe new width, in dp.
Returns
Reference to this view for chaining.

Definition at line 295 of file view.cpp.

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

◆ setMainAxisAlignment()

View & guillaume::entities::View::setMainAxisAlignment ( MainAxisAlignment alignment)

Set how the children are distributed along the axis. Arranges the children at once.

Parameters
alignmentStart, Center, End or SpaceBetween. It only shows when the view has a fixed size on that axis.
Returns
Reference to this view for chaining.

Definition at line 251 of file view.cpp.

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

◆ setPadding()

View & guillaume::entities::View::setPadding ( float padding)

Set the space between the edges of the view and its children. Arranges the children at once.

Parameters
paddingThe new padding, in dp, the same on the four sides.
Returns
Reference to this view for chaining.

Definition at line 284 of file view.cpp.

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

◆ setPose()

View & guillaume::entities::View::setPose ( const utility::graphic::PoseF & pose)

Move the view. Moves its layout children at once.

Parameters
poseThe new pose of the top-left corner of the view.
Returns
Reference to this view for chaining.

Definition at line 213 of file view.cpp.

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

◆ setSpacing()

View & guillaume::entities::View::setSpacing ( float spacing)

Set the gap between two consecutive children. Arranges the children at once.

Parameters
spacingThe new gap, in dp.
Returns
Reference to this view for chaining.

Definition at line 273 of file view.cpp.

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

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