Fonts

imlib2.auto_set_font_path()

Automatically add to Imlib2’s font path any directory known by FontConfig to contain TrueType fonts.

Warning

This function spawns fc-list which can take some time to execute with a cold cache.

imlib2.add_font_path(path)

Add the given path to the list of paths to scan when loading fonts.

Parameter:path (str) – directory containing fonts

imlib2.load_font(font, size)

Load a TrueType font from the first directory in the font path that contains the specified font.

Parameters:

• font (str) – the name of the font to load, e.g. ‘arial’
• size – the size in pixels of the font

Raises:

IOError if the font could not be loaded.

Returns:

Font object

imlib2.get_font_style_geometry(style)

Return the additional size in pixels needed for the given style.

Parameter:style – one of the TEXT_STYLE constants Returns:6-tuple (left, top, right, bottom, width, height)

Width and height are included as a convenience, but they are just the sum of left+right and top+bottom.

On Python 2.6 and later this function will return a named tuple.

Text Styles

These constants are used with imlib2.Image.draw_text() and imlib2.Font.set_style().

imlib2.TEXT_STYLE_PLAIN

No special styling.

imlib2.TEXT_STYLE_SHADOW

Draw text with a lower-right 1-pixel shadow. The shadow color is specified by the shadow attribute.

imlib2.TEXT_STYLE_SOFT_SHADOW

Draw text with a lower-right blurred 5-pixel shadow, offset up and left by 1 pixel. The shadow color is specified by the shadow attribute.

imlib2.TEXT_STYLE_FAR_SHADOW

Draw text with a lower-right 2-pixel shadow. The shadow color is specified by the shadow attribute.

imlib2.TEXT_STYLE_FAR_SOFT_SHADOW

Draw text with a lower-right blurred 5-pixel shadow. The shadow color is specified by the shadow attribute.

imlib2.TEXT_STYLE_OUTLINE

Draw text with a 1-pixel outline. The outline color is specified by the outline attribute.

imlib2.TEXT_STYLE_OUTLINE_SHADOW

Draw text with a 1-pixel outline and a lower-right 1-pixel shadow. The outline and shadow and colors are specified by the outline and shadow attributes respectively.

imlib2.TEXT_STYLE_SOFT_OUTLINE

Draw text with a blurred 2-pixel outline. The outline color is specified by the outline attribute.

imlib2.TEXT_STYLE_OUTLINE_SOFT_SHADOW

Draw text with a 1-pixel outline and a lower-right blurred 5-pixel shadow. The outline and shadow and colors are specified by the outline and shadow attributes respectively.

imlib2.TEXT_STYLE_GLOW

Draw text with a double outline. The outer and inner outline colors are specified by the glow and glow2 attributes respectively.

Font Objects

class imlib2.Font(fontdesc, color='#ffff')

Font class representing an Imlib2 Font object. Font objects may be assigned to Image objects via their font property to control font, size, and style to draw_text() operations.

Parameters:

• fontdesc (str or 2-tuple) – a description of the font either in the form name/size, where name is the filename of a .ttf file in the font path, or a tuple in the form ('name', size).
• color – the default color for text rendered with this font, specified as any value that could be passed by normalize_color().

Font paths can be registered by calling add_font_path() or auto_set_font_path().

Once a Font object is instantiated the font name cannot be changed, however the size can be changed by adjusting the size property.

Synopsis

Class Hierarchy

imlib2.Font

Methods

get_style_geometry()	Return the additional size in pixels needed for the current style.
get_text_size()	Calculate font metrics (size and advance) for the specified text when rendered by the current font.
set_color()	Deprecated: use the color property instead.
set_size()	Deprecated: use the size property instead.
set_style()	Set the default text style for future text rendered with this font.

Properties

ascent	read-only	The number of pixels from the baseline to the top of the text for nominal characters.
color	read/write	A 4-tuple containing the red, green, blue, and alpha values from 0-255.
descent	read-only	The number of pixels from the baseline to the bottom of the text for nominal characters.
max_ascent	read-only	The maximum ascent for all glyphs in the font.
max_descent	read-only	The maximum descent for all glyphs in the font.
name	read-only	The file name of the font (without the .ttf extension), e.g. VeraBd
size	read/write	The size in pixels of the font.

Signals

This class has no signals.

Methods

get_style_geometry()

Return the additional size in pixels needed for the current style.

See get_font_style_geometry() for more details.

get_text_size(text)

Calculate font metrics (size and advance) for the specified text when rendered by the current font.

Parameter:text (str or unicode) – the text whose metrics to calculate Returns:4-tuple (width, height, horizontal advance, vertical advance)

set_color(color)

Deprecated: use the color property instead.

set_size(size)

Deprecated: use the size property instead.

set_style(style, shadow='#000f', outline='#000f', glow='#000f', glow2='#000f')

Set the default text style for future text rendered with this font.

Parameters:

• style (a TEXT_STYLE constant) – the text style
• shadow – color used for any shadow styles
• outline – color used for any outline styles
• glow – color used for TEXT_STYLE_GLOW
• glow2 – color used for TEXT_STYLE_GLOW

Properties

ascent

The number of pixels from the baseline to the top of the text for nominal characters.

color

A 4-tuple containing the red, green, blue, and alpha values from 0-255.

This property may be set to any value accepted by normalize_color(), but it will always be converted to a 4-tuple.

descent

The number of pixels from the baseline to the bottom of the text for nominal characters.

max_ascent

The maximum ascent for all glyphs in the font.

max_descent

The maximum descent for all glyphs in the font.

name

The file name of the font (without the .ttf extension), e.g. VeraBd

size

The size in pixels of the font.