# sdl2.ext.ttf - Rendering Text With TrueType Fonts

The `sdl2.ext.ttf` module provides the `FontTTF` class, which provides a friendly and Pythonic API for font rendering based around the SDL_ttf library. SDL_ttf can be installed as a Python dependency with `pysdl2-dll` on platforms that support it).

Additionally, this module provides the deprecated `FontManager` class, which provides a different (and less featureful) API for rendering text using SDL_ttf.

class sdl2.ext.ttf.FontTTF(font, size, color, index=0, height_chars=None)

  A class for rendering text with a given TrueType font.

  This class loads a TrueType or OpenType font using the SDL_ttf library and allows the user to render text with it in various sizes and colors.

  To simplify rendering text with different font sizes and colors, this class allows users to define font styles (e.g. ‘instructions’, ‘error’, ‘title’, etc.) using `add_style()`, which can then be used by name with the `render_text()` method.

  By default, the `FontTTF` class defines font sizes in points (pt), a common unit of font size used by many libraries and text editors. However, you can also define font sizes in units of pixel height (px), i.e. the ascent height of the font’s tallest alphanumeric ASCII character. This is done by calculating each font’s px-to-pt scaling factor on import, meaning that some rounding error may occur. If using a font that does not include all alphanumeric ASCII characters (A-Z, a-z, 0-9) or wanting to scale the maximum pixel height to a different subset of characters (e.g. just 0-9 digits), you will need to specifiy a custom ‘height_chars’ string when creating the font object.

  Note

  If loading a font from an SDL RWops file object, you must not free the file object until you are done with the font. Otherwise, SDL_ttf will try to render with a closed font and hard-crash Python.

  Parameters:

    - font (str or `SDL_RWops`) – The relative (or absolute) path to the font to load, or an SDL file object containing the font data.

    - size (int or str) – The default size for the font, either as an integer (assumed to be in pt) or as a string specifying the unit of size (e.g. ‘12pt’ or ‘22px’).

    - color (Color or tuple) – The default color to use for rendering text. Defaults to white if not specified.

    - index (int, optional) – The index of the font face to load if the font file contains multiple faces. Defaults to 0 (first face in the file) if not specified.

    - height_chars (str, optional) – The set of font characters to use for calculating the maximum height (in pixels) of the font for

  get_ttf_font(style='default')

    Returns the base `TTF_Font` for a given font style.

    This method provides access to the base ctypes object for each font style so that they can be used with the full set of `sdlttf` functions.

    Parameters:

      style (str, optional) – The font style for which the base ctypes font object will be retrieved. Defaults to the ‘default’ style if not specified.

    Returns:

      The base ctypes font for the style.

    Return type:

      `TTF_Font`

  add_style(name, size, color, bg_color=None)

    Defines a named font style for the current font.

    Currently, a font style defines a font size, color, and background color combination to use for rendering text. Additional style attributes may be added in future releases.

    Parameters:

      - name (str) – The name of the new font style (e.g. ‘title’).

      - size (int or str) – The font size for the style, either as an integer (assumed to be in pt) or as a string specifying the unit of size (e.g. ‘12pt’ or ‘22px’).

      - color (Color) – The font color for the style.

      - bg_color (Color, optional) – The background surface color for the style. Defaults to a fully-transparent background if not specified.

  render_text(text, style='default', line_h=None, width=None, align='left')

    Renders a string of text to a new surface.

    If a newline character (`\n`) is encountered in the string, it will be rendered as a line break in the rendered text. Additionally, if a surface width is specified, any lines of text that exceed the width of the surface will be wrapped. Multi-line text can be left-aligned (the default), right-aligned, or centered, and the spacing between lines can be modified using the line_h argument.

    Line heights can be specified in pixels (e.g. `20` or `'20px'`) or as percentages of the TTF-suggested line spacing for the font (e.g. `'150%'`).

    Parameters:

      - text (str) – The string of text to render to the target surface.

      - style (str, optional) – The font style with which to render the given string. Defaults to the ‘default’ style if not specified.

      - line_h (int or str, optional) – The line height to use for each line of the rendered text, either in pixels or as a percentage of the font’s suggested line height. If not specified, the suggested line height for the font will be used.

      - width (int, optional) – The width (in pixels) of the output surface. If a line of text exceeds this value, it will be automatically wrapped to fit within the specified width. Defaults to `None`.

      - align (str, optional) – The alignment of lines of text for multi-line strings. Can be ‘left’ (left-aligned), ‘right’ (right-aligned), or ‘center’ (centered). Defaults to ‘left’.

    Returns:

      A 32-bit ARGB surface containing the rendered text.

    Return type:

      `SDL_Surface`

  close()

    Cleanly closes the font and frees all associated memory.

    This method should be called when you are finished with the font to free the resources taken up by the font and its styles. Once this method has been called, the font can no longer be used.

  contains(c)

    Checks whether a given character exists within the font.

    Parameters:

      c (str) – The glpyh (i.e. character) to check for within the font.

    Returns:

      `True` if the font contains the glpyh, otherwise `False`.

    Return type:

      bool

  property family_name

    The family name (e.g. “Helvetica”) of the loaded font.

    Type:

      str

  property style_name

    The style name (e.g. “Bold”) of the loaded font.

    Type:

      str

  property is_fixed_width

    Whether the current font face is fixed-width (i.e. monospaced).

    If `True`, all characters in the current font have the same width.

    Type:

      bool

