thorvg_python.paint.text¶

Classes¶

`Text`	Text API

Module Contents¶

class thorvg_python.paint.text.Text(engine: thorvg_python.engine.Engine, paint: thorvg_python.base.PaintPointer | None = None)¶

Bases: thorvg_python.paint.Paint

Text API

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

engine¶

thorvg_lib¶

_new() → thorvg_python.base.PaintPointer¶

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.
Return type:¶: thorvg_python.base.PaintPointer

Added in version 0.15.

Note

You need not call this method as it is auto called when initializing Text().

set_font(name: str | None = None) → thorvg_python.base.Result¶

Sets the font family for the text.

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

Parameters:¶

name: str | None = None¶: The name of the font. This should match a font available through the canvas backend. If set to None, ThorVG will attempt to select a fallback font available on the engine.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the paint argument.
Result.INSUFFICIENT_CONDITION The specified name cannot be found.

Note

This function only sets the font family name. Use size() to define the font size.

Note

If the name is not specified, ThorVG will select an available fallback font.

See also

Text.set_size()

See also

Engine.font_load()

Added in version 1.0.

set_size(size: float) → thorvg_python.base.Result¶

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:¶

size : float¶: The font size in points. Must be greater than 0.0.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the paint argument.
Result.INVALID_ARGUMENT if the size is less than or equal to 0.

Return type:¶

thorvg_python.base.Result

Note

Use this function in combination with font() to fully define text appearance.

Note

Fractional sizes (e.g., 12.5) are supported for sub-pixel rendering and animations.

See also

Text.set_font()

Added in version 1.0.

set_text(utf8: str) → thorvg_python.base.Result¶

Assigns the given unicode text to be rendered.

This function sets the unicode text 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:¶

utf8 : str¶: The multi-byte text encoded with utf8 string to be rendered.

Return type:¶

Result

See also

Text.get_text()

get_text() → str¶

Returns the currently assigned unicode text.

This function retrieves the unicode string that is currently set for rendering. The returned text is encoded in UTF-8.

Returns:¶: The UTF-8 encoded multi-byte text string.
Return type:¶: str

See also

Text.set_text()

Note

Experimental API

align(x: float, y: float) → thorvg_python.base.Result¶

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:¶

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

Added in version 1.0.

See also

Text.layout()

layout(w: float, h: float) → thorvg_python.base.Result¶

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 Text.align() acts as an anchor on that axis.

Parameters:¶

w : float¶: Layout width in user space. Use 0 for no horizontal constraint. (Default is 0)
h : float¶: 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().

Added in version 1.0.

See also

Text.align()

See also

Text.spacing()

wrap_mode(mode: thorvg_python.base.TextWrap) → thorvg_python.base.Result¶

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:¶

mode : thorvg_python.base.TextWrap¶: The wrapping strategy to apply. Default is NONE.

See also

TextWrap

See also

Text.line_count()

Added in version 1.0.

line_count() → int¶

Returns the number of text lines.

This function retrieves the number of lines generated after applying text layout and wrapping. The returned value reflects the current wrapping configuration set by thorvg_python.Text.wrap_mode(). The line count is also increased by explicit line feed characters (’

‘) contained in the text.

return:

The total number of lines

rtype:

int

See also

Text.wrap_mode()

Note

Experimental API

spacing(letter: float, line: float) → thorvg_python.base.Result¶

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:¶

letter : float¶: 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)
line: float¶: 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)

Added in version 1.0.

set_italic(shear: float) → thorvg_python.base.Result¶

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:¶

shear : float¶: 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]. Recommended value is 0.18.

Returns:¶

Result.INVALID_ARGUMENT A None passed as the paint argument.

Return type:¶

thorvg_python.base.Result

Note

The shear factor will be clamped to the valid range if it exceeds the limits.

Note

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.set_font()

Added in version 1.0.

set_outline(width: float, r: int, g: int, b: int) → thorvg_python.base.Result¶

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 : width¶: The width of the outline. Must be positive value. (The default is 0)
r : int¶: Red component of the outline color (0–255).
g : int¶: Green component of the outline color (0–255).
b : int¶: Blue component of the outline color (0–255).

Note

To disable the outline, set width to 0.

See also

