# ThorVG: Text

Textfinal
ThorVG

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

Inheritance diagram for Text:
[legend]
Collaboration diagram for Text:
[legend]

## Public Member Functions

Result | font (const char *name, float size, const char *style=nullptr) noexcept
| Sets the font properties for the text. More...
Result | text (const char *text) noexcept
| Assigns the given unicode text to be rendered. More...
Result | fill (uint8_t r, uint8_t g, uint8_t b) noexcept
| Sets the text color. More...
Result | fill (std::unique_ptr< Fill > f) noexcept
| Sets the gradient fill for all of the figures from the text. More...
Type | type () const noexcept override
| Returns the ID value of this class. More...
Public Member Functions inherited from Paint
Result | rotate (float degree) noexcept
| Sets the angle by which the object is rotated. More...
Result | scale (float factor) noexcept
| Sets the scale value of the object. More...
Result | translate (float x, float y) noexcept
| Sets the values by which the object is moved in a two-dimensional space. More...
Result | transform (const Matrix &m) noexcept
| Sets the matrix of the affine transformation for the object. More...
Matrix | transform () noexcept
| Gets the matrix of the affine transformation of the object. More...
Result | opacity (uint8_t o) noexcept
| Sets the opacity of the object. More...
Result | composite (std::unique_ptr< Paint > target, CompositeMethod method) noexcept
| Sets the composition target object and the composition method. More...
Result | clip (std::unique_ptr< Paint > clipper) noexcept
| Clip the drawing region of the paint object. More...
Result | blend (BlendMethod method) noexcept
| Sets the blending method for the paint object. More...
TVG_DEPRECATED Result | bounds (float *x, float *y, float *w, float *h) const noexcept
Result | bounds (float *x, float *y, float *w, float *h, bool transformed) const noexcept
| Gets the axis-aligned bounding box of the paint object. More...
Paint * | duplicate () const noexcept
| Duplicates the object. More...
uint8_t | opacity () const noexcept
| Gets the opacity value of the object. More...
CompositeMethod | composite (const Paint **target) const noexcept
| Gets the composition target object and the composition method. More...
TVG_DEPRECATED uint32_t | identifier () const noexcept

## Static Public Member Functions

static Result | load (const std::string &path) noexcept
| Loads a scalable font data (ttf) from a file. More...
static Result | load (const char *name, const char *data, uint32_t size, const std::string &mimeType="ttf", bool copy=false) noexcept
| Loads a scalable font data (ttf) from a memory block of a given size. More...
static Result | unload (const std::string &path) noexcept
| Unloads the specified scalable font data (TTF) that was previously loaded. More...
static std::unique_ptr< Text > | gen () noexcept
| Creates a new Text object. More...

## Additional Inherited Members

Public Attributes inherited from Paint
uint32_t | id = 0
| Unique ID of this instance. More...

## Detailed Description

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

Since
  0.15

## Member Function Documentation

## fill() [1/2]

Result fill | ( | std::unique_ptr< 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()

Since
  0.15

## font()

Result font | ( | const char * | name,
|  | float | size,
|  | const char * | style = `nullptr`
| ) |  |

noexcept

Sets the font properties for the text.

This function allows you to define the font characteristics used for text rendering. It sets the font name, size and optionally the style.

Parameters

  [in] | name | The name of the font. This should correspond to a font available in the canvas.
  [in] | size | The size of the font in points. This determines how large the text will appear.
  [in] | style | The style of the font. It can be used to set the font to 'italic'. If not specified, the default style is used. Only 'italic' style is supported currently.

Return values

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

Note
  Experimental API

## gen()

static std::unique_ptr<Text> gen | ( |  | ) |

staticnoexcept

Creates a new Text object.

Returns
  A new Text object.

Since
  0.15

## load() [1/2]

static Result load | ( | const char * | name,
|  | const char * | data,
|  | uint32_t | size,
|  | const std::string & | 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 `""`, and thorvg will attempt to figure it out.

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

Note
  0.15

## load() [2/2]

static Result load | ( | const std::string & | path | ) |

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] | path | The path to 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 std::string& path)

Since
  0.15

## 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.

Note
  Experimental API

## 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
  Experimental API

Implements Paint.

## unload()

static Result unload | ( | const std::string & | path | ) |

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] | path | The file path of the loaded font.

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 std::string& path)

Since
  0.15