class sdl2.ext.ttf.FontManager(font_path, alias=None, size=16, color=Color(r=255, g=255, b=255, a=255), bg_color=Color(r=0, g=0, b=0, a=255), index=0)

  A class for managing and rendering TrueType fonts.

  Note

  This class is has been deprecated in favor of the more flexible `FontTTF` class.

  This class provides a basic wrapper around the SDL_ttf library. One font path must be given to initialise the FontManager.

  The first face is always at index 0. It can be used for TTC (TrueType Font Collection) fonts.

  Parameters:

    - font_path (str) – The relative (or absolute) path to the font to load.

    - alias (str, optional) – The name to give the font within the FontManager. Defaults to the font filename if not specified.

    - size (int, optional) – The size (in pt) at which to load the default font. Defaults to 16pt if not specified.

    - color (Color) – The default font rendering color. Defaults to opaque white if not specified.

    - bg_color (Color, optional) – The default background surface color. Defaults to a fully-transparent background if not specified.

    - index (int, optional) – The index of the font face to load if the font file contains multiple faces. Defaults to 0 (first face in the file) if not specified.

  size

    The default font size in pt.

    Type:

      int

  close()

    Closes all fonts opened by the class.

  add(font_path, alias=None, size=None, index=0)

    Adds a font to the `FontManager`.

    Parameters:

      - font_path (str) – The relative (or absolute) path to the font to load.

      - alias (str, optional) – The name to give the font within the FontManager. Defaults to the font filename if not specified.

      - size (int, optional) – The size (in pt) at which to load the font. Defaults to the FontManager’s default size if not specified.

      - index (int, optional) – The index of the font face to load if the font file contains multiple faces. Defaults to 0 (first face in the file) if not specified.

    Returns:

      A pointer to the ctypes font object for the added font.

    Return type:

      `TTF_Font`

  property color

    The color to use for rendering text.

    Type:

      `Color`

  property bg_color

    The background color to use for rendering.

    Type:

      `Color`

  property default_font

    The name of the default font. Must be set to the alias of a currently-loaded font.

    Type:

      str

  render(text, alias=None, size=None, width=None, color=None, bg_color=None, **kwargs)

    Renders text to a surface.

    Parameters:

      - text (str) – The text to render.

      - alias (str, optional) – The alias of the font to use for rendering the text. Defaults to the FontManager’s default font if not specified.

      - size (int, optional) – The size (in pt) at which to render the font. Defaults to the FontManager’s default size if not specified.

      - width (int, optional) – The width (in pixels) of the output surface. If a line of text exceeds this value, it will be automatically wrapped to fit within the specified width. Defaults to `None`.

      - color (Color) – The font rendering color. Defaults to the FontManager’s default color if not specified.

      - bg_color (Color, optional) – The background surface color. Defaults to the FontManager’s default background color if not specified.

    Returns:

      A 32-bit ARGB surface containing the rendered text.

    Return type:

      `SDL_Surface`