Python API reference¶
Creating and updating Pango objects from Cairo¶
Contexts¶
-
pangocairocffi.
create_context
(cairo_context: cairocffi.context.Context) → pangocffi.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 withcairo_context
and do not need to access PangoContext directly, you can usecreate_layout()
instead.Parameters: cairo_context – a Cairo context Returns: a Pango context
-
pangocairocffi.
update_context
(cairo_context: cairocffi.context.Context, pango_context: pangocffi.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: cairocffi.context.Context) → pangocffi.layout.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 likeshow_layout()
. If you change the transformation or target surface forcairo_context
, you need to callupdate_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: cairocffi.context.Context, layout: pangocffi.layout.Layout) → None¶ Updates the private Pango
Context
of a PangoLayout
created withcreate_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: cairocffi.context.Context, layout: pangocffi.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: cairocffi.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: cairocffi.context.Context, text: str, glyph_item: pangocffi.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 toshow_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 byglyph_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: cairocffi.context.Context, layout: pangocffi.layout.Layout) → None¶ Adds the text in a
Pango.Layout
to the current path in the specified cairo context. The top-left corner of thePango.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: cairocffi.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: pangocffi.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: pangocffi.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: pangocffi.context.Context, options: Optional[_cffi_backend._CDataBase]) → 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: pangocffi.context.Context) → Optional[_cffi_backend._CDataBase]¶ 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.__init__
Creates a new PangoCairoFontMap object; afontmap
is used to cache information about available fonts, and holds certain global parameters such as the resolution. In most cases, you can usePangoCairoFontMap.get_default()
instead.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
andPangoCairoFontMap
interfaces on the returned object.You can override the type of backend returned by using an environment variable
PANGOCAIRO_BACKEND
. Supported types, based on your build, are fc (fontconfig), win32, and coretext. If requested type is not available, NULL is returned. I.E. this is only useful for testing, when at least two backends are compiled in.-
pointer
¶ Returns the pointer to the font map
Returns: the pointer to the font map.
-
classmethod
from_pointer
(pointer: _cffi_backend._CDataBase) → pangocairocffi.font_map.PangoCairoFontMap¶ Instantiates a
PangoCairoFontMap
from a pointer.Returns: the pango-cairo font map.
-
classmethod
get_default
() → pangocairocffi.font_map.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: Optional[PangoCairoFontMap] = 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, usingpango_cairo_font_map_new()
.Returns: the pango-cairo font map.
-
classmethod
from_cairo_font_type
(cairo_font_type_pointer: _cffi_backend._CDataBase) → pangocairocffi.font_map.PangoCairoFontMap¶ Instantiates a
PangoCairoFontMap
from a Cairo context.Returns: the pango-cairo font map.
-
get_cairo_font_type_pointer
() → _cffi_backend._CDataBase¶ Returns the pointer to the type of Cairo font backend that
fontmap
usesReturns: the pointer to the cairo_font_type_t
.
-
resolution
¶ 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
() → pangocffi.context.Context¶ Creates a Pango
Context
connected tofontmap
. This is equivalent topango.Context()
followed bycontext.set_font_map()
.Returns: the newly allocated Pango Context
.
-