Text.set_fill_color() to set the main text fill color.

Added in version 1.0.

set_color(r: int, g: int, b: int) → thorvg_python.base.Result¶

Sets the text solid color.

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

Returns:¶: Result.INVALID_ARGUMENT A None passed as the paint argument.
Return type:¶: thorvg_python.base.Result

Note

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

See also

Text.set_font()

See also

Text.set_outline()

Added in version 0.15.

set_gradient(gradient: thorvg_python.gradient.Gradient) → thorvg_python.base.Result¶

Sets the gradient fill for the text.

Parameters:¶

gradient : thorvg.base.GradientPointer¶: The linear or radial gradient fill

Returns:¶

Result.INVALID_ARGUMENT A None passed as the paint argument.
Result.MEMORY_CORRUPTION An invalid GradientPointer.

Return type:¶

thorvg_python.base.Result

Note

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

See also

Text.set_font()

Added in version 0.15.

get_text_metrics() → tuple[thorvg_python.base.Result, thorvg_python.base.TextMetrics]¶

Retrieves the layout metrics of the text object.

Fills the provided TextMetrics structure with the font layout values of this text object, such as ascent, descent, linegap, and line advance.

The returned values reflect the font size applied to the text object, but do not include any transformations (e.g., scale, rotation, or translation).

Returns:¶: A TextMetrics structure filled with the resulting values.
Return type:¶: thorvg_python.base.TextMetrics
Returns:¶: Result.INSUFFICIENT_CONDITION if no font or size has been set yet.
Return type:¶: thorvg_python.base.Result

See also

TextMetrics

Note

Experimental API

get_glyph_metrics(ch: str) → tuple[thorvg_python.base.Result, thorvg_python.base.GlyphMetrics]¶

Retrieves the layout metrics of a glyph in the text object.

Fills the provided @ref Tvg_Glyph_Metrics structure with the horizontal layout values of the specified glyph, such as advance, left-side bearing, and bounding box.

The returned values reflect the font size applied to the text object, but do not include any transformations (e.g., scale, rotation, or translation).

The input character must be a single UTF-8 encoded character.

Returns:¶: A GlyphMetrics structure filled with the resulting values.
Return type:¶: thorvg_python.base.GlyphMetrics
Returns:¶: Result.INSUFFICIENT_CONDITION if no font or size has been set yet. RESULT.INVALID_ARGUMENT if the given character is invalid or not supported.
Return type:¶: thorvg_python.base.Result

See also

GlyphMetrics

Note

Currently, ThorVG only supports horizontal text layout.

Note

Experimental API

font_load(path: str) → thorvg_python.base.Result¶

Loads a scalable font data 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:¶

path : str¶: The path to the font file.

Returns:¶

Result.INVALID_ARGUMENT An invalid path passed as an argument.
Result.NOT_SUPPORTED When trying to load a file with an unknown extension.

Return type:¶

thorvg_python.base.Result

See also

Engine.font_unload()

Added in version 0.15.

font_load_data(name: str, data: bytes, mimetype: str | None, copy: bool) → thorvg_python.base.Result¶

Loads a scalable font data 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:¶

name : str¶: The name under which the font will be stored and accessible (e.x. in a Text.set_font API).
data : bytes¶: A pointer to a memory location where the content of the font data is stored.
mimetype : str¶: Mimetype or extension of font data. In case a None or an empty “” value is provided the loader will be determined automatically.
copy : bool¶: If true the data are copied into the engine local buffer, otherwise they are not (default).

Returns:¶

Result.INVALID_ARGUMENT If no name is provided or if size is zero while data points to a valid memory location.
Result.NOT_SUPPORTED When trying to load a file with an unknown extension.
Result.INSUFFICIENT_CONDITION When trying to unload the font data that has not been previously loaded.

Return type:¶

thorvg_python.base.Result

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 None as data.

Added in version 0.15.

font_unload(path: str) → thorvg_python.base.Result¶

Unloads the specified scalable font data that was previously loaded.

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

Parameters:¶

path : str¶: The path to the loaded font file.

Returns:¶

Result.INSUFFICIENT_CONDITION The loader is not initialized.

Return type:¶

thorvg_python.base.Result

Note

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

See also

Engine.font_load()

Added in version 0.15.