A class to represent text objects in a graphical context, allowing for rendering and manipulation of unicode text. More...

#include <thorvg.h>

Inheritance diagram for Text:

[legend]

Collaboration diagram for Text:

[legend]

Public Member Functions
Result	font (const char *name) noexcept
	Sets the font family for the text.

Result	size (float size) noexcept
	Sets the font size for the text.

Result	text (const char *text) noexcept
	Assigns the given unicode text to be rendered.

Result	align (float x, float y) noexcept
	Sets text alignment or anchor per axis.

Result	layout (float w, float h) noexcept
	Sets the virtual layout box (constraints) for the text.

Result	wrap (TextWrap mode) noexcept
	Sets the text wrapping mode for this text object.

Result	italic (float shear=0.18f) noexcept
	Apply an italic (slant) transformation to the text.

Result	outline (float width, uint8_t r, uint8_t g, uint8_t b) noexcept
	Sets an outline (stroke) around the text object.

Result	fill (uint8_t r, uint8_t g, uint8_t b) noexcept
	Sets the text color.

Result	fill (Fill *f) noexcept
	Sets the gradient fill for all of the figures from the text.

Result	spacing (float letter, float line) noexcept
	Set the spacing scale factors for text layout.

Type	type () const noexcept override
	Returns the ID value of this class.

Public Member Functions inherited from Paint
const Paint *	parent () const noexcept
	Retrieves the parent paint object.

Result	visible (bool on) noexcept
	Sets the visibility of the Paint object.

Result	rotate (float degree) noexcept
	Sets the angle by which the object is rotated.

Result	scale (float factor) noexcept
	Sets the scale value of the object.

Result	translate (float x, float y) noexcept
	Sets the values by which the object is moved in a two-dimensional space.

Result	transform (const Matrix &m) noexcept
	Sets the matrix of the affine transformation for the object.

Matrix &	transform () noexcept
	Gets the matrix of the affine transformation of the object.

Result	opacity (uint8_t o) noexcept
	Sets the opacity of the object.

Result	mask (Paint *target, MaskMethod method) noexcept
	Sets the masking target object and the masking method.

Result	clip (Shape *clipper) noexcept
	Clip the drawing region of the paint object.

Result	blend (BlendMethod method) noexcept
	Sets the blending method for the paint object.

Result	bounds (Point *pt4) noexcept
	Retrieves the object-oriented bounding box (OBB) of the paint object in canvas space.

Result	bounds (float x, float y, float w, float h) noexcept
	Retrieves the axis-aligned bounding box (AABB) of the paint object in canvas space.

bool	intersects (int32_t x, int32_t y, int32_t w=1, int32_t h=1) noexcept
	Checks whether a given region intersects the filled area of the paint.

Paint *	duplicate () const noexcept
	Duplicates the object.

uint8_t	opacity () const noexcept
	Gets the opacity value of the object.

MaskMethod	mask (const Paint **target) const noexcept
	Gets the masking target object and the masking method.

Shape *	clip () const noexcept
	Get the clipper shape of the paint object.

bool	visible () const noexcept
	Gets the current visibility status of the Paint object.

uint16_t	ref () noexcept
	Increment the reference count for the Paint instance.

uint16_t	unref (bool free=true) noexcept
	Decrement the reference count for the Paint instance.

uint16_t	refCnt () const noexcept
	Retrieve the current reference count of the Paint instance.

Static Public Member Functions
static Result	load (const char *filename) noexcept
	Loads a scalable font data (ttf) from a file.

static Result	load (const char name, const char data, uint32_t size, const char *mimeType="ttf", bool copy=false) noexcept
	Loads a scalable font data (ttf) from a memory block of a given size.

static Result	unload (const char *filename) noexcept
	Unloads the specified scalable font data (TTF) that was previously loaded.

static Text *	gen () noexcept
	Creates a new Text object.

Static Public Member Functions inherited from Paint
static void	rel (Paint *paint) noexcept
	Safely releases a Paint object.

Additional Inherited Members
Public Attributes inherited from Paint
uint32_t	id = 0
	Unique ID of this instance.

Detailed Description

A class to represent text objects in a graphical context, allowing for rendering and manipulation of unicode text.

Warning: This class is not designed for inheritance.

Since: 0.15

Member Function Documentation

◆ align()

Result align	(	float	x,
		float	y
	)

noexcept

Sets text alignment or anchor per axis.

