Python API reference

Creating and updating Pango objects from Cairo

Contexts

pangocairocffi.create_context(cairo_context: Context) → Context

Creates a context object set up to match the current transformation and target surface of the Cairo context. This context can then be used to create a layout using pangocffi.Layout().

This function is a convenience function that creates a context using the default font map, then updates it to cairo_context. If you just need to create a layout for use with cairo_context and do not need to access PangoContext directly, you can use create_layout() instead.

Parameters:

cairo_context – a Cairo context

Returns:

a Pango context

pangocairocffi.update_context(cairo_context: Context, pango_context: Context) → None

Updates a PangoContext previously created for use with Cairo to match the current transformation and target surface of a Cairo context. If any layouts have been created for the context, it’s necessary to call pango_layout_context_changed() on those layouts.

Parameters:

  • cairo_context – a Cairo context

  • pango_context – a Pango context, from a pango-cairo font map

Layouts

pangocairocffi.create_layout(cairo_context: Context) → Layout

Creates a layout object set up to match the current transformation and target surface of the Cairo context. This layout can then be used for text measurement with functions like get_size() or drawing with functions like show_layout(). If you change the transformation or target surface for cairo_context, you need to call update_layout()

This function is the most convenient way to use Cairo with Pango, however it is slightly inefficient since it creates a separate PangoContext object for each layout. This might matter in an application that was laying out large amounts of text.

Parameters:

cairo_context – a Cairo context

Returns:

a Pango layout

pangocairocffi.update_layout(cairo_context: Context, layout: Layout) → None

Updates the private Pango Context of a Pango Layout created with create_layout() to match the current transformation and target surface of a Cairo context.

Parameters:

  • cairo_context – a Cairo context

  • layout – a Pango layout

Rendering Pango objects with Cairo

Drawing on the cairo context

pangocairocffi.show_layout(cairo_context: Context, layout: Layout) → None

Draws a Pango Layout in the specified cairo context. The top-left corner of the PangoLayout will be drawn at the current point of the cairo context.

Parameters:

  • cairo_context – a Cairo context

  • layout – a Pango layout

pangocairocffi.show_error_underline(cairo_context: Context, x: float, y: float, width: float, height: float) → None

Draw a squiggly line in the specified cairo context that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. (The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle)

Parameters:

  • cairo_context – a Cairo context

  • x – The X coordinate of one corner of the rectangle

  • y – The Y coordinate of one corner of the rectangle

  • width – Non-negative width of the rectangle

  • height – Non-negative height of the rectangle

pangocairocffi.show_glyph_item(cairo_context: Context, text: str, glyph_item: GlyphItem) → None

Draws the glyphs in glyph_item in the specified cairo context, embedding the text associated with the glyphs in the output if the output format supports it (PDF for example), otherwise it acts similar to show_glyph_string().

The origin of the glyphs (the left edge of the baseline) will be drawn at the current point of the cairo context.

Note that text is the start of the text for layout, which is then indexed by glyph_item->item->offset.

Parameters:

  • cairo_context – a Cairo context

  • text – the UTF-8 text that glyph_item refers to

  • glyph_item – a Pango glyph item

Adding text to cairo’s current path

pangocairocffi.layout_path(cairo_context: Context, layout: Layout) → None

Adds the text in a Pango.Layout to the current path in the specified cairo context. The top-left corner of the Pango.Layout will be at the current point of the cairo context.

Parameters:

  • cairo_context – a Cairo context

  • layout – a Pango layout

pangocairocffi.error_underline_path(cairo_context: Context, x: float, y: float, width: float, height: float) → None

Add a squiggly line to the current path in the specified cairo context that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. (The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle)

Parameters:

  • cairo_context – a Cairo context

  • x – The X coordinate of one corner of the rectangle

  • y – The Y coordinate of one corner of the rectangle

  • width – Non-negative width of the rectangle

  • height – Non-negative height of the rectangle

PangoCairo Fonts

PangoCairo Font Functions

pangocairocffi.set_resolution(context: Context, dpi: float) → None

