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)[source]¶

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')[source]¶

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)[source]¶

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')[source]¶

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()[source]¶

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)[source]¶

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

family_name¶

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

Type:	str

style_name¶

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

Type:	str

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)[source]¶

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()[source]¶: Closes all fonts opened by the class.

add(font_path, alias=None, size=None, index=0)[source]¶

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`

color¶

The color to use for rendering text.

Type:	`Color`

bg_color¶

The background color to use for rendering.

Type:	`Color`

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)[source]¶

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`