pangocairocffi

https://pangocairocffi.readthedocs.io/en/latest/
Admin
pangocairocffi is a CFFI-based set of Python bindings for Cairo rendering methods with Pango,...
Tokens:7,060
Snippets:60
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Basic usage of pangocairocffi with cairocffi and pangocffi

Source: https://pangocairocffi.readthedocs.io/en/latest/_sources/overview.rst.txt

Rough example showing how to use pangocairocffi together with pangocffi and cairocffi to create a PDF with a centered layout and markup text. It creates a PDFSurface, builds a layout, applies markup, renders it, and finishes the surface.

```python
import cairocffi
import pangocffi
import pangocairocffi

# Create the surface and get the context
filename = 'test.pdf'
pt_per_mm = 72 / 25.4
width, height = 210 * pt_per_mm, 297 * pt_per_mm  # A4 portrait
surface = cairocffi.PDFSurface(filename, width, height)
context = cairocffi.Context(surface)

context.translate(0, height / 2)

# Build the layout
layout = pangocairocffi.create_layout(context)
layout.width = pangocffi.units_from_double(width)
layout.alignment = pangocffi.Alignment.CENTER
layout.apply_markup('<span font="italic 30">Hi from Παν語</span>')

# Render the layout
pangocairocffi.show_layout(context, layout)

# Output the surface
surface.finish()
```

--------------------------------

### Install pangocairocffi with pip

Source: https://pangocairocffi.readthedocs.io/en/latest/_sources/overview.rst.txt

Install the pangocairocffi package using pip. Python versions < 3.10 are not supported.

```bash
pip install pangocairocffi
```

--------------------------------

### OSError when PangoCairo fails to load

Source: https://pangocairocffi.readthedocs.io/en/latest/_sources/overview.rst.txt

Example exception shown when pangocairocffi fails to find the PangoCairo shared library. If PangoCairo is not installed as a shared library, specify a path via the PANGOCAIRO_LOCATION environment variable.

```text
OSError: dlopen() failed to load pangocairo: pangocairo-1.0 / pangocairo-1.0.0
```

--------------------------------

### PangoCairoFontMap.get_default()

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Gets the default PangoCairoFontMap to use with Cairo. The type of the returned object depends on the Cairo font backend, and the default fontmap is per-thread since Pango 1.32.6.

```APIDOC
## PangoCairoFontMap.get_default()

### Description
Gets a default PangoCairoFontMap to use with Cairo. The type of the returned object depends on the particular font backend Cairo was compiled to use. The default Cairo fontmap can be changed using set_default(). Since Pango 1.32.6, the default fontmap is per-thread.

### Method
classmethod

### Endpoint
PangoCairoFontMap.get_default()

### Parameters
None

### Returns
- **PangoCairoFontMap** - The default PangoCairo fontmap for the current thread. This object is owned by Pango and must not be freed.
```

--------------------------------

### PangoCairoFontMap.from_pointer()

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Instantiates a PangoCairoFontMap from a pointer.

```APIDOC
## PangoCairoFontMap.from_pointer()

### Description
Instantiates a PangoCairoFontMap from a pointer.

### Method
classmethod

### Endpoint
PangoCairoFontMap.from_pointer()

### Parameters
- **pointer** (_CDataBase) - Required - The pointer to the font map.

### Returns
- **PangoCairoFontMap** - The pango-cairo font map.
```

--------------------------------

### PangoCairoFontMap.create_context()

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Creates a Pango Context connected to the font map. This is equivalent to calling pango.Context() followed by context.set_font_map().

```APIDOC
## PangoCairoFontMap.create_context()

### Description
Creates a Pango Context connected to the font map. This is equivalent to pango.Context() followed by context.set_font_map().

### Method
instance method

### Endpoint
PangoCairoFontMap.create_context()

### Parameters
None

### Returns
- **Context** - The newly allocated Pango Context.
```

--------------------------------

### pangocairocffi.show_layout

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Draws a Pango Layout in the specified cairo context.

```APIDOC
## pangocairocffi.show_layout(cairo_context: Context, layout: Layout) -> None

### Description
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.

### Method
Function call

### Signature
`pangocairocffi.show_layout(cairo_context: Context, layout: Layout) -> None`

### Parameters
- **cairo_context** (Context) - Required - a Cairo context
- **layout** (Layout) - Required - a Pango layout

### Return Value
None
```

--------------------------------

### create_layout(cairo_context: Context) -> Layout

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

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().