If layout width/height is set on an axis, align within the layout box. Otherwise, treat it as an anchor within the text bounds which point of the text box is pinned to the paint position.

Parameters

[in]	x	Horizontal alignment/anchor in [0..1]: 0=left/start, 0.5=center, 1=right/end. (Default is 0)
[in]	y	Vertical alignment/anchor in [0..1]: 0=top, 0.5=middle, 1=bottom. (Default is 0)

Since: 1.0

See also: layout()

◆ fill() [1/2]

Result fill ( Fill * f )

noexcept

Sets the gradient fill for all of the figures from the text.

The parts of the text defined as inner are filled.

Parameters

[in] f The unique pointer to the gradient fill.

Note: Either a solid color or a gradient fill is applied, depending on what was set as last.

See also: Text::font()

Since: 0.15

◆ fill() [2/2]

Result fill	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

noexcept

Sets the text color.

Parameters

[in]	r	The red color channel value in the range [0 ~ 255]. The default value is 0.
[in]	g	The green color channel value in the range [0 ~ 255]. The default value is 0.
[in]	b	The blue color channel value in the range [0 ~ 255]. The default value is 0.

See also: Text::font(); Text::outline()

Since: 0.15

◆ font()

Result font ( const char * name )

noexcept

Sets the font family for the text.

This function specifies the name of the font to be used when rendering text.

Parameters

[in] name The name of the font. This should match a font available through the canvas backend. If set to nullptr, ThorVG will attempt to select a fallback font available on the engine.

Return values

Result::InsufficientCondition when the specified name cannot be found.

Note: This function only sets the font family name. Use size() to define the font size.; If the name is not specified, ThorVG will select an available fallback font.

See also: Text::size(); Text::load()

Since: 1.0

◆ gen()

static Text * gen ( )

staticnoexcept

Creates a new Text object.

This function allocates and returns a new Text instance. To properly destroy the Text object, use Paint::rel().

Returns: A pointer to the newly created Text object.

See also: Paint::rel()

Since: 0.15

◆ italic()

Result italic ( float shear = 0.18f )

noexcept

Apply an italic (slant) transformation to the text.

This function applies a shear transformation to simulate an italic (oblique) style for the current text object. The shear factor determines the degree of slant applied along the X-axis.

Parameters

[in] shear The shear factor to apply. A value of 0.0 applies no slant, while values around 0.5 result in a strong slant. Must be in the range [0.0, 0.5]. Default value is 0.18.

Note: The shear factor will be clamped to the valid range if it exceeds the limits.; This does not require the font itself to be italic. It visually simulates the effect by applying a transformation matrix.

Warning: Excessive slanting may cause visual distortion depending on the font and size.

See also: Text::font()

Since: 1.0

◆ layout()

Result layout	(	float	w,
		float	h
	)

noexcept

Sets the virtual layout box (constraints) for the text.

If width/height is set on an axis, that axis is constrained by a virtual layout box and the text may wrap/align inside it. If width/height == 0, the axis is unconstrained and align() acts as an anchor on that axis.

Parameters

[in]	w	Layout width in user space. Use 0 for no horizontal constraint. (Default is 0)
[in]	h	Layout height in user space. Use 0 for no vertical constraint. (Default is 0)

Note: This defines constraints only; alignment/anchoring is controlled by align().

Since: 1.0

See also: align(); spacing()

◆ load() [1/2]

static Result load ( const char * filename )

staticnoexcept

Loads a scalable font data (ttf) from a file.

ThorVG efficiently caches the loaded data using the specified path as a key. This means that loading the same file again will not result in duplicate operations; instead, ThorVG will reuse the previously loaded font data.

Parameters

[in] filename A file name, including the path, for the font file.

Return values

Result::InvalidArguments	In case the `path` is invalid.
Result::NonSupport	When trying to load a file with an unknown extension.

See also: Text::unload(const char* filename)

Since: 0.15

◆ load() [2/2]

static Result load	(	const char *	name,
		const char *	data,
		uint32_t	size,
		const char *	mimeType = `"ttf"`,
		bool	copy = `false`
	)

staticnoexcept

Loads a scalable font data (ttf) from a memory block of a given size.

ThorVG efficiently caches the loaded font data using the specified name as a key. This means that loading the same fonts again will not result in duplicate operations. Instead, ThorVG will reuse the previously loaded font data.

Parameters

