text—multi-line text rendering

class TextRenderer(font, options={}, pool=conf.DEFAULT_RESOURCE_POOL, res_mgr=conf.GAME.resources)[source]

Bases: object

Render text to a surface.

Parameters:
  • font – font filename to use, under conf.FONT_DIR.
  • options – dict giving rendering parameters. These act as default values in the same argument to render(). All options can be retrieved as properties of this instance (and all are guaranteed to exist), but cannot be changed.
  • pool – ResourceManager resource pool name to cache any loaded Pygame fonts in.
  • res_mgr – ResourceManager instance to use to load any Pygame fonts.
render(text, options={}, **kwargs) -> (surface, num_lines)[source]

Render text to a surface.

Parameters:
  • text – text to render; may contain line breaks to display separate lines.
  • options – dict giving rendering parameters; those omitted default to the value given in the options argument to the constructor, and then the values in option_defaults.
  • kwargs – options can also be passed as keyword arguments, with the option’s name as the argument’s name. If an option is given both in options and as a keyword argument, the keyword argument takes precedence.

Options available:

Parameters:
  • text_size – text size, in points.
  • colour – text colour, as taken by util.normalise_colour. Alpha seems to be unsupported by Pygame.
  • shadow – to draw a drop-shadow: (colour, offset) tuple, where offset is (x, y).
  • width – maximum width of returned surface (also see wrap). This excludes padding (pad).
  • just – if the text has multiple lines, justify: 0 = left, 1 = centre, 2 = right.
  • minimise – if width is set, treat it as a minimum instead of absolute width (that is, shrink the surface after, if possible).
  • line_spacing – space between lines, in pixels.
  • aa – whether to anti-alias the text.
  • bg – background colour.
  • pad – (left, top, right, bottom) padding in pixels. Can also be one number for all sides or (left_and_right, top_and_bottom). This treats shadow as part of the text.
  • wrap –

    text wrapping mode (only used if width is given); one of:

    • 'char' (default): wrap words and wrap within words if necessary.
    • 'word': wrap words only; raises ValueError if any words won’t fit on a single line.
    • 'none': don’t wrap: if width is given, allow text to fall off the end of the surface.
Returns:

surface is the pygame.Surface containing the rendered text and num_lines is the final number of lines of text.
get_info(text, options={}, **kwargs) -> (lines, text_size, sfc_size)[source]

Get results for render arguments without actually rendering.

Arguments are as taken by render().

Returns:
  • lines: a list of string lines the text would be split into.
  • text_size: the resulting (width, height) size of the text within
    the surface that would be returned, excluding any shadow.
  • sfc_size: the resulting size of the surface.

Like render(), raises ValueError if wrapping fails.

mk_options(options={}, **kwargs) → new_options[source]

Generate a full set of rendering options given an options dict.

Arguments are as taken by render().

Returns:The completed dict of rendering options, with defaults filled in.
normalise_options(options={})[source]

Normalise a (possibly incomplete) renderer options dict, in-place.

Arguments are as taken by render().

This involves making every option hashable and putting it in a standard format.