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

A run of text: its content, its font metrics and the position of the editing cursor. More...

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

Inheritance diagram for guillaume::components::Text:
Collaboration diagram for guillaume::components::Text:

Public Member Functions

 Text (void)=default
 Default constructor for the Text component.
 ~Text (void)=default
 Default destructor for the Text component.
const std::string & getContent (void) const
 Get the text.
Text & setContent (const std::string &content)
 Replace the text.
float getFontSize (void) const
 Get the font size.
Text & setFontSize (float fontSize)
 Set the font size.
theme::FontWeight getFontWeight (void) const
 Get the font weight.
Text & setFontWeight (theme::FontWeight fontWeight)
 Set the font weight.
float getLineHeight (void) const
 Get the minimum height of the text's bound.
Text & setLineHeight (float lineHeight)
 Set the minimum height of the text's bound.
float getLetterSpacing (void) const
 Get the extra space between letters.
Text & setLetterSpacing (float letterSpacing)
 Set the extra space between letters.
Text & setTypeToken (const theme::TypeToken &token)
 Apply the four metrics of a typescale token at once: font size, weight, line height and letter spacing.
std::size_t getCursorPosition (void) const
 Get the position of the editing cursor.
Text & setCursorPosition (std::size_t position)
 Move the editing cursor.
bool moveCursorLeft (void)
 Move the cursor to the start of the previous UTF-8 character. Marks the component changed when it moves.
bool moveCursorRight (void)
 Move the cursor past the next UTF-8 character. Marks the component changed when it moves.
Text & insertCharacter (char ch)
 Insert one byte at the cursor and move the cursor after it. Marks the component changed.
Text & insertString (const std::string &str)
 Insert a string at the cursor and move the cursor after it. Always marks the component changed, even for an empty string.
bool deleteCharacterBefore (void)
 Delete the UTF-8 character before the cursor (backspace) and move the cursor back to where it started. Marks the component changed when a character is deleted.
bool deleteCharacterAfter (void)
 Delete the UTF-8 character after the cursor (delete key); the cursor does not move. Marks the component changed when a character is deleted.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Detailed Description

A run of text: its content, its font metrics and the position of the editing cursor.

Readers: systems::MeasureText (Measure phase) writes the size of the text into the entity's components::Bound, and systems::TextRender (Render phase) draws it at the entity's components::Transform in the entity's components::Color.

Writers: entities::Text and the widget systems set the content; systems::Typography writes the four font metrics every frame on an entity that also has a components::Typography; systems::TextInput appends typed text to the content and systems::KeyboardControl moves the cursor and deletes around it.

