Source

pygame / docs / reST / ref / freetype.rst

Full commit

:mod:`pygame.freetype`

The :mod:`pygame.freetype` module is a replacement for :mod:`pygame.font`. It has all of the functionality of the original, plus many new features. Yet is has absolutely no dependencies on the SDL_ttf library. It is implemented directly on the FreeType 2 library. The :mod:`pygame.freetype` module is not itself backward compatible with :mod:`pygame.font`. Instead, use the :mod:`pygame.ftfont` module as a drop-in replacement for :mod:`pygame.font`.

All font file formats supported by FreeType can be rendered by :mod:`pygame.freetype`, namely TTF, Type1, CFF, OpenType, SFNT, PCF, FNT, BDF, PFR and Type42 fonts. All glyphs having UTF-32 code points are accessible (see :attr:`ucs4`).

Most work on fonts is done using :class:`Font` instances. The module itself only has routines for initialization and creation of :class:`Font` objects. You can load fonts from the system using the :func:`SysFont` function.

Extra support of bitmap fonts is available. Available bitmap sizes can be listed (see :meth:`Font.get_sizes`). For bitmap only fonts :class:`Font` can set the size for you (see the :ref:`Font class size argument <freetype-font-size-argument>`).

For now undefined character codes are replaced with the .notdef (not defined) character. How undefined codes are handled may become configurable in a future release.

Pygame comes with a builtin default font. This can always be accessed by passing None as the font name to the :class:`Font` constructor.

Extra rendering features available to :class:`pygame.freetype.Font` are direct to surface rendering (see :meth:`Font.render_to`), character kerning (see :attr:`Font.kerning`), vertical layout (see :attr:`Font.vertical`), rotation of rendered text (see :attr:`rotation`), and the strong style (see :attr:`Font.strong`). Some properties are configurable, such as strong style strength (see :attr:`Font.strength`) and underline positioning (see :attr:`underline_adjustment`). Text can be positioned by the upper right corner of the text box or by the text baseline (see :attr:`Font.origin`). Finally, a font's vertical and horizontal size can be adjusted separately (see :attr:`Font.size`). The :mod:`pygame.examples.freetype` example (:func:`pygame.examples.freetype_misc.main`) shows these features in use.

The Pygame package does not import :mod:`freetype` automatically when loaded. This module must be imported explicitly to be used.

import pygame
import pygame.freetype

The :mod:`freetype` module is new in Pygame 1.9.2

Argument file can be either a string representing the font's filename, a file-like object containing the font, or None; if None, the default, Pygame, font is used.

Optionally, a size argument may be specified to set the default size in points, which determines the size of the rendered characters. The size can also be passed explicitly to each method call. Because of the way the caching system works, specifying a default size on the constructor doesn't imply a performance gain over manually passing the size on each function call. If the font is bitmap and no size is given, the default size is set to the first available size for the font.

If the font file has more than one font, the font to load can be chosen with the index argument. An exception is raised for an out-of-range font index value.

The optional resolution argument sets the pixel size, in dots per inch, for use in scaling glyphs for this Font instance. If 0 then the default module value, set by :meth:`freetype.init`, is used. The Font object's resolution can only be changed by re-initializing the Font instance.

The optional ucs4 argument, an integer, sets the default text translation mode: 0 (False) recognize UTF-16 surrogate pairs, any other value (True), to treat Unicode text as UCS-4, with no surrogate pairs. See :attr:`Font.ucs4`.