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

A single run of text drawn with a typescale role, a color and an optional explicit font size. More...

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

Inheritance diagram for guillaume::entities::Text:
Collaboration diagram for guillaume::entities::Text:

Classes

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

Public Types

enum class  Type {
  Normal , Condensed , Monospace , Serif ,
  Slab
}
 Font family kinds. No function of the library reads this enumeration. More...
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

 ~Text (void)
 Destructor.
Text & setContent (const std::string &content)
 Replace the characters to draw.
Text & setFontSize (const float &fontSize)
 Override the role font size with an explicit size.
Text & setTypeRole (theme::TypeRole role)
 Set the typescale role and drop any explicit font size.
theme::TypeRole getTypeRole (void) const
 Get the typescale role the text is styled with.
Text & setColor (const utility::graphic::Color32Bit &color)
 Set the text color.
Public Member Functions inherited from guillaume::ecs::EntityFiller< components::Transform, components::Bound, components::Text, components::Color, components::Typography >
 EntityFiller (ComponentRegistry &componentRegistry)
 Create the entity, its listed components and its components::Hierarchy.
virtual ~EntityFiller (void)=default
 Destroy the entity object; its 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.

Static Public Member Functions

template<typename... Arguments>
static std::shared_ptr< Text > create (Arguments &&...arguments)
 Build a text 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::EntityFiller< components::Transform, components::Bound, components::Text, components::Color, components::Typography >
ComponentRegistry & getComponentRegistry (void)
 Get the registry that stores this entity's components.
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 single run of text drawn with a typescale role, a color and an optional explicit font size.

Text is a leaf widget: it has no children. Its state lives in four components: components::Text (content and font metrics), components::Typography (typescale role and explicit size), components::Color and components::Transform. Each frame, in the Measure phase, systems::Typography resolves the role against the active theme into the font metrics, then systems::MeasureText writes the measured size into components::Bound. systems::TextRender draws the text in the Render phase. The class itself holds no field.

Text::Builder builder(getComponentRegistry(), getEntityRegistry());
auto title = builder.makeText(parent, "Settings",
getActiveColor(SchemeColorRole::OnSurface));
title->setContent("Preferences");
Configures Text widgets and registers them in the scene's entity registry.
Definition text.hpp:98
@ TitleLarge
22 / 28, regular.
Definition typescale.hpp:54
utility::graphic::Color32Bit getActiveColor(SchemeColorRole role)
Get the color the active scheme gives to a role.

Text::create(registry, content, role, color) or Text::create(registry, content, fontSize, color) builds the same widget without registering it in an entity registry.

Watch out:

  • The Bound is overwritten every frame with the measured size; do not size a text by hand.
  • The font weight, line height and letter spacing always come from the role. An explicit font size only replaces the size of the role.
  • The font metrics in components::Text are overwritten every frame from components::Typography; change them through setTypeRole() and setFontSize().
See also
components::Typography, systems::Typography, systems::MeasureText

Definition at line 81 of file text.hpp.

Member Enumeration Documentation

◆ Type

Font family kinds. No function of the library reads this enumeration.

Definition at line 91 of file text.hpp.

Constructor & Destructor Documentation

◆ ~Text()

guillaume::entities::Text::~Text ( void )

Destructor.

Definition at line 120 of file text.cpp.

Member Function Documentation

◆ create()

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

Build a text without registering it in an entity registry.

The arguments are forwarded to a private constructor: (registry, content, role, color), optionally followed by an explicit font size, or (registry, content, fontSize, color), which uses the role theme::TypeRole::Default. A text has no children to build.

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

Definition at line 218 of file text.hpp.

Here is the caller graph for this function:

◆ getTypeRole()

theme::TypeRole guillaume::entities::Text::getTypeRole ( void ) const

Get the typescale role the text is styled with.

Returns
The role stored in components::Typography.

Definition at line 163 of file text.cpp.

◆ setColor()

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

Set the text color.

Parameters
colorThe new color (RGBA), written to components::Color.
Returns
Reference to this text for chaining.

Definition at line 168 of file text.cpp.

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

◆ setContent()

Text & guillaume::entities::Text::setContent ( const std::string & content)

Replace the characters to draw.

Writes components::Text. The Bound follows at the next Measure phase.

Parameters
contentThe new text content.
Returns
Reference to this text for chaining.

Definition at line 141 of file text.cpp.

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

◆ setFontSize()

Text & guillaume::entities::Text::setFontSize ( const float & fontSize)

Override the role font size with an explicit size.

Writes components::Typography and resolves the font metrics at once. The weight, line height and letter spacing still come from the role.

Parameters
fontSizeThe new font size, in dp.
Returns
Reference to this text for chaining.

Definition at line 149 of file text.cpp.

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

◆ setTypeRole()

Text & guillaume::entities::Text::setTypeRole ( theme::TypeRole role)

Set the typescale role and drop any explicit font size.

Writes components::Typography and resolves the font metrics at once.

Parameters
roleThe typescale role, resolved against the active theme each frame.
Returns
Reference to this text for chaining.

Definition at line 156 of file text.cpp.

Here is the call graph for this function:

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