pygame / docs / reST / ref / font.rst

Full commit


The font module allows for rendering TrueType fonts into a new Surface object. It accepts any UCS-2 character ('u0001' to 'uFFFF'). This module is optional and requires SDL_ttf as a dependency. You should test that :mod:`pygame.font` is available and initialized before attempting to use the module.

Most of the work done with fonts are done by using the actual Font objects. The module by itself only has routines to initialize the module and create Font objects with pygame.font.Font().

You can load fonts from the system by using the pygame.font.SysFont() function. There are a few other functions to help lookup the system fonts.

Pygame comes with a builtin default font. This can always be accessed by passing None as the font name.

To use the :mod:`pygame.freetype` based :mod:`pygame.ftfont` as :mod:`pygame.font` define the enviroment variable PYGAME_FREETYPE before the first import of :mod:`pygame`. :mod:`pygame.ftfont` is a :mod:`pygame.font` compatible module that passes all but one of the font module unit tests: it does not have the UCS-2 limitation of the SDL_ttf based font module, so fails to raise an exception for a code point greater than 'uFFFF'. If :mod:`pygame.freetype` is unavailable then the SDL_ttf font module will be loaded instead.

Load a new font from a given filename or a python file object. The size is the height of the font in pixels. If the filename is None the Pygame default font will be loaded. If a font cannot be loaded from the arguments given an exception will be raised. Once the font is created the size cannot be changed.

Font objects are mainly used to render text into new Surface objects. The render can emulate bold or italic features, but it is better to load from a font with actual italic or bold glyphs. The rendered text can be regular strings or unicode.