[in]	name	The name under which the font will be stored and accessible (e.x. in a `font()` API).
[in]	data	A pointer to a memory location where the content of the font data is stored.
[in]	size	The size in bytes of the memory occupied by the `data`.
[in]	mimeType	Mimetype or extension of font data. In case an empty string is provided the loader will be determined automatically.
[in]	copy	If `true` the data are copied into the engine local buffer, otherwise they are not (default).

Return values

Result::InvalidArguments	If no name is provided or if `size` is zero while `data` points to a valid memory location.
Result::NonSupport	When trying to load a file with an unsupported extension.
Result::InsufficientCondition	If attempting to unload the font data that has not been previously loaded.

Warning: It's the user responsibility to release the data memory.

Note: To unload the font data loaded using this API, pass the proper name and nullptr as data.; If you are unsure about the MIME type, you can provide an empty value like nullptr, and thorvg will attempt to figure it out.

See also: Text::font(const char* name, float size, const char* style)

Since: 0.15

◆ outline()

Result outline	(	float	width,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

noexcept

Sets an outline (stroke) around the text object.

This function adds an outline to the text with the specified width and RGB color. The outline enhances the visibility of the text by rendering a stroke around its glyphs.

Parameters

width	The width of the outline. Must be positive value. (The default is 0)
r	Red component of the outline color (0–255).
g	Green component of the outline color (0–255).
b	Blue component of the outline color (0–255).

Note: To disable the outline, set width to 0.

See also: Text::fill() to set the main text fill color.

Since: 1.0

◆ size()

Result size ( float size )

noexcept

Sets the font size for the text.

This function sets the font size used during text rendering. The size is specified in point units, and supports floating-point precision for smooth scaling and animation effects.

Parameters

[in] size The font size in points. Must be greater than 0.0.

Return values

Result::InvalidArguments if the size is less than or equal to 0.

Note: Use this function in combination with font() to fully define text appearance.; Fractional sizes (e.g., 12.5) are supported for sub-pixel rendering and animations.

See also: Text::font()

Since: 1.0

◆ spacing()

Result spacing	(	float	letter,
		float	line
	)

noexcept

Set the spacing scale factors for text layout.

This function adjusts the letter spacing (horizontal space between glyphs) and line spacing (vertical space between lines of text) using scale factors.

Both values are relative to the font's default metrics:

The letter spacing is applied as a scale factor to the glyph's advance width.
The line spacing is applied as a scale factor to the glyph's advance height.

Parameters

[in]	letter	The scale factor for letter spacing. Values > 1.0 increase spacing, values < 1.0 decrease it. Must be greater than or equal to 0.0. (default: 1.0)
[in]	line	The scale factor for line spacing. Values > 1.0 increase line spacing, values < 1.0 decrease it. Must be greater than or equal to 0.0. (default: 1.0)

Since: 1.0

◆ text()

Result text ( const char * text )

noexcept

Assigns the given unicode text to be rendered.

This function sets the unicode string that will be displayed by the rendering system. The text is set according to the specified UTF encoding method, which defaults to UTF-8.

Parameters

[in] text The multi-byte text encoded with utf8 string to be rendered.

Since: 1.0

◆ type()

Type type ( ) const

overridevirtualnoexcept

Returns the ID value of this class.

This method can be used to check the current concrete instance type.

Returns: The class type ID of the Text instance.

Since: 1.0

Implements Paint.

◆ unload()

static Result unload ( const char * filename )

staticnoexcept

Unloads the specified scalable font data (TTF) that was previously loaded.

This function is used to release resources associated with a font file that has been loaded into memory.

Parameters

[in] filename The file name of the loaded font, including the path.

Return values

Result::InsufficientCondition Fails if the loader is not initialized.

Note: If the font data is currently in use, it will not be immediately unloaded.

See also: Text::load(const char* filename)

Since: 0.15

◆ wrap()

Result wrap ( TextWrap mode )

noexcept

Sets the text wrapping mode for this text object.

This method controls how the text is laid out when it exceeds the available space. The wrapping mode determines whether text is truncated, wrapped by character or word, or adjusted automatically. An ellipsis mode is also available for truncation with "...".

Parameters

[in] mode The wrapping strategy to apply. Default is TextWrap::None

See also: TextWrap

Since: 1.0

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ align()

◆ fill() [1/2]

◆ fill() [2/2]

◆ font()

◆ gen()

◆ italic()

◆ layout()

◆ load() [1/2]

◆ load() [2/2]

◆ outline()

◆ size()

◆ spacing()

◆ text()

◆ type()

◆ unload()

◆ wrap()