```APIDOC
## create_layout(cairo_context: Context) -> Layout

### Description
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.

### Parameters
- **cairo_context** (Context) - Required - A Cairo context.

### Returns
- **Layout** - A Pango layout.
```

--------------------------------

### PangoCairoFontMap.from_cairo_font_type()

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Instantiates a PangoCairoFontMap from a Cairo context.

```APIDOC
## PangoCairoFontMap.from_cairo_font_type()

### Description
Instantiates a PangoCairoFontMap from a Cairo context.

### Method
classmethod

### Endpoint
PangoCairoFontMap.from_cairo_font_type()

### Parameters
- **cairo_font_type_pointer** (_CDataBase) - Required - The pointer to the Cairo font type.

### Returns
- **PangoCairoFontMap** - The pango-cairo font map.
```

--------------------------------

### Import pangocairocffi as pangocairo

Source: https://pangocairocffi.readthedocs.io/en/latest/_sources/overview.rst.txt

Import the pangocairocffi module, optionally aliasing it as pangocairo. The module dynamically loads PangoCairo as a shared library upon importing.

```python
import pangocairocffi as pangocairo
```

--------------------------------

### pangocairocffi.layout_path

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Adds the text in a Pango Layout to the current path in the specified cairo context.

```APIDOC
## pangocairocffi.layout_path(cairo_context: Context, layout: Layout) -> None

### Description
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.

### Method
Function call

### Signature
`pangocairocffi.layout_path(cairo_context: Context, layout: Layout) -> None`

### Parameters
- **cairo_context** (Context) - Required - a Cairo context
- **layout** (Layout) - Required - a Pango layout

### Return Value
None
```

--------------------------------

### pangocairocffi.error_underline_path

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Adds a squiggly underline path to the current path in the specified cairo context.

```APIDOC
## pangocairocffi.error_underline_path(cairo_context: Context, x: float, y: float, width: float, height: float) -> None

### Description
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)

### Method
Function call

### Signature
`pangocairocffi.error_underline_path(cairo_context: Context, x: float, y: float, width: float, height: float) -> None`

### Parameters
- **cairo_context** (Context) - Required - a Cairo context
- **x** (float) - Required - The X coordinate of one corner of the rectangle
- **y** (float) - Required - The Y coordinate of one corner of the rectangle
- **width** (float) - Required - Non-negative width of the rectangle
- **height** (float) - Required - Non-negative height of the rectangle

### Return Value
None
```

--------------------------------

### create_context(cairo_context: Context) -> Context

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

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

```APIDOC
## create_context(cairo_context: Context) -> Context

### Description
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** (Context) - Required - A Cairo context.

### Returns
- **Context** - A Pango context.
```

--------------------------------

### update_layout(cairo_context: Context, layout: Layout) -> None

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

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.

```APIDOC
## update_layout(cairo_context: Context, layout: Layout) -> None

### Description
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** (Context) - Required - A Cairo context.
- **layout** (Layout) - Required - A Pango layout.

### Returns
- **None** - This function does not return a value.
```

--------------------------------

### PangoCairoFontMap.pointer property

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Returns the pointer to the font map.

```APIDOC
## PangoCairoFontMap.pointer property

### Description
Returns the pointer to the font map.

### Property
pointer

### Returns
- **_CDataBase** - The pointer to the font map.
```

--------------------------------

### set_font_options

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Sets font rendering options for the Pango context, overriding options derived from the target surface.

```APIDOC
## set_font_options

### Description
Sets the font options used when rendering text with the given context, overriding derived options.

### Parameters
- **context** (Context) - Required - A Pango context
- **options** (_CDataBase | None) - Required - A cairo_font_options_t pointer or `None` to unset any previously set options.

### Return Value
None
```

--------------------------------

### set_resolution

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Sets the resolution for the Pango context in dots per inch, affecting how text is scaled to Cairo units.

```APIDOC
## set_resolution

### Description
Sets the resolution for the Pango context. This is a scale factor between points specified in a PangoFontDescription and Cairo units.

### Method
Set resolution

### Parameters
- **context** (Context) - Required - A Pango context
- **dpi** (float) - Required - The resolution in "dots per inch". A 0 or negative value means to use the resolution from the font map.

### Return Value
None
```

--------------------------------

### pangocairocffi.show_error_underline

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Draws a squiggly underline in the specified cairo context to indicate a spelling error.