Sets the resolution for the context. This is a scale factor between points specified in a PangoFontDescription and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3).

Parameters:

  • context – a Pango context

  • dpi – the resolution in “dots per inch”. (Physical inches aren’t actually involved; the terminology is conventional.) A 0 or negative value means to use the resolution from the font map.

pangocairocffi.get_resolution(context: Context) → float

Returns the resolution for the Pango context.

Parameters:

context – a Pango context

Returns:

the resolution in “dots per inch”. A negative value will be returned if no resolution has previously been set.

pangocairocffi.set_font_options(context: Context, options: _CDataBase | None) → None

Sets the font options used when rendering text with this context. These options override any options that pango_cairo_update_context() derives from the target surface.

Parameters:

  • context – a Pango context

  • options – a cairo_font_options_t, or None to unset any previously set options.

pangocairocffi.get_font_options(context: Context) → _CDataBase | None

Retrieves any font rendering options previously set with pango_cairo_context_set_font_options(). This function does not report options that are derived from the target surface by pango_cairo_update_context()

Parameters:

context – a Pango Context

Returns:

a cairo_font_options_t pointer previously set on the context, otherwise None.

PangoCairo Font Map

class pangocairocffi.PangoCairoFontMap

API not fully implemented yet.

Todo: This class should extend FontMap from pangocffi once it is implemented. This class in theory should be able to inherit the functions listed here: https://developer.gnome.org/pango/stable/pango-Fonts.html, with the prefix pango_font_map_X. For example: create_context, load_font, load_fontset, list_families.

PangoCairoFontMap is an interface exported by font maps for use with Cairo. The actual type of the font map will depend on the particular font technology Cairo was compiled to use.

property pointer: _CDataBase

Returns the pointer to the font map

Returns:

the pointer to the font map.

classmethod from_pointer(pointer: _CDataBase) → PangoCairoFontMap

Instantiates a PangoCairoFontMap from a pointer.

Returns:

the pango-cairo font map.

classmethod get_default() → PangoCairoFontMap

Gets a default PangoCairoFontMap to use with Cairo.

Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use; You generally should only use the PangoFontMap and PangoCairoFontMap interfaces on the returned object.

The default Cairo fontmap can be changed by using PangoCairoFontMap.set_default(). This can be used to change the Cairo font backend that the default fontmap uses for example.

Note that since Pango 1.32.6, the default fontmap is per-thread. Each thread gets its own default fontmap. In this way, PangoCairo can be used safely from multiple threads.

Returns:

the default PangoCairo fontmap for the current thread. This object is owned by Pango and must not be freed.

classmethod set_default(fontmap: PangoCairoFontMap | None = None) → None

Sets a default PangoCairoFontMap to use with Cairo.

This can be used to change the Cairo font backend that the default fontmap uses for example. The old default font map is unreffed and the new font map referenced.

Note that since Pango 1.32.6, the default fontmap is per-thread. This function only changes the default fontmap for the current thread. Default fontmaps of existing threads are not changed. Default fontmaps of any new threads will still be created using pango_cairo_font_map_new().

A value of None for fontmap will cause the current default font map to be released and a new default font map to be created on demand, using pango_cairo_font_map_new().

Returns:

the pango-cairo font map.

classmethod from_cairo_font_type(cairo_font_type_pointer: _CDataBase) → PangoCairoFontMap

Instantiates a PangoCairoFontMap from a Cairo context.

Returns:

the pango-cairo font map.

get_cairo_font_type_pointer() → _CDataBase

Returns the pointer to the type of Cairo font backend that fontmap uses

Returns:

the pointer to the cairo_font_type_t.

property resolution: float

The resolution for the fontmap in “dots per inch”. This is a scale factor between points specified in a Pango FontDescription and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3). (Physical inches aren’t actually involved; the terminology is conventional.)

create_context() → Context

Creates a Pango Context connected to fontmap. This is equivalent to pango.Context() followed by context.set_font_map().

Returns:

the newly allocated Pango Context.