Text

Text drawn in canvas space from a bitmap font.

Text lays out a UTF-8 string as one quad per glyph using its font's metrics. The glyphs are rebuilt when the text, font, alignment, or line spacing changes. The font is read only at that point, so it must be complete before it is assigned. Later changes to it are not picked up.

Metrics are in the font's atlas pixels so text draws at the size the font was authored at until scaled through transform. The node's position is the top-left corner of the text's bounds unless the anchor moves it.

auto font = vglx::LoadFont("assets/fonts/roboto.fnt");
if (font.has_value()) {
  auto label = canvas.Add(vglx::Text::Create(font.value(), "Score 0"));
  label->anchor = {1.0f, 0.0f};
  label->transform.SetPosition({canvas.GetSize().x - 24.0f, 24.0f});
}

INFO

Derives from Renderable2D and inherits all public properties and methods.

Construction

Constructors

Text()

Constructs a text node.

Text::Text(std::shared_ptr<Font> font, std::string_view text);

Parameter	Description
font	Font to lay out with or nullptr to assign one later.
text	UTF-8 string to display.

Factories preferred

Text::Create() std::unique_ptr<Text>

Creates an instance of Text.

static std::unique_ptr<Text> Text::Create(std::shared_ptr<Font> font, std::string_view text);

Parameter	Description
font	Font to lay out with or nullptr to assign one later.
text	UTF-8 string to display.

Types

Text::Alignment enum

Horizontal alignment of lines within the text's bounds.

Value	Description
Left	Lines start at the left edge of the bounds.
Center	Lines are centered within the bounds.
Right	Lines end at the right edge of the bounds.

Functions

GetAlignment() Alignment

Returns the horizontal alignment of lines.

Alignment Text::GetAlignment() const;

GetFont() std::shared_ptr<Font>

Returns the font.

std::shared_ptr<Font> Text::GetFont() const;

GetGeometry() std::shared_ptr<Geometry> virtual

Returns the glyph quads laid out in canvas units.

The geometry may be replaced when the text or font changes so the returned pointer should not be cached.

std::shared_ptr<Geometry> Text::GetGeometry() override;

GetLineSpacing() float

Returns the line spacing multiplier.

float Text::GetLineSpacing() const;

GetNodeType() Node2D::Type virtual

Identifies this node as Node2D::Type::Text.

Type vglx::Text::GetNodeType() const override;

GetSize() Vector2 virtual

Returns the size of the text's bounds in canvas units before scaling.

The width is the widest line measured by glyph advances and kerning, and the height covers every line. Returns zero for an empty string or a missing font.

Vector2 Text::GetSize() const override;

GetText() const std::string&

Returns the displayed string.

const std::string& Text::GetText() const;

GetTexture() std::shared_ptr<Texture2D> virtual

Returns the font's atlas page or nullptr without a font.

std::shared_ptr<Texture2D> Text::GetTexture() const override;

SetAlignment() void

Sets the horizontal alignment of lines.

void Text::SetAlignment(Alignment alignment);

Parameter	Description
alignment	Alignment to apply.

SetFont() void

Replaces the font.

void Text::SetFont(std::shared_ptr<Font> font);

Parameter	Description
font	Font to lay out with or nullptr to draw nothing.

SetLineSpacing() void

Sets the spacing between lines as a multiple of the font's line height.

void Text::SetLineSpacing(float spacing);

Parameter	Description
spacing	Multiplier applied to the font's line height. Defaults to 1.0.

SetText() void

Replaces the displayed string.

Characters the font has no glyph for are skipped, as are malformed UTF-8 sequences.

void Text::SetText(std::string_view text);

Parameter	Description
text	UTF-8 string to display.