```APIDOC
## pangocairocffi.show_error_underline(cairo_context: Context, x: float, y: float, width: float, height: float) -> None

### Description
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)

### Method
Function call

### Signature
`pangocairocffi.show_error_underline(cairo_context: Context, x: float, y: float, width: float, height: float) -> None`

### Parameters
- **cairo_context** (Context) - Required - a Cairo context
- **x** (float) - Required - The X coordinate of one corner of the rectangle
- **y** (float) - Required - The Y coordinate of one corner of the rectangle
- **width** (float) - Required - Non-negative width of the rectangle
- **height** (float) - Required - Non-negative height of the rectangle

### Return Value
None
```

--------------------------------

### update_context(cairo_context: Context, pango_context: Context) -> None

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

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.

```APIDOC
## update_context(cairo_context: Context, pango_context: Context) -> None

### Description
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** (Context) - Required - A Cairo context.
- **pango_context** (Context) - Required - A Pango context, from a pango-cairo font map.

### Returns
- **None** - This function does not return a value.
```

--------------------------------

### get_font_options

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Retrieves any font rendering options that were previously set on the context, not including derived options.

```APIDOC
## get_font_options

### Description
Retrieves any font rendering options previously set on the Pango context.

### Parameters
- **context** (Context) - Required - A Pango context

### Return Value
_CDataBase | None - A cairo_font_options_t pointer previously set on the context, or `None` if none has been set.
```

--------------------------------

### PangoCairoFontMap.set_default()

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Sets a default PangoCairoFontMap to use with Cairo. This can change the Cairo font backend used by the default fontmap. The old default font map is unreffed and the new one referenced. Since Pango 1.32.6, this only affects the current thread.

```APIDOC
## PangoCairoFontMap.set_default()

### Description
Sets a default PangoCairoFontMap to use with Cairo. This can be used to change the Cairo font backend that the default fontmap uses. The old default font map is unreffed and the new font map referenced. Since Pango 1.32.6, this function only changes the default fontmap for the current thread.

### Method
classmethod

### Endpoint
PangoCairoFontMap.set_default()

### Parameters
- **fontmap** (PangoCairoFontMap | None) - Optional - The new default font map, or None to release the current default and create a new one on demand.

### Returns
- **None** - This method returns None.
```

--------------------------------

### pangocairocffi.show_glyph_item

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Draws the glyphs in a glyph item in the specified cairo context.

```APIDOC
## pangocairocffi.show_glyph_item(cairo_context: Context, text: str, glyph_item: GlyphItem) -> None

### Description
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`.

### Method
Function call

### Signature
`pangocairocffi.show_glyph_item(cairo_context: Context, text: str, glyph_item: GlyphItem) -> None`

### Parameters
- **cairo_context** (Context) - Required - a Cairo context
- **text** (str) - Required - the UTF-8 text that `glyph_item` refers to
- **glyph_item** (GlyphItem) - Required - a Pango glyph item

### Return Value
None
```

--------------------------------

### get_resolution

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Retrieves the resolution that has been set on the Pango context, returning a negative value if not previously set.

```APIDOC
## get_resolution

### Description
Returns the resolution for the Pango context in "dots per inch".

### Parameters
- **context** (Context) - Required - A Pango context

### Return Value
float - The resolution in "dots per inch". A negative value is returned if no resolution has been set.
```

--------------------------------

### PangoCairoFontMap.get_cairo_font_type_pointer()

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

Returns the pointer to the type of Cairo font backend that the font map uses.

```APIDOC
## PangoCairoFontMap.get_cairo_font_type_pointer()

### Description
Returns the pointer to the type of Cairo font backend that the font map uses.

### Method
instance method

### Endpoint
PangoCairoFontMap.get_cairo_font_type_pointer()

### Parameters
None

### Returns
- **_CDataBase** - The pointer to the cairo_font_type_t.
```

--------------------------------

### PangoCairoFontMap.resolution property

Source: https://pangocairocffi.readthedocs.io/en/latest/modules.html

The resolution for the font map in dots per inch. This is a scale factor between points specified in a Pango FontDescription and Cairo units. The default value is 96.

```APIDOC
## PangoCairoFontMap.resolution property

### Description
The resolution for the font map in dots per inch. This is a scale factor between points specified in a Pango FontDescription and Cairo units. The default value is 96.

### Property
resolution

### Type
float

### Returns
- **float** - The resolution in dots per inch.
```
Tokens:
Raw