auto &text = registry.getComponent<components::Text>(id);
text.setContent("Hello").setTypeToken(
A run of text: its content, its font metrics and the position of the editing cursor.
Definition text.hpp:66
Text & setContent(const std::string &content)
Replace the text.
Definition text.cpp:34
Text & setTypeToken(const theme::TypeToken &token)
Apply the four metrics of a typescale token at once: font size, weight, line height and letter spacin...
Definition text.cpp:108
@ TitleMedium
16 / 24, medium weight.
Definition typescale.hpp:55
const theme::TypeToken & getTypeToken(theme::TypeRole role)
Get the text style the active theme gives to a role: font family, weight, size, line height and lette...
Note
The content is UTF-8 and the cursor position is a byte offset into it, not a character count.
On an entity with a components::Typography, set the role or the size there: the metrics written here are replaced on the next frame.
No system of the library reads the letter spacing.
See also
systems::MeasureText, systems::TextRender, entities::Text

Definition at line 65 of file text.hpp.

Member Function Documentation

◆ deleteCharacterAfter()

bool guillaume::components::Text::deleteCharacterAfter ( void )

Delete the UTF-8 character after the cursor (delete key); the cursor does not move. Marks the component changed when a character is deleted.

Returns
True when a character was deleted, false when the cursor is at the end.

Definition at line 199 of file text.cpp.

Here is the call graph for this function:

◆ deleteCharacterBefore()

bool guillaume::components::Text::deleteCharacterBefore ( void )

Delete the UTF-8 character before the cursor (backspace) and move the cursor back to where it started. Marks the component changed when a character is deleted.

Returns
True when a character was deleted, false when the cursor is at the start.

Definition at line 180 of file text.cpp.

Here is the call graph for this function:

◆ getContent()

const std::string & guillaume::components::Text::getContent ( void ) const

Get the text.

Returns
The content, UTF-8; empty by default.

Definition at line 29 of file text.cpp.

Here is the caller graph for this function:

◆ getCursorPosition()

std::size_t guillaume::components::Text::getCursorPosition ( void ) const

Get the position of the editing cursor.

Returns
A byte offset into the content, from 0 (before the first character) to the content size (after the last one).

Definition at line 119 of file text.cpp.

◆ getFontSize()

float guillaume::components::Text::getFontSize ( void ) const

Get the font size.

Returns
The font size, in dp (24 by default).

Definition at line 48 of file text.cpp.

◆ getFontWeight()

theme::FontWeight guillaume::components::Text::getFontWeight ( void ) const

Get the font weight.

Returns
The weight (Regular by default).

Definition at line 60 of file text.cpp.

◆ getLetterSpacing()

float guillaume::components::Text::getLetterSpacing ( void ) const

Get the extra space between letters.

Returns
The letter spacing, in dp (0 by default).

Definition at line 93 of file text.cpp.

◆ getLineHeight()

float guillaume::components::Text::getLineHeight ( void ) const

Get the minimum height of the text's bound.

Returns
The line height, in dp; 0 (the default) when the measured height is used as is.

Definition at line 75 of file text.cpp.

◆ insertCharacter()

Text & guillaume::components::Text::insertCharacter ( char ch)

Insert one byte at the cursor and move the cursor after it. Marks the component changed.

Parameters
chThe byte to insert; use insertString() for a character that takes several bytes in UTF-8.
Returns
This component, for chaining.

Definition at line 164 of file text.cpp.

Here is the call graph for this function:

◆ insertString()

Text & guillaume::components::Text::insertString ( const std::string & str)

Insert a string at the cursor and move the cursor after it. Always marks the component changed, even for an empty string.

Parameters
strThe UTF-8 text to insert.
Returns
This component, for chaining.

Definition at line 172 of file text.cpp.

Here is the call graph for this function:

◆ moveCursorLeft()

bool guillaume::components::Text::moveCursorLeft ( void )

Move the cursor to the start of the previous UTF-8 character. Marks the component changed when it moves.

Returns
True when the cursor moved, false when it was already at the start.

Definition at line 131 of file text.cpp.

Here is the call graph for this function:

◆ moveCursorRight()

bool guillaume::components::Text::moveCursorRight ( void )

Move the cursor past the next UTF-8 character. Marks the component changed when it moves.

Returns
True when the cursor moved, false when it was already at the end.

Definition at line 147 of file text.cpp.

Here is the call graph for this function:

◆ setContent()

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

Replace the text.

A cursor beyond the end of the new content is moved to its end. Marks the component changed only when the content differs.

Parameters
contentThe new content, UTF-8.
Returns
This component, for chaining.

Definition at line 34 of file text.cpp.

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

◆ setCursorPosition()

Text & guillaume::components::Text::setCursorPosition ( std::size_t position)

Move the editing cursor.

Always marks the component changed.

Parameters
positionA byte offset into the content; a value beyond the end is clamped to the content size. It is not checked against UTF-8 character boundaries.
Returns
This component, for chaining.

Definition at line 124 of file text.cpp.

Here is the call graph for this function:

◆ setFontSize()

Text & guillaume::components::Text::setFontSize ( float fontSize)

Set the font size.

Always marks the component changed, even when the size is the same.

Parameters
fontSizeThe font size, in dp.
Returns
This component, for chaining.

Definition at line 53 of file text.cpp.

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

◆ setFontWeight()

Text & guillaume::components::Text::setFontWeight ( theme::FontWeight fontWeight)

Set the font weight.

The weight selects the font file the text is measured and drawn with (see theme::fontPath). Marks the component changed only when the weight differs.

Parameters
fontWeightThe weight of the font.
Returns
This component, for chaining.

Definition at line 65 of file text.cpp.

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

◆ setLetterSpacing()

Text & guillaume::components::Text::setLetterSpacing ( float letterSpacing)

Set the extra space between letters.

The value is stored; the measure and render systems do not apply it. Marks the component changed only when the value differs.

Parameters
letterSpacingThe letter spacing, in dp.
Returns
This component, for chaining.

Definition at line 98 of file text.cpp.

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

◆ setLineHeight()

Text & guillaume::components::Text::setLineHeight ( float lineHeight)

Set the minimum height of the text's bound.

systems::MeasureText writes the larger of the measured height and this value into the Bound, so short text still takes a full line. Marks the component changed only when the value differs.

Parameters
lineHeightThe line height, in dp; must not be negative.
Returns
This component, for chaining.
Exceptions
std::invalid_argumentIf lineHeight is negative.

Definition at line 80 of file text.cpp.

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

◆ setTypeToken()

Text & guillaume::components::Text::setTypeToken ( const theme::TypeToken & token)

Apply the four metrics of a typescale token at once: font size, weight, line height and letter spacing.

Marks the component changed only when at least one metric differs, so systems::Typography can call it every frame.

Parameters
tokenThe token, usually from getTypeToken(role).
Returns
This component, for chaining.
Exceptions
std::invalid_argumentIf the token's line height is negative.

Definition at line 108 of file text.cpp.

Here is the call graph for this function:

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