Text

class sfml.Font

The constructor will raise NotImplementedError if called. Use class methods like load_from_file() or load_from_memory() instead.

The following types of fonts are supported: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.

Once it’s loaded, you can retrieve three types of information about the font:

  • Global metrics, such as the line spacing.
  • Per-glyph metrics, such as bounding box or kerning.
  • Pixel representation of glyphs.

Fonts alone are not very useful: they hold the font data but cannot make anything useful of it. To do so you need to use the Text class, which is able to properly output text with several options such as character size, style, color, position, rotation, etc. This separation allows more flexibility and better performances: a font is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other hand, a Text is a lightweight object which can combine the glyphs data and metrics of a font to display any text on a render target. Note that it is also possible to bind several text instances to the same font.

Usage example:

# Load a font from a file, catch PySFMLException
# if you want to handle the error
font = sfml.Font.load_from_file('arial.ttf')

# Create a text which uses our font
text1 = sfml.Text()
text1.font = font
text1.character_size = 30
text1.style = sfml.Text.REGULAR

# Create another text using the same font, but with different parameters
text2 = sfml.Text()
text2.font = font
text2.character_size = 50
text1.style = sfml.Text.ITALIC

Apart from loading font files, and passing them to instances of Text, you should normally not have to deal directly with this class. However, it may be useful to access the font metrics or rasterized glyphs for advanced usage.

classmethod load_from_file(filename)

Load the font from filename, and return a new font object.

Note that this class method knows nothing about the standard fonts installed on the user’s system, so you can’t load them directly.

PySFMLException is raised if an error occurs.

classmethod load_from_memory(bytes data)

Load the font from the string/bytes object (for Python 2/3, respectively) and return a new font object.

Warning

SFML cannot preload all the font data in this function, so you should keep a reference to the data object as long as the font is used.

classmethod load_from_stream(InputStream stream)

Load the font from a custom stream.

get_glyph(int code_point, int character_size, bool bold)

Return a glyph corresponding to code_point and character_size.

get_texture(int character_size)

Retrieve the texture containing the loaded glyphs of a certain size.

The contents of the returned texture changes as more glyphs are requested, thus it is not very relevant. It is mainly used internally by Text.

get_kerning(int first, int second, int character_size)

Return the kerning offset of two glyphs.

The kerning is an extra offset (negative) to apply between two glyphs when rendering them, to make the pair look more “natural”. For example, the pair “AV” have a special kerning to make them closer than other characters. Most of the glyphs pairs have a kerning offset of zero, though.

get_line_spacing(int character_size)

Get the line spacing.

Line spacing is the vertical offset to apply between two consecutive lines of text.

class sfml.Glyph

A glyph is the visual representation of a character. Glyph structure provides the information needed to handle the glyph:

  • its coordinates in the font’s texture,
  • its bounding rectangle,
  • the offset to apply to get the starting position of the next glyph.
advance

Offset to move horizontically to the next character.

bounds

Bounding rectangle of the glyph as an IntRect, in coordinates relative to the baseline.

texture_rect

Texture coordinates of the glyph inside the font’s texture, as an IntRect.

class sfml.Text(string, font[, character_size=0])

This class inherits Transformable.

string can be a bytes/str/unicode object. SFML will internally store characters as 32-bit integers. A bytes object (str in Python 2) will end up being interpreted by SFML as an “ANSI string” (cp1252 encoding). A unicode object (str in Python 3) will be interpreted as 32-bit code points.

Text is a drawable class that allows to easily display some text with custom style and color on a render target.

It inherits all the functions from Transformable: position, rotation, scale, origin. It also adds text-specific properties such as the font to use, the character size, the font style (bold, italic, underlined), the global color and the text to display of course. It also provides convenience functions to calculate the graphical size of the text, or to get the global position of a given character.

Text works in combination with the Font class, which loads and provides the glyphs (visual characters) of a given font. The separation of Font and Text allows more flexibility and better performances: a Font is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other hand, a Text is a lightweight object which can combine the glyphs data and metrics of a Font to display any text on a render target.

Usage example:

# Declare and load a font
font = sfml.Font.loadFromFile('font.ttf')

# Create a text
text = sfml.Text('hello')
text.font = font
text.character_size = 30
text.style = sfml.Text.BOLD
text.color = sfml.Color.RED

# Draw it
window.draw(text)
character_size

The size of the characters, pixels. The default size is 30.

color

The global color of the text. The default color is opaque white.

font

The text’s font.

global_bounds

Read-only. The global bounding rectangle of the entity, as a FloatRect. The returned rectangle is in global coordinates, which means that it takes in account the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the sprite in the global 2D world’s coordinate system.

local_bounds

Read-only. The local bounding rectangle of the entity, as a FloatRect. The returned rectangle is in local coordinates, which means that it ignores the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the entity in the entity’s coordinate system.

string

This attribute can be set as either a str or unicode object. The value retrieved will be either str or unicode as well, depending on what type has been set before. See Text for more information.

style

Can be one or more of the following:

  • sfml.Text.REGULAR
  • sfml.Text.BOLD
  • sfml.Text.ITALIC
  • sfml.Text.UNDERLINED

Example:

text.style = sfml.Text.BOLD | sfml.Text.ITALIC
find_character_pos(int index)

Return the position of the index-th character. This method computes the visual position of a character from its index in the string. The returned position is in global coordinates (translation, rotation, scale and origin are applied). If index is out of range, the position of the end of the string is returned.